TMSFMXNativeiCloudDocument component is used to access the iCloud document storage. You typically use this component to add and update existing or create new documents and make them available to every instance of your app on every device connected to a user’s iCloud account. More information about the iCloud document storage can be found on the following page:
|ContainerIdentifier||Optional property to specify a different container identifier to access your documents, such as the difference between a trial and a paid application.|
|AddDocument||Adds a new document to the Documents collection and moves the file to iCloud. When the file is added, the
|DeleteDocument||Deletes an existing document from iCloud and removes the entry from the collection.|
|DocumentByIndex||Returns the document by the index in the Documents collection.|
|DocumentByName||Returns the document by the file system name or the display name. These are properties that are extracted from the file as metadata when the documents are loaded.|
|DocumentCount||Returns the number of documents in the collection.|
|LoadDocuments||Loads the documents from iCloud. The
|RefreshDocuments||Manually refresh the documents asynchronously. When the documents are refreshed, the
Each refresh automatically calls
|RemoveDocument||Removes the document from the collection and moves an existing document from iCloud to a local directory.|
|SwitchContainer||Switches between containers, after the
|UpdateDocument||Updates an existing document, this call has a number of overloads to update a document from a file or directly from a memory stream.|
|OnDocumentAdded||Event called when a new document is added to iCloud.|
|OnDocumentDeleted||Event called when an existing document is deleted from iCloud.|
|OnDocumentRemoved||Event called when an existing document is moved from iCloud to a local directory.|
|OnDocumentSaved||Event called when an existing document is updated and saved.|
|OnDocumentUpdated||Event called when an existing document is updated from iCloud.|
|OnDocumentsLoaded||Event called when the documents are loaded, after calling
|OnDocumentsRefreshed||Event called when the documents are refreshed.|
|OnInitialized||Event called when iCloud is initialized.|
|OnDocumentDataChanged||Event called when an iCloud document data has changed.|
When dropping a component on the form, it will try to connect to the iCloud document storage container specified by the
ContainerIdentifier property. If you have no intention to create multiple containers (such as the difference between a paid and a trial application), leave the
ContainerIdentifier empty, so the default container is accessed. As this process is asynchronous, an event is triggered when the component is done initializing.
After initialization succeeds, the documents can be loaded. If the initialization fails, you can try to reconnect by calling
When the documents are loaded, the
OnDocumentsLoaded event is called, and the listbox can be filled with the names of the documents.
procedure TForm1.TMSFMXNativeiCloudDocument1DocumentsLoaded(Sender: TObject); var doc: TTMSFMXNativeiCloudDocumentItem; I: Integer; begin ListBox1.BeginUpdate; ListBox1.Clear; for I := 0 to TMSFMXNativeiCloudDocument1.DocumentCount - 1 do begin doc := TMSFMXNativeiCloudDocument1.DocumentByIndex[I]; // ListBox1.Items.Add(doc.DisplayName); ListBox1.Items.Add(doc.FileSystemName); end; ListBox1.EndUpdate; end;
In the code sample we specify the
FileSystemName which includes the extension, but you can also use the
DisplayName which is a more meaningful name given to a document without the need for an extension.
To have a better understanding how the initialization process works, how to add new, delete or update existing documents, have a look at the iCloud Documents demo, which demonstrates the management of automatically synchronized notes throughout various devices which are all connected to the the same iCloud document storage container.
The demo also specifies an entitlements file that is used to sign the application to allow iCloud access. Below is more information on how to create provisioning profiles and correctly sign your application.
Before iCloud can be used in your application you need to enable it and sign your application. Additional information about enabling iCloud and incorporating it into your application can be found on the following page:
After reading the guide, you will need to perform 2 steps: signing your device, and adding an entitlements file that adds the necessary keys to gain access to the iCloud storage. As a helper sample we have included an iCloud Document demo project that demonstrates how the Entitlements file is added.
When opening the Entitlements file (iCloud.entitlements) you will notice placeholders that need to be filled in with a combination of the Team-ID and the Bundle Identifier
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>get-task-allow</key> <true/> <key>com.apple.developer.ubiquity-container-identifiers</key> <array> <string>$(TeamIdentifierPrefix)com.mycompany.myapplication</string> </array> <key>com.apple.developer.ubiquity-kvstore-identifier</key> <string>$(TeamIdentifierPrefix)com.mycompany.myapplication</string> </dict> </plist>
The first key is to allow the debugger to access the application. This is inherited from the default entitlements file that is distributed when deploying your application. The
com.apple.developer.ubiquity-container-identifiers and the
com.apple.developer.ubiquity-kvstore-identifier keys are used to access iCloud. Here you need to specify the correct Team Identifier Prefix and the Bundle Identifier that matches your Application ID, used in the generation of the provisioning profile. Below is a sample of the Application ID at developer.apple.com, used to generate a provisioning profile to sign your application.
If the prefix is
ABC123 and the ID is
com.tmssoftware.FireMonkeySample. The correct Entitlements.plist file would have
ABC123.com.tmssoftware.FireMonkeySample as substitute for