Title Storage Interface

用于从云下载所有玩家共享的加密数据的界面

阅读时间10分钟

通过 Title保管界面(Title Storage Interface),开发人员可以使用 Epic在线服务 (EOS)从云服务器检索加密数据。你通过此界面存储的数据可以被任何用户通过任何可登录的设备访问。尽管与玩家数据存储接口类似,但此接口专门处理与游戏相关的特定数据,而非特定于用户的数据,而且可基于用户的平台、区域或其他条件提供不同版本的文件。有关标题存储接口与玩家数据存储接口间差异的更多详情,参见本文底部的与玩家数据存储的差异部分。

要访问游戏存储接口,请通过平台接口函数 EOS_Platform_GetTitleStorageInterface 获取 EOS_HTitleStorage 句柄。游戏存储接口的所有函数都需要此句柄作为其第一个参数。必须确保 EOS_HPlatform 句柄处于更新状态,以便在完成请求时触发回调。

要使用此接口,必须使用以下额外参数初始化EOS平台:

  • const char* EncryptionKey:这个64字符的十六进制字符串可构建出256位的密钥,EOS将其用于加密用户数据。Epic的后端服务器不存储此密钥。如果没有密钥,从标题存储接口调用文件管理函数将失败并返回 EOS_TitleStorage_EncryptionKeyNotSet 错误代码。

  • const char* CacheDirectory:这是该接口在数据文件传输期间用于临时存储的完整本地目录路径。它可以是任何位置,一般选择系统的临时目录或游戏的数据目录。如果指定目录不存在,EOS将尝试创建它。你可以对多个用户和产品使用同一目录,EOS将确保其不发生冲突。如果目录有问题,调用文件管理函数将失败,并返回 EOS_CacheDirectoryMissingEOS_CacheDirectoryInvalid 错误代码。有关可使用文件夹的平台特定限制,请参见EOS平台文档

文件管理

文件名格式

EOS中的文件名采用以下形式:Directory0/Directory1/DirectoryN/Filename.Extension

"Directory"与"Extension"部分为可选项。每个目录名之后必须加"/"符号,但不能加在他处,也不能作为第一个和最后一个字符。文件名必须使用以下字符:

任何字母数字ASCII字符

  • !
  • -
  • _
  • +
  • .
  • '
  • (
  • )

文件名不可超过 EOS_TITLESTORAGE_FILENAME_MAX_LENGTH_BYTES (64)个字符。

查询文件

EOS SDK允许你通过数次查询API调用来检索云上存储的文件信息。你的查询将返回一个或多个文件的元数据,包括每个文件的名称、大小(以字节为单位)和MD5哈希。然后可以请求和管理你自己的元数据副本,并用它来访问或修改文件。由于文件在后端以加密形式存储,因此如文件大小和MD5哈希之类的元数据反映的是加密文件,而非通过开发人员门户上传的原始文件。

当查询对应的回调函数在执行期间,务必从缓存中复制你可能需要的任何信息。数据的生命周期无法保证超过回调函数的持续时间。运行多个查询时这点尤其重要,因为每个成功的查询都可能改变缓存的内容。

大多数函数都包含一个产品用户ID参数(可选项),以便更好地跟踪。你可以在没有产品用户ID的情况下查询数据(通过传递nullptr),但你在开发者门户中设置的用户ID重载项(User ID overrides)将不可用。回调包含你传递的相同的用户产品ID值

查询单个文件

如果只需要一个文件的信息,并且知道该文件名,可以调用 EOS_TitleStorage_QueryFile 函数,传入 EOS_TitleStorage_QueryFileOptions 结构,初始化如下:

属性
ApiVersionEOS_TITLESTORAGE_QUERYFILEOPTIONS_API_LATEST
LocalUserId(可选项)正在请求文件数据的本地用户的 EOS_ProductUserId
Filename正在查询的文件名

操作完成后,EOS将运行结构为 EOS_TitleStorage_QueryFileCallbackInfo 的回调(类型为 EOS_TitleStorage_OnQueryFileCompleteCallback)。如果调用成功,则EOS现在已将文件相关数据存入缓存中。

按标签查询多个文件

要一次性查询多个文件,或在不知确切文件名的情况下查询文件,必须先通过开发人员门户将标签应用于你的文件。然后EOS SDK可以基于这些标签查询文件。文件标记是字符串,其使用的格式规则与EOS文件名相同。以此方式查询文件时,必须提供一个或多个标签,EOS SDK将检索包含其中至少一个标记的所有文件的列表。为此需调用 EOS_TitleStorage_QueryFileListOptions 数据结构和 EOS_TitleStorage_QueryFileList,其初始化如下:

[COMMENT:none] 将其替换为指向API/Excerpts#EOS_TitleStorage_QueryFileListOptions的包含标签 [/COMMENT]

属性
ApiVersionEOS_TITLESTORAGE_QUERYFILELISTOPTIONS_API_LATEST
LocalUserId(可选项)正在请求文件数据的本地用户的 EOS_ProductUserId
NumTags标签列表中的标签数量(必须是正数值)
ListOfTags要为其查询文件的标签数组(ASCII字符串)

完成时,EOS将返回数据结构为 EOS_TitleStorage_QueryFileListCallbackInfo 的回调函数(类型为 EOS_TitleStorage_OnQueryFileListCompleteCallback)。如果调用成功,数据结构将包含找到的文件数量,且EOS缓存中包含这些文件的相关信息。

查询所有文件

标题存储接口不会提供特定的API调用来查询所有文件。但是,如果将特定标签应用于你上传的每个文件,则可以使用该标签以及 EOS_TitleStorage_QueryFileListOptions 来检索所有文件的相关数据。

(#ExaminingCachedFileInformation)

检查缓存的文件信息

一旦EOS检索和缓存了一个或多个文件的相关信息,你可以通过调用 EOS_TitleStorage_CopyFileMetadataByFilename 以及特定文件的文件名来检索该文件的相关信息,或通过调用 EOS_TitleStorage_CopyFileMetadataAtIndex 以及文件在缓存内的索引值(0为起点)。如果你需要知道缓存中的文件数量,可以调用 EOS_TitleStorage_GetFileMetadataCount。不再需要此信息的副本时,调用 EOS_TitleStorage_FileMetadata_Release 以释放它占用的内存。

查询EOS有关单个文件的信息之后,EOS_TitleStorage_GetFileMetadataCount 可能显示缓存中包含的多个文件。如果之前查询的结果仍保留在缓存中,就可能会发生这种情况。这种情况下,最佳操作是检查并确保 EOS_TitleStorage_QueryFileCallbackInfo 中的 ResultCodeEOS_Success,并调用 EOS_TitleStorage_CopyFileMetadataByFilename 以访问其信息。成功查询多个文件时,将删除之前缓存的元数据。

访问文件

标题存储接口支持从云异步读取文件。读取是一种流操作,EOS提供了一些句柄,用于检查流的进度,或限制/中断流送。

读取文件