Skip to content

title_storage

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

Title Storage

Epic Online Services Interface: Title Storage Interface

The Title Storage Interface enables developers using Epic Online Services (EOS) to retrieve encrypted data from cloud servers. Data that you store through this interface is accessible to any user on any device where they can log in. While similar to the Player Data Storage, this interface is specialised to handle game-specific data rather than user-specific data, and can provide different versions of files based on the user's platform, region, or other conditions.

Functions

These functions are provided for handling title storage:

Structs

These are the structures used by this API:


Back To Top

EpicGames_TitleStorage_CopyFileMetadataAtIndex

Epic Online Services Function: EOS_TitleStorage_CopyFileMetadataAtIndex

This function gets the cached copy of a file's metadata by index. The metadata will be for the last retrieved version.

Note

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


Syntax:

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



Returns:

TitleFileMetadata


Example:

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

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



Back To Top

EpicGames_TitleStorage_CopyFileMetadataByFilename

Epic Online Services Function: EOS_TitleStorage_CopyFileMetadataByFilename

This function creates a 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_TitleStorage_QueryFileList to store values in cache.


Syntax:

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



Returns:

TitleFileMetadata


Example:

var _struct = EpicGames_TitleStorage_CopyFileMetadataByFilename(userID, i);
if(_struct.status == EpicGames_Success)
{
    Filename = _struct.Filename;
}

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



Back To Top

EpicGames_TitleStorage_DeleteCache

Epic Online Services Function: EOS_TitleStorage_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. 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_TitleStorage_DeleteCache(userID)
Argument Type Description
userID String Product User ID of the local user who is deleting his cache (optional)



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String The string "EpicGames_TitleStorage_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_TitleStorage_DeleteCache(userID);

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

if (async_load[? "type"] == "EpicGames_TitleStorage_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_TitleStorage_GetFileMetadataCount

Epic Online Services Function: EOS_TitleStorage_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_TitleStorage_QueryFileList to store values in cache.


Syntax:

EpicGames_TitleStorage_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_TitleStorage_GetFileMetadataCount(userID);
for(var i = 0 ; i < _count ; i ++)
{
    var _struct = EpicGames_TitleStorage_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_TitleStorage_QueryFileList, the function EpicGames_TitleStorage_GetFileMetadataCount will return the number of entries in the query array which can then be accessed using the EpicGames_TitleStorage_CopyFileMetadataAtIndex function.



Back To Top

EpicGames_TitleStorage_QueryFile

Epic Online Services Function: EOS_TitleStorage_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.

Once a file has been queried, its metadata will be available by the EpicGames_TitleStorage_CopyFileMetadataAtIndex and EpicGames_TitleStorage_CopyFileMetadataByFilename 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_TitleStorage_QueryFile(userID, filename)
Argument Type Description
userID String Product User ID of the local user requesting file metadata
filename String The requested file's name



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String The string "EpicGames_TitleStorage_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_TitleStorage_QueryFile(userID, "myFile.dat");

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

if (async_load[? "type"] == "EpicGames_TitleStorage_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_TitleStorage_QueryFileList

Epic Online Services Function: EOS_TitleStorage_QueryFileList

This function queries the file metadata, such as file names, size, and a MD5 hash of the data, for all files available for current user based on their settings (such as game role) and tags provided. This is not required before a file can be downloaded by name.

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_TitleStorage_QueryFileList(userID, tag)
Argument Type Description
userID String Product User ID of the local user who requested file metadata
tag String List of tags to use for lookup, either a String (single tag) or an Array of strings (multiple tags)



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String The string "EpicGames_TitleStorage_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_TitleStorage_QueryFileList(userID, "Tag1");

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

if (async_load[? "type"] == "EpicGames_TitleStorage_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_TitleStorage_ReadFile

Epic Online Services Function: EOS_TitleStorage_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.

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_TitleStorage_ReadFile(userID, filename, path)
Argument Type Description
userID String 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 save the file



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String The string "EpicGames_TitleStorage_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_TitleStorage_ReadFile(userID, "Preferences.json", "/path/to/save/Preferences.json");

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

if (async_load[? "type"] == "EpicGames_TitleStorage_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_TitleStorageFileTransferRequest_CancelRequest

Epic Online Services Function: EOS_TitleStorageFileTransferRequest_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_TitleStorageFileTransferRequest_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 The string "EpicGames_TitleStorageFileTransferRequest_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_TitleStorageFileTransferRequest_CancelRequest("myFile.txt");

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

if (async_load[? "type"] == "EpicGames_TitleStorageFileTransferRequest_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

TitleFileMetadata

The player file metadata is represented by a struct and contains metadata information for a specific title 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
UnencryptedDataSizeBytes Real The size of data (payload) in file in unencrypted (original) form.

YoYoGames 2024

Clone this wiki locally