学步园

原文地址:https://developer.apple.com/library/prerelease/ios/#releasenotes/General/WhatsNewIniPhoneOS/Articles/iOS5.html

iCloud Storage APIs

The iCloud storage APIs let your application write user documents and data to a central location and access those items from all of a user’s computers and iOS devices. Making a user’s documents ubiquitous using iCloud means that a user can view or edit those documents from any device without having to sync or transfer files explicitly. Storing documents in a user’s iCloud account also provides a layer of security for that user. Even if a user loses a device, the documents on that device are not lost if they are in iCloud storage.

There are two ways that applications can take advantage of iCloud storage, each of which has a different intended usage:

• iCloud document storage—Use this feature to store user documents and data in the user’s iCloud account. For more information, see “Storing and Using Documents in iCloud.”

• iCloud key-value data storage—Use this feature to share small amounts of data among instances of your application. For more information, see “Storing Key-Value Data in iCloud.”

Most applications will use iCloud document storage to share documents from a user’s iCloud account. This is the feature that users think of when they think of iCloud storage. A user cares about whether documents are shared across devices and can see and manage those documents from a given device. In contrast, the iCloud key-value data store is not something a user would see. It is a way for your application to share very small amounts of data (tens of kilobytes) with other instances of itself. Applications can use this feature to store important state information. A magazine application might save the issue and page that the user read last, while a stocks application might store the stock symbols the user is tracking.

The summary for using the iCloud storage APIs in your application is as follows:

1. Use the iOS Provisioning Portal to enable iCloud storage for your iOS application.

   Enabling this feature requires that you have an updated provisioning profile on your development systems. Xcode 4 handles this step for you automatically.

2. Add an Entitlements file to your application and use it to configure the iCloud features your application uses; see “Requesting Entitlements for iCloud Storage.”

3. Implement iCloud document storage as follows:

   • Use the UIDocument class to read and write the contents of your user documents; alternatively, incorporate support for file presenters and file coordinators into the custom classes that you use to manage user documents. The iCloud service uses the file coordination mechanism to notify your application when a document changes. (The UIDocument class implements support for file presenters and file coordinators for you and is recommended.) For more information, see “Storing and Using Documents in iCloud.”

   • Use the NSFileManager class to move the appropriate documents to the user’s iCloud storage. It is recommended that you give users the option to move documents to iCloud; see “Moving a Document to iCloud Storage.”

   • Use the NSMetadataQuery interfaces to search for documents in a user’s iCloud storage; see “Searching for Documents in iCloud.”

   • Be prepared to handle version conflicts that might arise when two devices try to update a document at the same time; see “Handling File-Version Conflicts.”

4. To implement iCloud key-value data storage, use the NSUbiquitousKeyValueStore class to read and write keys and values. For information about how to use this class effectively, see “Storing Key-Value Data in iCloud.”

The sections that follow provide more details about how to implement different aspects of iCloud storage for your application. For additional information about using specific classes and interfaces, see the corresponding reference documentation.

Storing and Using Documents in iCloud

Documents in iCloud provide the central location from which updates can be delivered to a user’s computers and iOS devices. All documents must be created in your application’s sandbox initially and moved to a user’s iCloud account later. A document targeted for iCloud storage is not moved to iCloud immediately, though. First, it is moved out of your application sandbox and into a local system-managed directory where it can be monitored by the iCloud service. After that transfer, the file is transfered to iCloud and to the user’s other devices as soon as possible.

While in iCloud storage, changes made on one device are stored locally and then pushed to iCloud using a local daemon, as shown in Figure 1. To prevent large numbers of conflicting changes from occurring at the same time, applications are expected to use file coordinator objects to perform all changes. File coordinators mediate changes between your application and the daemon that facilitates the transfer of the document to and from iCloud. In this way, the file coordinator acts like a locking mechanism for the document, preventing your application and the daemon from modifying the document simultaneously.

Figure 1  Pushing document changes to iCloud

From an implementation perspective, the easiest way to manage documents in iCloud is to use the UIDocument class. This class does most of the heavy lifting required to read and write files that are stored in iCloud. Specifically, the UIDocument class handles the creation and use of file coordinators to modify the document. This class also seamlessly integrates document changes coming from other devices. The class even helps handle the potential conflicts that can arise when two devices do manage to update the same file in conflicting ways. You are not required to use the UIDocument class to manage your application’s documents, but using it requires less effort on your part.

Important: Applications that store documents to iCloud must specify one or more containers in which to store those documents. You specify which containers your application supports using the com.apple.developer.ubiquity-container-identifiers entitlement. For more information about this entitlement, see “Requesting Entitlements for iCloud Storage.”

The sections that follow discuss the basic mechanics of how you move documents to iCloud and manage them (with and without the help of the UIDocument class).

Moving a Document to iCloud Storage

To move a document to iCloud storage:

1. Create and save the file locally in your application sandbox.

2. If you are not using the UIDocument class to manage your file, create a file presenter to be responsible for it. For information on file presenters, see “Working with Documents in iCloud.”

3. Create an NSURL object that specifies the destination of the file in a user’s iCloud storage.

   You must put files in one of the container directories associated with your application. Call the URLForUbiquityContainerIdentifier: method of NSFileManager to get the root URL for the directory, and then append any additional directory and filenames to that URL. (Applications may put documents in any container directory for which they have the appropriate entitlement. For more information about specifying entitlements, see “Requesting Entitlements for iCloud Storage.”)

4. Call the setUbiquitous:itemAtURL:destinationURL:error: method of NSFileManager to move the file to the specified destination in iCloud.

When moving documents to iCloud, you can create additional subdirectories inside the container directory to manage your files. It is strongly recommended that you create a Documents subdirectory and use that directory for storing user documents. In iCloud, the contents of the Documents directory are made visible to the user so that individual documents can be deleted. Everything outside of the Documents directory is grouped together and treated as a single entity that a user can keep or delete. You create subdirectories in a user’s iCloud storage using the methods of the NSFileManager class just as you would any directory.

After you move a document to iCloud, it is not necessary to save a URL to the document’s location persistently. If you manage a document using a UIDocument object, that object automatically updates its local data structures with the document’s new URL. However, it does not save that URL to disk, and neither should your custom file presenters. Instead, because documents can move while in a user’s iCloud storage, you should use an NSMetadataQuery object to search for documents. Searching guarantees that your application has the correct URL for accessing the document. For information on how to search for documents in iCloud, see “Searching for Documents in iCloud.”

For more information about the methods of the NSFileManager class, see NSFileManager Class Reference.

Searching for Documents in iCloud

To locate documents in iCloud storage, your application must search using an NSMetadataQuery object. Searching is a guaranteed way to locate documents both in a user’s iCloud storage and in your application sandbox. You should always use query objects instead of saving URLs persistently because the user can delete files from iCloud storage when your application is not running. Using a query to search is the only way to ensure an accurate list of documents.

In iOS 5.0, the NSMetadataQuery class supports the following search scopes for your documents:

• Use the NSMetadataQueryUbiquitousDocumentsScope constant to search for documents in iCloud that reside somewhere inside a Documents directory. (For any given container directory, put documents that the user is allowed to access inside aDocuments subdirectory.)

• Use the NSMetadataQueryUbiquitousDataScope constant to search for documents in iCloud that reside anywhere other than in a Documents directory. (For any given container directory, use this scope to store user-related data files that your application needs to share but that are not files you want the user to manipulate directly.)

To use a metadata query object to search for documents, create a new NSMetadataQuery object and do the following:

1. Set the search scope of the query to an appropriate value (or values).

2. Add a predicate to narrow the search results. To search for all files, specify a predicate with the format NSMetadataItemFSNameKey == *.

3. Register for the query notifications and configure any other query parameters you care about, such as sort descriptors, notification intervals, and so on.

   The NSMetadataQuery object uses notifications to deliver query results. At a minimum, you should register for the NSMetadataQueryDidFinishGatheringNotification notification, but you might want to register for others in order to detect updates after the initial gathering process has finished.

4. Call the startQuery method of the query object.

5. Run the current run loop so that the query object can generate the results.

   If you started the query on your application’s main thread, simply return and let the main thread continue processing events. If you started the query on a secondary thread, you must configure and execute a run loop explicitly. For more information about executing run loops, see Threading Programming Guide.

6. Process the results in your notification-handler methods.

   When processing results, always disable updates first. Doing so prevents the query object from modifying the result list while you are using it. When you are done processing the results, reenable updates again to allow new updates to arrive.

7. When you are ready to stop the search, call the stopQuery method of the query object.

For information on how to create a metadata query object, see NSMetadataQuery Class Reference.

Working with Documents in iCloud

When your application needs to read or write a document in iCloud, it must do so in a coordinated manner. Your application might not be the only application trying to manipulate the local file at any given moment. The daemon that transfers the document to and from iCloud also needs to manipulate it periodically. To prevent your application from interfering with the daemon (and vice versa), iOS provides a coordinated locking mechanism that works with the files and directories you target for iCloud storage.

At the heart of the iCloud locking mechanism are file coordinators and file presenters. Whenever you need to read and write a file, you do so using a file coordinator, which is an instance of the NSFileCoordinator class. The job of a file coordinator is to coordinate the reads and writes performed by your application and the sync daemon on the same document. For example, your application and the daemon may both read the document at the same time but only one may write to the file at any single time. Also, if one process is reading the document, the other process is prevented from writing to the document until the reader is finished.

In addition to coordinating operations, file coordinators also work with file presenters to notify applications when changes are about to occur. A file presenter is any object that conforms to the NSFilePresenter protocol and takes responsibility for managing a specific file (or directory of files) in an application. The job of a file presenter is to protect the integrity of its own data structures. It does this by listening for messages from other file coordinators and using those messages to update its internal data structures. In most cases, a file presenter may not have to do anything. However, if a file coordinator declares that it is about to move a file to a new URL, the file presenter would need to replace its old URL with the new one provided to it by the file coordinator. The UIDocument class is an example of a file presenter that tracks changes to its underlying file or file package.

Here is a checklist of the things your application must do to work with documents in iCloud:

• Manage each document in iCloud using a file presenter. The recommended way to do this is to use the UIDocument class, but you may define custom file presenters if you prefer. You can use a single file presenter to manage a file package or a directory of files.

• After creating a file presenter, register it by calling the addFilePresenter: class method of NSFileCoordinator. Registration is essential. The system can notify only registered presenter objects.

• Before deleting a file presenter, unregister it by calling the removeFilePresenter: method of NSFileCoordinator.

All file-related operations must be performed through a file coordinator object. To read or write a document, or move or delete it, follow these steps:

1. Create an instance of the NSFileCoordinator class and initialize it with the file presenter object that is about to perform the file operation.

2. Use the methods of the NSFileCoordinator object to read or write the file:

   • To read all or part of a single file, use the coordinateReadingItemAtURL:options:error:byAccessor: method

   • To write to a file or delete it, call the coordinateWritingItemAtURL:options:error:byAccessor: method.

   • To perform a sequence of read or write operations, use the coordinateReadingItemAtURL:options:writingItemAtURL:options:error:byAccessor: method.

   • To write to multiple files, or to move a file to a new location, use the coordinateWritingItemAtURL:options:writingItemAtURL:options:error:byAccessor: method.

   You perform the actual file-related operations in the block that you pass to these methods. You should perform operations as quickly as possible to avoid blocking other applications that might be trying to access the file at the same time.

3. When you are done with the operations, release the file coordinator object.

For more information about using file coordinators and file presenters, see File System Programming Guide.

Handling File-Version Conflicts

When multiple instances of your application (running on different computers or iOS devices) try to modify the same document in iCloud, a conflict can occur. For example, if the devices are not connected to the network and the user makes changes on both, both devices try to push their changes to iCloud when they are reconnected to the network. At this point, iCloud has two different versions of the same file and has to decide what to do with them. Its solution is to make the most recently modified file thecurrent file and to mark any other versions of the file as conflict versions.

Your application is notified of conflict versions through its file presenter objects. It is the job of the file presenter to decide how best to resolve any conflicts that arise. Applications are encouraged to resolve conflicts quietly whenever possible, either by merging the file contents or by discarding the older version if the older data is no longer relevant. However, if discarding or merging the file contents is impractical or might result in data loss, your application might need to prompt the user for help in choosing an appropriate course of action. For example, you might let the user choose which version of the file to keep, or you might offer to save the older version under a new name.

Applications should always attempt to resolve conflict versions as soon as possible. When conflict versions exist, all of the versions remain in a user’s iCloud storage (and locally on any computers and iOS devices) until your application resolves them. The current version of the file and any conflict versions are reported to your application using instances of the NSFileVersion class.

To resolve conflicts:

1. Get the current file version using the currentVersionOfItemAtURL: class method of NSFileVersion.

2. Get an array of conflict versions using the unresolvedConflictVersionsOfItemAtURL: class method of NSFileVersion.

3. For each conflict version object, perform whatever actions are needed to resolve the conflict. Options include:

   • Merging the conflict versions with the current file automatically, if it is practical to do so.

   • Ignoring the conflict versions, if doing so does not result in any data loss.

   • Prompting the user to select which version (current or conflict) to keep. This should always be your last option.

4. Update the current file as needed.

   • If the current file version remains the winner, you do not need to update the current file.

   • If a conflict version is chosen as the winner, use a coordinated write operation to overwrite the contents of the current file with the contents of the conflict version.

   • If the user chooses to save the conflict version under a different name, create the new file with the contents of the conflict version.

5. Set the resolved property of the conflict version objects to YES.

   Setting this property to YES causes the conflict version objects (and their corresponding files) to be removed from the user’s iCloud storage.

For more information about file versions and how you use them, see NSFileVersion Class Reference.

Storing Key-Value Data in iCloud

An application can use the NSUbiquitousKeyValueStore class to share small amounts of data with other instances of itself running on other computers and iOS devices. This class provides a similar service as the NSUserDefaults class in that it allows you to save simple data types (numbers, strings, dates, arrays, and so on) persistently and retrieve that data later. The main difference is that the NSUbiquitousKeyValueStore class writes that data to the user’s iCloud storage so that it can be retrieved by the application running on different iOS devices or computers.