Skip to content

player_data_storage

Jump to bottom
Francisco Dias edited this page Jun 20, 2024 · 2 revisions

Player Data Storage

Epic Online Services Interface: Player Data Storage Interface

The Player Data Storage Interface enables developers using Epic Online Services (EOS) to save encrypted, user-specific, game-specific data to cloud servers. Data that you store through this interface is accessible to the user on any device where they can log in.

The Player Data Storage Interface supports any file format; typical use cases would include saved games and replay data.

Functions

These functions are provided for handling player data storage:

Structs

These are the structures used by this API:


Back To Top

EpicGames_PlayerDataStorage_CopyFileMetadataAtIndex

Epic Online Services Function: EOS_PlayerDataStorage_CopyFileMetadataAtIndex

This function gets the cached copy of a file's metadata by index. The metadata will be for the last retrieved or successfully saved version, and will not include any local changes that have not been committed by calling EpicGames_PlayerDataStorage_WriteFile.

Note

Requires a previous call to EpicGames_PlayerDataStorage_QueryFileList to store values in cache.


Syntax:

EpicGames_PlayerDataStorage_CopyFileMetadataAtIndex(userID, index)
Argument Type Description
userID String The Product User ID of the local user who is requesting file metadata
index Real The index to get metadata for



Returns:

PlayerFileMetadata


Example:

var _count = EpicGames_PlayerDataStorage_GetFileMetadataCount(userID);
for(var i = 0 ; i < _count; i++)
{
    var _struct = EpicGames_PlayerDataStorage_CopyFileMetadataAtIndex(userID, i);
    Filename = _struct.Filename;
}

The above code shows an example of how the function should be used. The player file metadata is returned providing an index.



Back To Top

EpicGames_PlayerDataStorage_CopyFileMetadataByFilename

Epic Online Services Function: EOS_PlayerDataStorage_CopyFileMetadataByFilename

This function creates the cached copy of a file's metadata by filename. The metadata will be for the last retrieved or successfully saved version, and will not include any changes that have not completed writing.

Note

Requires a previous call to EpicGames_PlayerDataStorage_QueryFileList to store values in cache.


Syntax:

EpicGames_PlayerDataStorage_CopyFileMetadataByFilename(userID, filename)
Argument Type Description
userID String The Product User ID of the local user who is requesting file metadata
filename String The file's name to get metadata for



Returns:

PlayerFileMetadata


Example:

var _struct = EpicGames_PlayerDataStorage_CopyFileMetadataByFilename(userID, filename);
if(_struct.status == EpicGames_Success)
{
    var _filename = _struct.Filename;
}

The above code shows an example of how the function should be used. The player file metadata is returned for a provided filename.



Back To Top

EpicGames_PlayerDataStorage_DeleteCache

Epic Online Services Function: EOS_PlayerDataStorage_DeleteCache

This function clears previously cached file data. This operation will be done asynchronously. All cached files except those corresponding to the transfers in progress will be removed.

Warning

Use this with care. The cache system generally tries to clear old and unused cached files from time to time. Unnecessarily clearing the cache can degrade performance as the SDK will have to re-download data.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

EpicGames_PlayerDataStorage_DeleteCache(userID)
Argument Type Description
userID String Product User ID of the local user who is deleting his cache



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String "EpicGames_PlayerDataStorage_DeleteCache"
status EpicGames_Result The status code for the operation. EpicGames_Success indicates that the operation succeeded; other codes indicate errors
status_message String Text representation of the status code
identifier Real The asynchronous listener ID.

Example:

identifier = EpicGames_PlayerDataStorage_DeleteCache(userID);

The code sample above saves the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "EpicGames_PlayerDataStorage_DeleteCache")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EpicGames_Success)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
         show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.



Back To Top

EpicGames_PlayerDataStorage_DeleteFile

Epic Online Services Function: EOS_PlayerDataStorage_DeleteFile

This function deletes an existing file in the cloud. If successful, the file's data will be removed from our local cache.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

EpicGames_PlayerDataStorage_DeleteFile(userID, filename)
Argument Type Description
userID String The Product User ID of the local user who authorizes deletion of the file; must be the file's owner
filename String The name of the file to delete



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String "EpicGames_PlayerDataStorage_DeleteFile"
status EpicGames_Result The status code for the operation. EpicGames_Success indicates that the operation succeeded; other codes indicate errors
status_message String Text representation of the status code
identifier Real The asynchronous listener ID.

Example:

identifier = EpicGames_PlayerDataStorage_DeleteFile(userID, "MyFilename.txt");

The code sample above saves the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "EpicGames_PlayerDataStorage_DeleteFile")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EpicGames_Success)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
         show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.



Back To Top

EpicGames_PlayerDataStorage_DuplicateFile

Epic Online Services Function: EOS_PlayerDataStorage_DuplicateFile

This function copies the data of an existing file to a new filename. This action happens entirely on the server and will not upload the contents of the source destination file from the host. This function paired with a subsequent EpicGames_PlayerDataStorage_DeleteFile can be used to rename a file. If successful, the destination file's metadata will be updated in our local cache.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

EpicGames_PlayerDataStorage_DuplicateFile(userID, source, destination)
Argument Type Description
userID String The Product User ID of the local user who authorized the duplication of the requested file; must be the original file's owner
source String The name of the existing file to duplicate
destination String The name of the new file



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String "EpicGames_PlayerDataStorage_DuplicateFile"
status EpicGames_Result The status code for the operation. EpicGames_Success indicates that the operation succeeded; other codes indicate errors
status_message String Text representation of the status code
identifier Real The asynchronous listener ID.

Example:

identifier = EpicGames_PlayerDataStorage_DuplicateFile(userID,"myNiceFile.dat", "myNiceFile2.dat");

The code sample above saves the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "EpicGames_PlayerDataStorage_DuplicateFile")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EpicGames_Success)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
         show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.



Back To Top

EpicGames_PlayerDataStorage_GetFileMetadataCount

Epic Online Services Function: EOS_PlayerDataStorage_GetFileMetadataCount

This function gets the count of files we have previously queried information for and files we have previously read from / written to.

Note

Requires a previous call to EpicGames_PlayerDataStorage_QueryFileList to store values in cache.


Syntax:

EpicGames_PlayerDataStorage_GetFileMetadataCount(userID)
Argument Type Description
userID String The Product User ID of the local user who is requesting file metadata



Returns:

Real


Example:

var _count = EpicGames_PlayerDataStorage_GetFileMetadataCount(userID);
for (var i = 0 ; i < _count; i ++)
{
    var _struct = EpicGames_PlayerDataStorage_CopyFileMetadataAtIndex(userID, i);
    Filename = _struct.Filename;
}

The above code shows an example of how the function should be used. After a successful call to EpicGames_PlayerDataStorage_QueryFileList, the function EpicGames_PlayerDataStorage_GetFileMetadataCount will return the number of entries in the query array which can then be accessed using the EpicGames_PlayerDataStorage_CopyFileMetadataAtIndex function.



Back To Top

EpicGames_PlayerDataStorage_QueryFile

Epic Online Services Function: EOS_PlayerDataStorage_QueryFile

This function queries a specific file's metadata, such as file names, size, and a MD5 hash of the data. This is not required before a file may be opened, saved, copied, or deleted.

Once a file has been queried, its metadata will be available by the one of the following functions:

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

EpicGames_PlayerDataStorage_QueryFile(userID, filename)
Argument Type Description
userID String The Product User ID of the local user requesting file metadata
filename String The name of the file being queried



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String "EpicGames_PlayerDataStorage_QueryFile"
status EpicGames_Result The status code for the operation. EpicGames_Success indicates that the operation succeeded; other codes indicate errors
status_message String Text representation of the status code
identifier Real The asynchronous listener ID.

Example:

identifier = EpicGames_PlayerDataStorage_QueryFile(userID, "myFile.txt");

The code sample above saves the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "EpicGames_PlayerDataStorage_QueryFile")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EpicGames_Success)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
        show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.



Back To Top

EpicGames_PlayerDataStorage_QueryFileList

Epic Online Services Function: EOS_PlayerDataStorage_QueryFileList

This function queries the file metadata, such as file names, size, and a MD5 hash of the data, for all files owned by this user for this application. This is not required before a file may be opened, saved, copied, or deleted. Once the callback has been fired with a successful EpicGames_Result, it is possible to call one of the following functions:

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

EpicGames_PlayerDataStorage_QueryFileList(userID)
Argument Type Description
userID String The Product User ID of the local user who requested file metadata



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String "EpicGames_PlayerDataStorage_QueryFileList"
status EpicGames_Result The status code for the operation. EpicGames_Success indicates that the operation succeeded; other codes indicate errors
status_message String Text representation of the status code
identifier Real The asynchronous listener ID.

Example:

identifier = EpicGames_PlayerDataStorage_QueryFileList(userID);

The code sample above saves the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "EpicGames_PlayerDataStorage_QueryFileList")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EpicGames_Success)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
        show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.



Back To Top

EpicGames_PlayerDataStorage_ReadFile

Epic Online Services Function: EOS_PlayerDataStorage_ReadFile

This function retrieves the contents of a specific file, potentially downloading the contents if we do not have a local copy, from the cloud. This request will occur asynchronously, potentially over multiple frames. All callbacks for this function will come from the same thread that the SDK is ticked from. If specified, the FileTransferProgressCallback will always be called at least once if the request is started successfully.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

EpicGames_PlayerDataStorage_ReadFile(userID, filename, path)
Argument Type Description
userID String The Product User ID of the local user who is reading the requested file
filename String The file name to read; this file must already exist
path String local path where to save the file



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String "EpicGames_PlayerDataStorage_ReadFile"
status EpicGames_Result The status code for the operation. EpicGames_Success indicates that the operation succeeded; other codes indicate errors
status_message String Text representation of the status code
identifier Real The asynchronous listener ID.

Example:

identifier = EpicGames_PlayerDataStorage_ReadFile(userID, "MyFavPic.png", "path/to/save/MyFavPic.png");

The code sample above saves the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "EpicGames_PlayerDataStorage_ReadFile")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EpicGames_Success)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
         show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.



Back To Top

EpicGames_PlayerDataStorage_WriteFile

Epic Online Services Function: EOS_PlayerDataStorage_WriteFile

This function writes new data to a specific file, potentially overwriting any existing file by the same name, to the cloud. This request will occur asynchronously, potentially over multiple frames. All callbacks for this function will come from the same thread that the SDK is ticked from. If specified, the FileTransferProgressCallback will always be called at least once if the request is started successfully.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

EpicGames_PlayerDataStorage_WriteFile(userID, filename, path)
Argument Type Description
userID String The Product User ID of the local user who is writing the requested file to the cloud
filename String The name of the file to write; if this file already exists, the contents will be replaced if the write request completes successfully.
path String Local path of the file to upload



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String "EpicGames_PlayerDataStorage_WriteFile"
status EpicGames_Result The status code for the operation. EpicGames_Success indicates that the operation succeeded; other codes indicate errors
status_message String Text representation of the status code
identifier Real The asynchronous listener ID.

Example:

identifier = EpicGames_PlayerDataStorage_WriteFile(userID, "myData.dat", "/path/to/file/myData.dat");

The code sample above saves the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "EpicGames_PlayerDataStorage_WriteFile")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EpicGames_Success)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
         show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.



Back To Top

EpicGames_PlayerDataStorageFileTransferRequest_CancelRequest

Epic Online Services Function: EOS_PlayerDataStorageFileTransferRequest_CancelRequest

This function attempts to cancel this file request in progress. This is a best-effort command and is not guaranteed to be successful if the request has completed before this function is called.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

EpicGames_PlayerDataStorageFileTransferRequest_CancelRequest(filename)
Argument Type Description
filename String Filename contained in the process to cancel



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String "EpicGames_PlayerDataStorageFileTransferRequest_CancelRequest"
status EpicGames_Result The status code for the operation. EpicGames_Success indicates that the operation succeeded; other codes indicate errors
status_message String Text representation of the status code
identifier Real The asynchronous listener ID

Example:

identifier = EpicGames_PlayerDataStorageFileTransferRequest_CancelRequest("myFile.txt");

The code sample above saves the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "EpicGames_PlayerDataStorageFileTransferRequest_CancelRequest")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EpicGames_Success)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
        show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.



Back To Top

PlayerFileMetadata

The player file metadata is represented by a struct and contains metadata information for a specific player file.

This struct is referenced by the following functions:


Member Type Description
FileSizeBytes Real The total size of the file in bytes (includes the file header in addition to the file contents)
MD5Hash String The MD5 Hash of the entire file (including additional file header), in hex digits
Filename String The file's name
LastModifiedTime Real The POSIX timestamp when the file was saved last time.
UnencryptedDataSizeBytes Real The size of data (payload) in file in unencrypted (original) form.

YoYoGames 2024

Clone this wiki locally