iOS Developer Library

Developer

Foundation Framework Reference NSUbiquitousKeyValueStore Class Reference

Options
Deployment Target:

On This Page
Language:

NSUbiquitousKeyValueStore

Inherits From


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 5.0 and later

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 Request Access to iCloud Storage By Using Entitlements in iCloud Design Guide.

This class is not meant to be subclassed.

  • Returns the shared iCloud key-value store object.

    Declaration

    Swift

    class func defaultStore() -> NSUbiquitousKeyValueStore

    Objective-C

    + (NSUbiquitousKeyValueStore *)defaultStore

    Return Value

    The shared iCloud key-value store object.

    Discussion

    An app must always use the default iCloud key-value store object to get and set values. This store is tied to the unique identifier string your app provides in its entitlement requests.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later

  • Returns the array associated with the specified key.

    Declaration

    Swift

    func arrayForKey(_ aKey: String) -> [AnyObject]?

    Objective-C

    - (NSArray *)arrayForKey:(NSString *)aKey

    Parameters

    aKey

    A key in the key-value store.

    Return Value

    The array associated with the specified key, or nil if the key was not found or its value is not an NSArray object.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later

  • Returns the Boolean value associated with the specified key.

    Declaration

    Swift

    func boolForKey(_ aKey: String) -> Bool

    Objective-C

    - (BOOL)boolForKey:(NSString *)aKey

    Parameters

    aKey

    A key in the key-value store.

    Return Value

    If a Boolean value is associated with the specified key, that value is returned. If the key was not found, this method returns NOfalse.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later

  • Returns the data object associated with the specified key.

    Declaration

    Swift

    func dataForKey(_ aKey: String) -> NSData?

    Objective-C

    - (NSData *)dataForKey:(NSString *)aKey

    Parameters

    aKey

    A key in the key-value store.

    Return Value

    The data object associated with the specified key or nil if the key was not found or its value is not an NSData object.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later

  • Returns the dictionary object associated with the specified key.

    Declaration

    Swift

    func dictionaryForKey(_ aKey: String) -> [NSObject : AnyObject]?

    Objective-C

    - (NSDictionary *)dictionaryForKey:(NSString *)aKey

    Parameters

    aKey

    A key in the key-value store.

    Return Value

    The dictionary object associated with the specified key or nil if the key was not found or its value is not an NSDictionary object.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later

  • Returns the double value associated with the specified key.

    Declaration

    Swift

    func doubleForKey(_ aKey: String) -> Double

    Objective-C

    - (double)doubleForKey:(NSString *)aKey

    Parameters

    aKey

    A key in the key-value store.

    Return Value

    The double value associated with the specified key or 0 if the key was not found. If the key exists but does not contain a numerical value, this method returns 0.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later

  • Returns the long long value associated with the specified key.

    Declaration

    Swift

    func longLongForKey(_ aKey: String) -> Int64

    Objective-C

    - (long long)longLongForKey:(NSString *)aKey

    Parameters

    aKey

    A key in the key-value store.

    Return Value

    The long long value associated with the specified key or 0 if the key was not found. If the key exists but does not contain a numerical value, this method returns 0.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later

  • Returns the object associated with the specified key.

    Declaration

    Swift

    func objectForKey(_ aKey: String) -> AnyObject?

    Objective-C

    - (id)objectForKey:(NSString *)aKey

    Parameters

    aKey

    A key in the key-value store.

    Return Value

    The object associated with the specified key or nil if the key was not found.

    Discussion

    You can use this method to retrieve objects whose type you do not necessarily know from the key-value store. The object returned by this method is always one of the property list types: NSNumber, NSString, NSDate, NSData, NSArray, or NSDictionary.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later

  • Returns the string associated with the specified key.

    Declaration

    Swift

    func stringForKey(_ aKey: String) -> String?

    Objective-C

    - (NSString *)stringForKey:(NSString *)aKey

    Parameters

    aKey

    A key in the key-value store.

    Return Value

    The string associated with the specified key or nil if the key was not found or its value is not an NSString object.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later

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

    Declaration

    Swift

    func setArray(_ anArray: [AnyObject]?, forKey aKey: String)

    Objective-C

    - (void)setArray:(NSArray *)anArray forKey:(NSString *)aKey

    Parameters

    anArray

    An array whose contents can be stored in a property list format. In other words, the objects in the array must be of the types NSNumber, NSString, NSDate, NSData, NSArray, or NSDictionary. The total size (in bytes) of the array and its contents must not exceed the per-key size limits.

    aKey

    The key under which to store the value. The length of this key must not exceed 64 bytes using UTF8 encoding.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later

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

    Declaration

    Swift

    func setBool(_ value: Bool, forKey aKey: String)

    Objective-C

    - (void)setBool:(BOOL)value forKey:(NSString *)aKey

    Parameters

    value

    The Boolean value to store.

    aKey

    The key under which to store the value. The length of this key must not exceed 64 bytes using UTF8 encoding.\

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later

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

    Declaration

    Swift

    func setData(_ aData: NSData?, forKey aKey: String)

    Objective-C

    - (void)setData:(NSData *)aData forKey:(NSString *)aKey

    Parameters

    aData

    The data object to store. The total size of this data object (including any object overhead) must not exceed 1 MB.

    aKey

    The key under which to store the value. The length of this key must not exceed 64 bytes using UTF8 encoding.

    Discussion

    Using an NSData object as a value in key-value storage lets you store arbitrary data. For example, in a game app, you can use it to store game state to iCloud.

    Be sure to exercise caution when storing a data object. Because it is available to be read and modified by every instance of your app attached to a user’s iCloud account, some of which may be older versions or running on another platform, you must diligently protect a data object’s integrity. For more information, see “Exercise Caution When Using NSData Objects as Values” in iCloud Design Guide.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later

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

    Declaration

    Swift

    func setDictionary(_ aDictionary: [NSObject : AnyObject]?, forKey aKey: String)

    Objective-C

    - (void)setDictionary:(NSDictionary *)aDictionary forKey:(NSString *)aKey

    Parameters

    aDictionary

    A dictionary whose contents can be stored in a property list format. In other words, the objects in the dictionary must be of the types NSNumber, NSString, NSDate, NSData, NSArray, or NSDictionary. The total size (in bytes) of the dictionary and its contents must not exceed the per-key size limits.

    aKey

    The key under which to store the value. The length of this key must not exceed 64 bytes using UTF8 encoding.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later

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

    Declaration

    Swift

    func setDouble(_ value: Double, forKey aKey: String)

    Objective-C

    - (void)setDouble:(double)value forKey:(NSString *)aKey

    Parameters

    value

    The double value to store.

    aKey

    The key under which to store the value. The length of this key must not exceed 64 bytes using UTF8 encoding.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later

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

    Declaration

    Swift

    func setLongLong(_ value: Int64, forKey aKey: String)

    Objective-C

    - (void)setLongLong:(long long)value forKey:(NSString *)aKey

    Parameters

    value

    The long long value to store.

    aKey

    The key under which to store the value. The length of this key must not exceed 64 bytes using UTF8 encoding.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later

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

    Declaration

    Swift

    func setObject(_ anObject: AnyObject?, forKey aKey: String)

    Objective-C

    - (void)setObject:(id)anObject forKey:(NSString *)aKey

    Parameters

    anObject

    The object you want to store. The type of the object must be one of the property list types: NSNumber, NSString, NSDate, NSData, NSArray, or NSDictionary. The total size (in bytes) of the object must not exceed the per-key size limits.

    aKey

    The key under which to store the value. The length of this key must not exceed 64 bytes using UTF8 encoding.

    Discussion

    If the type of anObject is not one of the property list types, this method does not set it in the key-value store. Instead, it logs an error and silently ignores the object.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later

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

    Declaration

    Swift

    func setString(_ aString: String?, forKey aKey: String)

    Objective-C

    - (void)setString:(NSString *)aString forKey:(NSString *)aKey

    Parameters

    aString

    The string you want to store. The total size (in bytes) of the string must not exceed the per-key size limits.

    aKey

    The key under which to store the value. The length of this key must not exceed 64 bytes using UTF8 encoding.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later

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

    Declaration

    Swift

    func synchronize() -> Bool

    Objective-C

    - (BOOL)synchronize

    Return Value

    YEStrue if the in-memory and on-disk keys and values were synchronized, or NOfalse if an error occurred. For example, this method returns NOfalse if an app was not built with the proper entitlement requests.

    Discussion

    The only recommended time to call this method is upon app launch, or upon returning to the foreground, to ensure that the in-memory key-value store representation is up-to-date.

    Changes you make to the key-value store are saved to memory. The system then synchronizes the in-memory keys and values with the local on-disk cache, automatically and at appropriate times. For example, it synchronizes the keys when your app is put into the background, when changes are received from iCloud, and when your app makes changes to a key but does not call the synchronize method for several seconds.

    This method does not force new keys and values to be written to iCloud. Rather, it lets iCloud know that new keys and values are available to be uploaded. Do not rely on your keys and values being available on other devices immediately. The system controls when those keys and values are uploaded. The frequency of upload requests for key-value storage is limited to several per minute.

    During synchronization between memory and disk, this method updates your in-memory set of keys and values with changes previously received from iCloud.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later

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

    Declaration

    Swift

    func removeObjectForKey(_ aKey: String)

    Objective-C

    - (void)removeObjectForKey:(NSString *)aKey

    Parameters

    aKey

    The key corresponding to the value you want to remove.

    Discussion

    If the specified key is not found in the key-value store, this method does nothing. This method removes the key from the in-memory version of the store only. Call the synchronize method at appropriate times to update the information on disk.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later

  • A dictionary containing all of the key-value pairs in the key-value store. (read-only)

    Declaration

    Swift

    var dictionaryRepresentation: [NSObject : AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSDictionary *dictionaryRepresentation

    Discussion

    This method returns the in-memory version of the keys and values. If you want to ensure that this dictionary contains the most recent set of changes, call synchronize shortly before calling this method.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later

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

    Declaration

    Swift

    let NSUbiquitousKeyValueStoreChangeReasonKey: String let NSUbiquitousKeyValueStoreChangedKeysKey: String

    Objective-C

    NSString * const NSUbiquitousKeyValueStoreChangeReasonKey; NSString * const NSUbiquitousKeyValueStoreChangedKeysKey;

    Constants

    • NSUbiquitousKeyValueStoreChangeReasonKey

      NSUbiquitousKeyValueStoreChangeReasonKey

      The value of this key indicates the reason the key-value store changed, as described in Change Reason Values .

      An NSNumber object with an integer value.

      Available in iOS 5.0 and later

    • NSUbiquitousKeyValueStoreChangedKeysKey

      NSUbiquitousKeyValueStoreChangedKeysKey

      The value of this key is an array of NSString objects, where each is the name of a key that changed in the key-value store.

      Available in iOS 5.0 and later

  • Possible values associated with the NSUbiquitousKeyValueStoreChangeReasonKey key.

    Declaration

    Swift

    var NSUbiquitousKeyValueStoreServerChange: Int { get } var NSUbiquitousKeyValueStoreInitialSyncChange: Int { get } var NSUbiquitousKeyValueStoreQuotaViolationChange: Int { get } var NSUbiquitousKeyValueStoreAccountChange: Int { get }

    Objective-C

    enum { NSUbiquitousKeyValueStoreServerChange, NSUbiquitousKeyValueStoreInitialSyncChange, NSUbiquitousKeyValueStoreQuotaViolationChange, NSUbiquitousKeyValueStoreAccountChange };

    Constants

    • NSUbiquitousKeyValueStoreServerChange

      NSUbiquitousKeyValueStoreServerChange

      A value changed in iCloud. This occurs when another device, running another instance of your app and attached to the same iCloud account, uploads a new value.

      Available in iOS 5.0 and later

    • NSUbiquitousKeyValueStoreInitialSyncChange

      NSUbiquitousKeyValueStoreInitialSyncChange

      Your attempt to write to key-value storage was discarded because an initial download from iCloud has not yet happened. That is, before you can first write key-value data, the system must ensure that your app’s local, on-disk cache matches the truth in iCloud.

      Initial downloads happen the first time a device is connected to an iCloud account, and when a user switches their primary iCloud account.

      Available in iOS 5.0 and later

    • NSUbiquitousKeyValueStoreQuotaViolationChange

      NSUbiquitousKeyValueStoreQuotaViolationChange

      Your app’s key-value store has exceeded its space quota on the iCloud server.

      Available in iOS 5.0 and later

    • NSUbiquitousKeyValueStoreAccountChange

      NSUbiquitousKeyValueStoreAccountChange

      The user has changed the primary iCloud account. The keys and values in the local key-value store have been replaced with those from the new account, regardless of the relative timestamps.

      Available in iOS 6.0 and later

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

    This notification is sent only upon a change received from iCloud; it is not sent when your app sets a value.

    The user info dictionary can contain the reason for the notification as well as a list of which values changed, as follows:

    The notification object is the NSUbiquitousKeyValueStore object whose contents changed.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later