UDN
Search public documentation:

CloudDocumentStorageCH
English Translation
한국어

Interested in the Unreal Engine?
Visit the Unreal Technology site.

Looking for jobs and company info?
Check out the Epic games site.

Questions about support via UDN?
Contact the UDN Staff

UE3 主页 > 平台接口架构 > 云文件存储

云文件存储


概述


云文件存储允许将数据存储到“云系统”中并允许读取该“云系统”中存储的文档,主要用于保存游戏数据。

注意: 尽管云文件通过在本地存储文件在PC上模拟,但云文件存储功能目前仅限于在iOS系统上运行的游戏。

CloudStorageBase


CloudStorageBase 类是个基类,包含了加载及保存云文件的功能。该类继承于 PlatformInterfaceBase ,并使用了那个类中包含的代理系统。每个平台(PC、iOS等)有它自己的继承于 CloudStorageBase 的子类,这些子类提供了针对那个特定平台的实现。

函数

  • Init - 当初始化云存储系统时引擎调用的事件。
  • ReadKeyValue [KeyName] [Type] [SerializedObj] - 开始从云存储中读取一个 键/值 对,如果成功则返回TRUE。
    • KeyName - 要读取的键的名称( 字符串 ) 。
    • Type - 要读取的 EPlatformInterfaceDataType 类型的值。
    • SerializedObj - 如果您正在读取一个对象,那么它将向这个对象反序列化二进制数据。
  • WriteKeyValue [KeyName] [Value] - 将一个 键/值 对写入到云系统中,如果成功则返回TRUE。
    • KeyName - 要写入的键的名称( 字符串 ) 。
    • Value - 要写入到指定键中的 PlatformInterfaceData 值。
  • QueryForCloudDocuments - 对云系统中存在的文档进行一次异步查询,如果成功则返回TRUE。如果已经搜索到了任何文档,那么将会冲掉这些文档,刷新那组找到的文档。一旦完成,您可以使用 GetNumCloudDocuments()GetCloudDocumentName() 来获得现有文档的信息。
  • GetNumCloudDocuments [bIsForConflict] - 返回该云系统中已知存在的文档的数量,在 QueryForCloudDocuments() 函数的后面调用。
    • bIsForConflict – 可选项。如果该项为TRUE,那么将会返回有冲突的文档的数量而不是总文档的数量。
  • GetCloudDocumentName [Index] - 返回和给定索引对应的文档的名称。
    • Index - Int 指出了要获得其名称的文档的索引。
  • CreateCloudDocument [Filename] - 在运系统中创建一个新的文档 (未初始化的文档、为保存的文档、使用 Write/Save 函数)。
    • Filename - 赋予新创建的文档的名称 ( string )。
  • ReadCloudDocument [Index] [bIsForconflict] - 读取一个文档到内存中(或读取到任何需要的地方,以便使得ParseDocumentAs*函数异步操作,不必停止游戏)。
    • Index - Int 指出了要读取的文档的索引。
    • bIsForConflict - 如果该项为TRUE,那么 Index 是指具有冲突的文档数组的索引,而不是所有文档数组的索引。
  • ParseDocumentAsString [Index] [bIsForConflict] - 返回一个代表整个文档的字符串。首先必须使用 ReadCloudDocument() 函数读取文档。这应该仅在使用 SaveDocumentWithString() 生成文档时使用。
    • Index - Int 指出了要解析的文档的索引。
    • bIsForConflict - 如果该项为TRUE,那么 Index 是指具有冲突的文档数组的索引,而不是之所有文档数组的索引。
  • ParseDocumentAsBytes [Index] [ByteData] [bIsForConflict] - 输出一组代表整个文档的字节。首先必须使用 ReadCloudDocument() 函数读取文档。这应该仅在使用 SaveDocumentWithBytes() 生成文档时使用。
    • Index - Int 指出了要解析的文档的索引。
    • ByteData - 一个由从文档中读取的数据填充的字节数组。如果解析失败那么该数组则为空。
    • bIsForConflict - 如果该项为TRUE,那么 Index 是指具有冲突的文档数组的索引,而不是之所有文档数组的索引。
  • ParseDocumentAsObject [Index] [ObjectClass] [ExpectedVersion] [bIsForConflict] - 返回一个代表整个文档的对象。首先必须使用 ReadCloudDocument() 函数读取文档。这应该仅在使用 SaveDocumentWithObject() 生成文档时使用。
    • Index - Int 指出了要解析的文档的索引。
    • ObjectClass - 使用文档的数据要创建的对象的 Class(类)
    • ExpectedVersion - Int 指出了期望的数据版本号(设置通过 SaveDocumentWithObject)。如果数据的版本和这个版本号不匹配,那么函数将返回 none
    • bIsForConflict - 如果该项为TRUE,那么 Index 是指具有冲突的文档数组的索引,而不是之所有文档数组的索引。
  • WriteCloudDocument [Index] - 使用 SaveDocumentWith* 函数读取一个已经“保存”的文档。
    • Index - Int 指出了要写入的文档的索引。
  • SaveDocumentWithString [Index] [StringData] - 准备文档以便将其写入到云系统中,使用字符串作为输入数据。这是同步的。
    • Index - Int 指出了要保存的文档的索引。
    • StringData - 要保存到文件中的 String(字符串) 数据。
  • SaveDocumentWithString [Index] [StringData] - 准备文档以便将其写入到云系统中,使用一组字节作为输入数据。这是同步的。
    • Index - Int 指出了要保存的文档的索引。
    • ByteData - 要保存到文件中的字节数组。
  • SaveDocumentWithString [Index] [StringData] - 准备文档以便将其写入到云系统中,使用对象作为输入数据。这是同步的。
    • Index - Int 指出了要保存的文档的索引。
    • ObjectData - 要序列化到字节内并保存到文件中的 Object(对象) 数据。
    • SaveVersion - Int 指出了正在保存的对象的版本号。以便在您加载这个对象时使用,如果版本和该版本号不匹配,则跳过加载该对象。
  • ResolveConflictWithNewestDocument - 如果有冲突通知,这个函数简单地告诉云系统接口选择最近修改的版本,忽略其他版本。
  • ResolveConflictWithNewestVersionIndex [Index] - 如果有冲突通知,这个函数告诉云接口选择具有给定索引的版本作为主要版本,忽略其他版本。
    • Index - Int 指出了要作为主要版本的文档的索引。

Delegates(代理)

ECloudStorageDelegate 枚举值定义了可以接受函数调用返回的代理类型的ID。通过使用 平台接口代理系统来为这些类型中的任何一种分配代理。

  • CSD_KeyValueReadComplete - 当尝试通过 ReadKeyValue() 函数读取一个云 键/值 对的值完成时执行分配给这个ID的代理。
    • bSuccessful - 如果成功读取了值则返回TRUE。
    • Data - 包含了被读取的值。
  • CSD_KeyValueWriteComplete - 当尝试通过 WriteKeyValue() 函数写入一个云系统 键/值 的值完成时执行分配给这个ID的代理。
    • bSuccessful - 如果成功写入了值则返回TRUE。
    • Data - 包含了被写入的值。
  • CSD_ValueChanged - 当一个云系统 键/值 对发生改变时执行分配给这个ID的代理。
    • bSuccessful - TRUE。
    • Data - 包含了值发生改变的键的名称。
  • CSD_DocumentQueryComplete - 当通过 QueryCloudDocuments() 完成云文档查询时执行分配给这个ID的代理。
    • bSuccessful - TRUE。
    • Data - 包含了被读取的文档的索引。
  • CSD_DocumentReadComplete - 当通过 ReadCloudDocument() 完成云文档读取时执行分配给这个ID的代理。
    • bSuccessful - 如果成功地打开了文档则该项为TRUE。
    • Data - 包含了被打开的文档的索引。
  • CSD_DocumentWriteComplete - 当通过 WriteCloudDocument() 完成云文档写入时执行分配给这个ID的代理。
    • bSuccessful - 如果写入成功则返回TRUE。
    • Data - 包含了被写入的文档的索引。
  • CSD_DocumentConflictDetected - 当多个及其更新了一个文档导致出现冲突时执行分配给这个ID的代理。这可以用于通过ResolveConflictWithNewest*函数使用脚本来决定使用哪个版本。
    • bSuccessful - TRUE。
    • Data - 包含了发生冲突的文档的索引。

对象作为数据


对象及它们的属性可以序列化并保存到云文件中,这使得云存储成为保存游戏数据的可行选择。一般的思想是创建一个继承与Object (对象)的类,该类包含了要保存的所有数据的变量。创建这个游戏数据对象的实例,它的变量将会在游戏过程中进行更新。当准备好保存游戏时,这个对象的实例被传入到 SaveDocumentWithObject() 函数,然后使用 WriteCloudDocument() 函数写入这个文档。当游戏启动后可以使用 ReadCloudDocument()ParseDocumentAsObject() 函数来读取该数据。

实现细节


针对虚幻引擎3设置及使用云文档存储的一般流程如下所示:

  1. 如果您的游戏是iOS应用程序,那么确保在iOS Provisioning Portal中设置您的游戏使用iCloud 服务。要想获得更多信息,请参照Apple开发者网站
  2. 根据您正在放置的云文件的功能的位置的不同通常在 PostBeginPlay() 或其他初始化函数中通过调用 PlatformInterfaceBase 类的静态函数 GetCloudStorageInterface() 获得到 CloudStorageBase 对象的引用,并设置您想处理的任何代理(文档查询、值改变、值读取、值写入、文档读取、文档写入、冲突检测)。
       var CloudStorageBase Cloud;
    
       ...
    
       Cloud = class'PlatformInterfaceBase'.static.GetCloudStorageInterface();
       Cloud.AddDelegate(CSD_ValueChanged, CloudValueChanged);
       Cloud.AddDelegate(CSD_DocumentReadComplete, CloudReadDocument);
       Cloud.AddDelegate(CSD_DocumentConflictDetected, CloudConflictDetected);
       
    CloudValueChangedCloudReadDocumentCloudConflictDetected 就是这样的例子。这些可以是任何和 PlatformInterfaceDelegate 代理的签名相匹配的函数的名称。
       delegate PlatformInterfaceDelegate(const out PlatformInterfaceDelegateResult Result);
       
  3. 要想获得游戏的文档列表,可以在 CloudStorageBase 对象上调用 QueryForCloudDocuments() 函数,并等待 CSD_DocumentQueryComplete 函数返回,此时您可以处理文档列表来将它们以您期望的方式显示给用户(一般是显示在某种菜单中)。
       Cloud.QueryForCloudDocuments();
       
  4. 要想读取文档,请调用 ReadCloudDocument() 函数,然后根据您需要的数据类型的不同使用其中一个 ParseDocumentAs*() 函数。
       Cloud.ReadCloudDocument(0);
       StringData = Cloud.ParseDocumentAsString(0);
       
  5. 要想保存文档,请调用其中一个 SaveDocumentAs*() 函数,并向它传入适当的数据,然后调用 WriteCloudDocument() 函数来保存文档。
       Cloud.SaveDocumentAsString(0, StringData);
       Cloud.WriteCloudDocument(0);
       

可以在 UDKBase\Classes 目录中的 CloudPC.uc 脚本中找到基本实现,并且可以使用 CloudGame 游戏类型进行测试。