Class

NSUbiquitousKeyValueStore

An iCloud-based container of key-value pairs you use to share data among instances of your app running on a user's connected devices.

Declaration

@interface NSUbiquitousKeyValueStore : NSObject

Overview

Use the iCloud key-value store to make preference, configuration, and app-state data available to every instance of your app on every device connected to a user’s iCloud account. You can store scalar values such as BOOL, as well as values containing any of the property list object types: NSNumber, NSString, NSDate, NSData, NSArray, and NSDictionary.

Changes your app writes to the key-value store object are initially held in memory, then written to disk by the system at appropriate times. If you write to the key-value store object when the user is not signed into an iCloud account, the data is stored locally until the next synchronization opportunity. When the user signs into an iCloud account, the system automatically reconciles your local, on-disk keys and values with those on the iCloud server.

Any device running your app, and attached to the same iCloud account, can upload key-value changes to iCloud. To keep track of such changes, register for the NSUbiquitousKeyValueStoreDidChangeExternallyNotification notification during app launch. Then, obtain the keys and values from iCloud (which may be newer than those that are local) by calling the synchronize method. You need not call the synchronize method again during your app’s life cycle, unless your app design requires fast-as-possible upload to iCloud after you change a value.

For more information on adopting key-value storage in your app, see Designing for Key-Value Data in iCloud in iCloud Design Guide.

Avoid using this class for data that is essential to your app’s behavior when offline; instead, store such data directly into the local user defaults database.

The total amount of space available in your app’s key-value store, for a given user, is 1 MB. There is a per-key value size limit of 1 MB, and a maximum of 1024 keys. If you attempt to write data that exceeds these quotas, the write attempt fails and no change is made to your iCloud key-value storage. In this scenario, the system posts the NSUbiquitousKeyValueStoreDidChangeExternallyNotification notification with a change reason of NSUbiquitousKeyValueStoreQuotaViolationChange.

The maximum length for key strings for the iCloud key-value store is 64 bytes using UTF8 encoding. Attempting to write a value to a longer key name results in a runtime error.

To use this class, you must distribute your app through the App Store or Mac App Store, and you must request the com.apple.developer.ubiquity-kvstore-identifier entitlement in your Xcode project. For more on this, see Configuring Common Key-Value Storage for Multiple Apps in iCloud Design Guide.

This class is not meant to be subclassed.

Topics

Getting the Shared Instance

defaultStore

Returns the shared iCloud key-value store object.

Getting Values

- arrayForKey:

Returns the array associated with the specified key.

- boolForKey:

Returns the Boolean value associated with the specified key.

- dataForKey:

Returns the data object associated with the specified key.

- dictionaryForKey:

Returns the dictionary object associated with the specified key.

- doubleForKey:

Returns the double value associated with the specified key.

- longLongForKey:

Returns the long long value associated with the specified key.

- objectForKey:

Returns the object associated with the specified key.

- stringForKey:

Returns the string associated with the specified key.

Setting Values

- setArray:forKey:

Sets an array object for the specified key in the key-value store.

- setBool:forKey:

Sets a Boolean value for the specified key in the key-value store.

- setData:forKey:

Sets a data object for the specified key in the key-value store.

- setDictionary:forKey:

Sets a dictionary object for the specified key in the key-value store.

- setDouble:forKey:

Sets a double value for the specified key in the key-value store.

- setLongLong:forKey:

Sets a long long value for the specified key in the key-value store.

- setObject:forKey:

Sets an object for the specified key in the key-value store.

- setString:forKey:

Sets a string object for the specified key in the key-value store.

Explicitly Synchronizing In-Memory Key-Value Data to Disk

- synchronize

Explicitly synchronizes in-memory keys and values with those stored on disk.

Removing Keys

- removeObjectForKey:

Removes the value associated with the specified key from the key-value store.

Retrieving the Current Keys and Values

dictionaryRepresentation

A dictionary containing all of the key-value pairs in the key-value store.

Constants

Notification Keys

These keys can be included in the user info dictionary of the NSUbiquitousKeyValueStoreDidChangeExternallyNotification notification.

Change Reason Values

Possible values associated with the NSUbiquitousKeyValueStoreChangeReasonKey key.

Notifications

NSUbiquitousKeyValueStoreDidChangeExternallyNotification

Posted when the value of one or more keys in the local key-value store changed due to incoming data pushed from iCloud.

Relationships

Inherits From