TTMSFMXNativeiCloudDocument

Usage

The 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:

https://developer.apple.com/library/mac/documentation/General/Conceptual/iCloudDesignGuide/Chapters/DesigningForDocumentsIniCloud.html

Properties

Properties name	Description
ContainerIdentifier	Optional property to specify a different container identifier to access your documents, such as the difference between a trial and a paid application.

Methods

Methods name	Description
AddDocument	Adds a new document to the Documents collection and moves the file to iCloud. When the file is added, the OnDocumentAdded event is called.
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 LoadDocuments is the first step you need to manually implement after iCloud has been initialized. The OnInitialized event is triggered when iCloud has been loaded, or has failed to load. In this event, you need to call this method to asynchronously load the documents.
RefreshDocuments	Manually refresh the documents asynchronously. When the documents are refreshed, the OnDocumentsRefreshed event is called. This event is also called when there are changes in the iCloud document storage. Each refresh automatically calls OnDocumentAdded, OnDocumentDeleted and OnDocumentUpdated based on the difference of the current and the previous documents state. The Documents collection is automatically updated.
RemoveDocument	Removes the document from the collection and moves an existing document from iCloud to a local directory.
SwitchContainer	Switches between containers, after the ContainerIdentifier has been set. The currently loaded documents are cleared and renewed with the documents in the other container. If the ContainerIdentifier is an empty string, the default container is loaded, specified in your entitlements file.
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.

Events

Events name	Description
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 LoadDocuments.
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.

Initialization

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 TMSFMXNativeiCloudDocument1.SwitchContainer;

procedure TForm1.TMSFMXNativeiCloudDocument1Initialized(Sender: TObject;
  ASuccess: Boolean);
begin
  if ASuccess then
    TMSFMXNativeiCloudDocument1.LoadDocuments;
end;

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.

Notes sample

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.

Entitlements

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:

https://developer.apple.com/library/ios/documentation/General/Conceptual/iCloudDesignGuide/Chapters/iCloudFundametals.html

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 $(TeamIdentifierPrefix)com.mycompany.myapplication.