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 Interface, this interface is specialized 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. For more specific information about the differences between the Title Storage Interface and the Player Data Storage Interface, see the Differences from Player Data Storage section at the bottom of this document.
To access the Title Storage Interface, acquire an
EOS_HTitleStorage handle through the Platform Interface function,
EOS_Platform_GetTitleStorageInterface. All Title Storage Interface functions require this handle as their first parameter. You must ensure that the
EOS_HPlatform handle is ticking in order for callbacks to trigger when requests are completed.
To use this interface, you must initialize the EOS Platform with the following extra parameters:
const char* EncryptionKey: This 64-character hexadecimal string builds a 256-bit key that EOS uses to encrypt user data. Epic's backend servers do not store this key. If there is no key, calls to file-management functions from the Title Storage Interface will result in failure and will return the
const char* CacheDirectory: This is the full path to the local directory that the interface will use for temporary storage during data file transfers. This could be any location, with the system's temporary directory or the game's data directory being common choices. If the directory you specify does not exist, EOS will attempt to create it. You can use the same directory for multiple users and products, and EOS will ensure that they do not collide. If there are issues with the directory, calls to file-management functions will result in failure and will return
EOS_CacheDirectoryInvaliderror codes. Please refer to the EOS Platform documentation for platform-specific limitations on what folders can be used.
File Name Format
File names in EOS take the following form:
The "Directory" and "Extension" portions are optional. The "/" character must appear after each directory name, but cannot appear anywhere else, including as the first or last character. File names may use the following characters:
- Any alphanumeric ASCII character
File names may not exceed
EOS_TITLESTORAGE_FILENAME_MAX_LENGTH_BYTES (64) characters.
The EOS SDK enables you to retrieve information about files stored on the cloud through a few querying API calls. Your query will return metadata about one or more files, including each file's name, size (in bytes), and MD5 hash. You can then request and manage your own copy of this metadata, and use it to access or modify the files. Because files are stored in encrypted form on the backend, metadata such as file size and MD5 hash reflects the encrypted file, rather than the original file you uploaded through the Dev Portal.
Be sure to copy any information you may need from the cache during your query's callback function. This data's lifetime is not guaranteed to last beyond the duration of the callback function. This is especially important when running multiple queries, as each successful query can alter the contents of the cache.
Most functions contain an optional Product User ID parameter for better tracking. You can query data with no Product User ID (by passing nullptr instead), but the User ID overrides you set up on the Dev Portal will not be available. Callbacks contain the same User Product ID value you pass
Querying a Single File
If you only need information about a single file, and you know that file's name, you can call
EOS_TitleStorage_QueryFile function, passing in an
EOS_TitleStorage_QueryFileOptions structure initialized as follows:
|(Optional) The |
|The name of the file you are querying|
When the operation completes, EOS will run your callback (of type
EOS_TitleStorage_OnQueryFileCompleteCallback) with an
EOS_TitleStorage_QueryFileCallbackInfo structure. If the call succeeded, EOS now has data about your file in the cache.
Querying Multiple Files by Tag
To query multiple files at once, or to query files without knowing the exact file names, you must first apply tags to your files through the Dev Portal. The EOS SDK can then query files based on those tags. File tags are strings that use the same formatting rules as EOS file names. When querying files this way, you must provide one or more tags, and the EOS SDK will retrieve a list of all files that contain at least one of the tags. To do this, call
EOS_TitleStorage_QueryFileList with an
EOS_TitleStorage_QueryFileListOptions data structure initialized as follows:
|(Optional) The |
|The number of tags in the list of tags (has to be positive)|
|The array of tags (ASCII strings) you are querying files for|
Upon completion, EOS will run your callback function (of type
EOS_TitleStorage_OnQueryFileListCompleteCallback) with an
EOS_TitleStorage_QueryFileListCallbackInfo data structure. If the call succeeded, the data structure contains the number of files found, and the information about those files is available in the EOS cache.
Querying All Files
The Title Storage Interface does not provide a specific API call to query all files. However, if you apply a certain tag to every file you upload, you could use
EOS_TitleStorage_QueryFileListOptions with that tag to retrieve data about all of your files.
Examining Cached File Information
Once EOS has retrieved and cached information about one or more files, you can retrieve information on a specific file by calling
EOS_TitleStorage_CopyFileMetadataByFilename with the name of the file, or by calling
EOS_TitleStorage_CopyFileMetadataAtIndex with the file's zero-based index within the cache. If you need to know how many files are in the cache, you can call
EOS_TitleStorage_GetFileMetadataCount. Once you no longer need your copy of this information, release the memory it was using by calling
After querying EOS for information about a single file,
EOS_TitleStorage_GetFileMetadataCount may reveal that the cache holds multiple files. This can happen when results from previous queries remain in the cache. In these cases, the best practice is to check that the
ResultCode within your
EOS_Success, and to call
EOS_TitleStorage_CopyFileMetadataByFilename to access its information. Previously cached metadata is removed on successful multiple-file query.
The Title Storage Interface supports reading files from the cloud asynchronously. Reading is a streaming operation, and EOS provides handles that you can use to check a stream's progress, or throttle or interrupt it.
Reading a File
To read a file from the cloud (or your local cache) with a known name, call
EOS_TitleStorage_ReadFile. You will need to pass in an
EOS_TitleStorage_ReadFileOptions initialized as follows:
|(Optional) The Account ID of the local user who is reading the requested file|
|The name of the file to read|
|The maximum amount of data to read in a single |
|Callback function that handles data as it comes in, and can stop the transfer early|
|Optional callback function to inform you of transfer progress; will be called at least once if set|
This function returns an
EOS_HTitleStorageFileTransferRequest handle that you can use to check the progress of the transfer, get the name of the file, or cancel the transfer. At any time during the transfer, call
EOS_TitleStorageFileTransferRequest_GetFileRequestState to poll its current state,
EOS_TitleStorageFileTransferRequest_GetFilename to check the name of the file being transferred, or
EOS_TitleStorageFileTransferRequest_CancelRequest to cancel it (without generating an error). If you prefer to receive updates from EOS rather than polling the transfer directly, provide a valid
EOS_TitleStorage_OnFileTransferProgressCallback function when initiating the transfer (as the
FileTransferProgressCallback parameter), and EOS will call it (with an
EOS_TitleStorage_FileTransferProgressCallbackInfo parameter) periodically inform you of the progress of the file transfer. If you choose this route, you are guaranteed to receive at least one call to your callback function. Using the callback function does not preclude using the handle, though they serve very similar purposes and most use cases will not require both.
When a chunk of the file comes through, your
ReadFileDataCallback (of type
EOS_TitleStorage_OnReadFileDataCallback) will run with a parameter of type
EOS_TitleStorage_ReadFileDataCallbackInfo. This structure includes a chunk of the actual data from the file, as well as a variable indicating whether or not this is the last chunk. It also has an enumerated return type,
EOS_TitleStorage_EReadResult, which you can use to instruct EOS to continue the transfer, end it due to an error, or cancel it without reporting an error.
Once the file transfer has completed, EOS will run your
EOS_TitleStorage_OnReadFileCompleteCallback callback function with an
EOS_TitleStorage_ReadFileCallbackInfo parameter. This parameter indicates success or failure and includes the name of the file.
EOS may cache files locally to speed