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
한국어
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
CloudStorageBase
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
- KeyName - The name (
- 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.
- KeyName - The name (
- 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()
andGetCloudDocumentName()
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.
- Index - The
- 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.
- Filename - The name (
- 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.
- Index - The
- ParseDocumentAsString [Index] [bIsForConflict] - Returns a string representing the entire document. The document must first be read in using
ReadCloudDocument()
. This should only be used ifSaveDocumentWithString()
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.
- Index - The
- 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 ifSaveDocumentWithBytes()
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.
- Index - The
- 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 ifSaveDocumentWithObject()
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 viaSaveDocumentWithObject
). If the version of the data does not match this, the function will returnnone
. - bIsForConflict - If TRUE, the Index is into the array of documents with conflicts instead of the array of all documents.
- Index - The
- 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.
- Index - The
- 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.
- Index - The
- 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.
- Index - The
- 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.
- Index - The
- 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.
- Index - 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
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
- 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.
- Get a reference to the
CloudStorageBase
object by calling the staticGetCloudStorageInterface()
of thePlatformInterfaceBase
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 inPostBeginPlay()
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 thePlatformInterfaceDelegate
delegate.delegate PlatformInterfaceDelegate(const out PlatformInterfaceDelegateResult Result);
- To obtain the list of documents for the game, call
QueryForCloudDocuments()
on theCloudStorageBase
object and wait for theCSD_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();
- To read a document, call
ReadCloudDocument()
and then use one of theParseDocumentAs*()
functions depending on the type of data you are expecting.Cloud.ReadCloudDocument(0); StringData = Cloud.ParseDocumentAsString(0);
- To save a document, call one of the
SaveDocumentAs*()
functions passing it the appropriate data and then callWriteCloudDocument()
to save the document.Cloud.SaveDocumentAsString(0, StringData); Cloud.WriteCloudDocument(0);
CloudPC.uc
script of the UDKBase\Classes
directory and can be tested by using the CloudGame
gametype.