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.

These functions are provided for handling player data storage:

• eos_player_data_storage_copy_file_metadata_at_index
• eos_player_data_storage_copy_file_metadata_by_filename
• eos_player_data_storage_delete_cache
• eos_player_data_storage_delete_file
• eos_player_data_storage_duplicate_file
• eos_player_data_storage_get_file_metadata_count
• eos_player_data_storage_query_file
• eos_player_data_storage_query_file_list
• eos_player_data_storage_read_file
• eos_player_data_storage_write_file
• eos_player_data_storage_file_transfer_request_cancel_request

These are the constants used with player data storage:

• EOS_PLAYER_DATA_STORAGE_READ_RESULT
• EOS_PLAYER_DATA_STORAGE_WRITE_RESULT

These are the structures used by this API:

• PlayerFileMetadata

Back To Top

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 eos_player_data_storage_write_file.

Syntax:

eos_player_data_storage_copy_file_metadata_at_index(user_id, index)

Returns:

PlayerFileMetadata

Example:

var _count = eos_player_data_storage_get_file_metadata_count(user_id);
for(var i = 0 ; i < _count; i++)
{
    var _struct = eos_player_data_storage_copy_file_metadata_at_index(user_id, i);
    var _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

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.

Syntax:

eos_player_data_storage_copy_file_metadata_by_filename(user_id, filename)

Returns:

PlayerFileMetadata

Example:

var _struct = eos_player_data_storage_copy_file_metadata_by_filename(user_id, filename);
if(_struct.status == EOS_RESULT.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

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.

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:

eos_player_data_storage_delete_cache(user_id)

Returns:

Real

Triggers:

Social Async Event

Example:

identifier = eos_player_data_storage_delete_cache(user_id);

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

if (async_load[? "type"] == "eos_player_data_storage_delete_cache")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EOS_RESULT.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

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:

eos_player_data_storage_delete_file(user_id, filename)

Returns:

Real

Triggers:

Social Async Event

Example:

identifier = eos_player_data_storage_delete_file(user_id, "MyFilename.txt");

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

if (async_load[? "type"] == "eos_player_data_storage_delete_file")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EOS_RESULT.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

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 eos_player_data_storage_delete_file 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:

eos_player_data_storage_duplicate_file(user_id, source, destination)

Returns:

Real

Triggers:

Social Async Event

Example:

identifier = eos_player_data_storage_duplicate_file(user_id,"myNiceFile.dat", "myNiceFile2.dat");

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

if (async_load[? "type"] == "eos_player_data_storage_duplicate_file")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EOS_RESULT.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

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.

Syntax:

eos_player_data_storage_get_file_metadata_count(user_id)

Returns:

Real

Example:

var _count = eos_player_data_storage_get_file_metadata_count(user_id);
for (var i = 0 ; i < _count; i ++)
{
    var _struct = eos_player_data_storage_copy_file_metadata_at_index(user_id, i);
    var _filename = _struct.filename;
}

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

Back To Top

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:

• eos_player_data_storage_copy_file_metadata_at_index
• eos_player_data_storage_copy_file_metadata_by_filename

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:

eos_player_data_storage_query_file(user_id, filename)

Returns:

Real

Triggers:

Social Async Event

Example:

identifier = eos_player_data_storage_query_file(user_id, "myFile.txt");

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

if (async_load[? "type"] == "eos_player_data_storage_query_file")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EOS_RESULT.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

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 EOS_RESULT, it is possible to call one of the following functions:

• eos_player_data_storage_copy_file_metadata_at_index
• eos_player_data_storage_copy_file_metadata_by_filename
• eos_player_data_storage_get_file_metadata_count

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:

eos_player_data_storage_query_file_list(user_id)

Returns:

Real

Triggers:

Social Async Event

Example:

identifier = eos_player_data_storage_query_file_list(user_id);

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

if (async_load[? "type"] == "eos_player_data_storage_query_file_list")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EOS_RESULT.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

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:

eos_player_data_storage_read_file(user_id, filename, path)

Returns:

Real

Triggers:

Social Async Event

Example:

identifier = eos_player_data_storage_read_file(user_id, "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"] == "eos_player_data_storage_read_file")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EOS_RESULT.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

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:

eos_player_data_storage_write_file(user_id, filename, path)

Returns:

Real

Triggers:

Social Async Event

Example:

identifier = eos_player_data_storage_write_file(user_id, "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"] == "eos_player_data_storage_write_file")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EOS_RESULT.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

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:

eos_player_data_storage_file_transfer_request_cancel_request(filename)

Returns:

Real

Triggers:

Social Async Event

Example:

identifier = eos_player_data_storage_file_transfer_request_cancel_request("myFile.txt");

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

if (async_load[? "type"] == "eos_player_data_storage_file_transfer_request_cancel_request")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EOS_RESULT.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

This enum holds the return results for EOS_PlayerDataStorage_OnReadFileDataCallback callbacks to return.

Back To Top

This enum holds the return results for EOS_PlayerDataStorage_OnWriteFileDataCallback callbacks to return.

Back To Top

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:

• eos_player_data_storage_copy_file_metadata_at_index
• eos_player_data_storage_copy_file_metadata_by_filename