UDN
Search public documentation:

CloudDocumentStorage
中国翻译
한국어

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 Home > PlatformInterface Framework > Cloud Document Storage

Cloud Document Storage


Overview


Cloud document storage allows the data to be stored to and read from documents stored in the "cloud", generally for the purpose of saving game data.

Note: Cloud document storage functionality is currently limited to games running on the iOS platform, though it is simulated on PC by storing documents locally.

CloudStorageBase


The CloudStorageBase class is the base class containing the functionality for loading and saving cloud documents. It inherits from the PlatformInterfaceBase and makes use of the delegate system contained in that class. Each platform (PC, iOS, etc.) has its own subclass extending from CloudStorageBase that provides the implementation specific to that platform.

Functions

  • Init - Event called by the engine to initialize the cloud storage system.
  • ReadKeyValue [KeyName] [Type] [SerializedObj] - Initiates reading a key/value pair from cloud storage and returns TRUE if successful.
    • KeyName - The name (string) of the key to be read.
    • Type - The EPlatformInterfaceDataType type of value to be read.
    • SerializedObj - If you are reading an object, it will de-serialize the binary blob into this object
  • WriteKeyValue [KeyName] [Value] - Writes a key/value pair to the cloud and returns TRUE if successful.
    • KeyName - The name (string) of the key to be written.
    • Value - The PlatformInterfaceData value to be written to the specified key.
  • QueryForCloudDocuments - Kick off an async query of documents that exist in the cloud and returns TRUE if successful. If any documents have already been retrieved, this will flush those documents, and refresh the set. Once completed, you can use GetNumCloudDocuments() and GetCloudDocumentName() to get the information about any existing documents.
  • GetNumCloudDocuments [bIsForConflict] - Returns the number of documents known to exist in the cloud following a call to QueryForCloudDocuments().
    • bIsForConflict - Optional. If TRUE, the number of documents with conflicts will be returned in place of the total number of documents.
  • GetCloudDocumentName [Index] - Returns the name of the document corresponding to the given index.
    • Index - The Int specifying the index of the document to get the name for.
  • CreateCloudDocument [Filename] - Creates a new document in the cloud (uninitialized, unsaved, use the Write/Save functions).
    • Filename - The name (string) to give the newly created document.
  • ReadCloudDocument [Index] [bIsForconflict] - Reads a document into memory (or whatever is needed so that the ParseDocumentAs* functions operate synchronously without stalling the game).
    • Index - The Int specifying the index of the document to read.
    • bIsForConflict - If TRUE, the Index is into the array of documents with conflicts instead of the array of all documents.
  • ParseDocumentAsString [Index] [bIsForConflict] - Returns a string representing the entire document. The document must first be read in using ReadCloudDocument(). This should only be used if SaveDocumentWithString() was used to generate the document.
    • Index - The Int specifying the index of the document to parse.
    • bIsForConflict - If TRUE, the Index is into the array of documents with conflicts instead of the array of all documents.
  • ParseDocumentAsBytes [Index] [ByteData] [bIsForConflict] - Outputs an array of bytes representing the entire document. The document must first be read in using ReadCloudDocument(). This should only be used if SaveDocumentWithBytes() was used to generate the document.
    • Index - The Int specifying the index of the document to parse.
    • ByteData - An array of bytes that is populated with the data from the document. This will be empty if the parsing fails.
    • bIsForConflict - If TRUE, the Index is into the array of documents with conflicts instead of the array of all documents.
  • ParseDocumentAsObject [Index] [ObjectClass] [ExpectedVersion] [bIsForConflict] - Returns an object representing the entire document. The document must first be read in using ReadCloudDocument(). This should only be used if SaveDocumentWithObject() was used to generate the document.
    • Index - The Int specifying the index of the document to parse.
    • ObjectClass - The Class of the object to create using the data from the document.
    • ExpectedVersion - An Int specifying the version number expected to be in the data (set via SaveDocumentWithObject). If the version of the data does not match this, the function will return none.
    • bIsForConflict - If TRUE, the Index is into the array of documents with conflicts instead of the array of all documents.
  • WriteCloudDocument [Index] - Writes a document that has been already "saved" using the SaveDocumentWith* functions.
    • Index - The Int specifying the index of the document to be written.
  • SaveDocumentWithString [Index] [StringData] - Prepare a document for writing to the cloud with a string as input data. This is synchronous.
    • Index - The Int specifying the index of the document to be saved.
    • StringData - The String data to be saved to the file.
  • SaveDocumentWithBytes [Index] [ByteData] - Prepare a document for writing to the cloud with an array of bytes as input data. This is synchronous.
    • Index - The Int specifying the index of the document to be saved.
    • ByteData - The array of bytes to be saved to the file.
  • SaveDocumentWithObject [Index] [ObjectData] [SaveVersion] - Prepare a document for writing to the cloud with an object as input data. This is synchronous.
    • Index - The Int specifying the index of the document to be saved.
    • ObjectData - The Object data to be serialized to bytes and saved to the file.
    • SaveVersion - An Int specifying the version number of the object being saved. Used so that when you load this object, if the version doesn't match it will skip loading the object.
  • ResolveConflictWithNewestDocument - If there was a conflict notification, this will simply tell the cloud interface to choose the most recently modified version, and toss any others.
  • ResolveConflictWithNewestVersionIndex [Index] - If there was a conflict notification, this will tell the cloud interface to choose the version with the given Index to be the master version, and to toss any others.
    • Index - The Int specifying the index of the document to keep as the master version.

Delegates

The ECloudStorageDelegate enum defines the IDs for the types of delegates that can receive callbacks. Delegates can be assigned to each of these using the Platform Interface Delegates system.

  • CSD_KeyValueReadComplete - Delegates assigned to this ID are executed when an attempt to read the value of a cloud key/value is completed via ReadKeyValue().
    • bSuccessful - TRUE if the value was read successfully.
    • Data - Contains the value that was read.
  • CSD_KeyValueWriteComplete - Delegates assigned to this ID are executed when an attempt to write the value of a cloud key/value is completed via WriteKeyValue().
    • bSuccessful - TRUE if the value was written successfully.
    • Data - Contains the value that was written.
  • CSD_ValueChanged - Delegates assigned to this ID are executed when the value of a cloud key/value changes.
    • bSuccessful - TRUE.
    • Data - Contains the name of the key whose value changed.
  • CSD_DocumentQueryComplete - Delegates assigned to this ID are executed when the query for cloud documents is completed, via QueryCloudDocuments().
    • bSuccessful - TRUE.
    • Data - Contains the index of the document that was read.
  • CSD_DocumentReadComplete - Delegates assigned to this ID are executed when an attempt to open a document for reading is completed via ReadCloudDocument().
    • bSuccessful - TRUE if the document was opened successfully.
    • Data - Contains the index of the document that was opened.
  • CSD_DocumentWriteComplete - Delegates assigned to this ID are executed when an attempt to write a document is completed via WriteCloudDocument().
    • bSuccessful - TRUE if the document was written successfully.
    • Data - Contains the index of the document that was written.
  • CSD_DocumentConflictDetected - Delegates assigned to this ID are executed when multiple machines have updated a document resulting in a conflict. This can be used to allow the script to determine which version to use via the ResolveConflictWithNewest* functions.
    • bSuccessful - TRUE.
    • Data - Contains the Index of the document where the conflict occurred.

Objects as Data


Objects and their properties can be serialized and saved to cloud documents, which makes cloud storage a viable option for saving game data. The general idea is a class extending from Object is created that contains variables for all of the data to be saved. An instance of this game data object is created and its variables are updated during the game. When the game is ready to be saved, the instance of this object is passed to SaveDocumentWithObject() and then the document is written with WriteCloudDocument(). The data can then be read in when the game starts up using ReadCloudDocument() and ParseDocumentAsObject().

Implementation Details


The general workflow for setting up and using the cloud document storage for Unreal Engine 3 is outlined below:

  1. Make sure your game is set up to use the iCloud service in the iOS Provisioning Portal if it is an iOS app. For more information, see the Apple Developer Site.
  2. Get a reference to the CloudStorageBase object by calling the static GetCloudStorageInterface() of the PlatformInterfaceBase class and set up any delegates you wish to handle (document query, value changed, value read, value write, document read, document write, conflict detected), usually in PostBeginPlay() or some other initialization function depending on where you are placing the cloud document functionality.
       var CloudStorageBase Cloud;
    
       ...
    
       Cloud = class'PlatformInterfaceBase'.static.GetCloudStorageInterface();
       Cloud.AddDelegate(CSD_ValueChanged, CloudValueChanged);
       Cloud.AddDelegate(CSD_DocumentReadComplete, CloudReadDocument);
       Cloud.AddDelegate(CSD_DocumentConflictDetected, CloudConflictDetected);
       
    CloudValueChanged, CloudReadDocument, CloudConflictDetected are just examples. These can be the names of any function matching the signature of the PlatformInterfaceDelegate delegate.
       delegate PlatformInterfaceDelegate(const out PlatformInterfaceDelegateResult Result);
       
  3. To obtain the list of documents for the game, call QueryForCloudDocuments() on the CloudStorageBase object and wait for the CSD_DocumentQueryComplete callback where you can handle the list of documents to display them to the user in any way you desire (most likely in a menu of some sort).
       Cloud.QueryForCloudDocuments();
       
  4. To read a document, call ReadCloudDocument() and then use one of the ParseDocumentAs*() functions depending on the type of data you are expecting.
       Cloud.ReadCloudDocument(0);
       StringData = Cloud.ParseDocumentAsString(0);
       
  5. To save a document, call one of the SaveDocumentAs*() functions passing it the appropriate data and then call WriteCloudDocument() to save the document.
       Cloud.SaveDocumentAsString(0, StringData);
       Cloud.WriteCloudDocument(0);
       

A basic implementation can be found in the CloudPC.uc script of the UDKBase\Classes directory and can be tested by using the CloudGame gametype.