Class: NSUbiquitousKeyValueStore

Inherits:
NSObject show all

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.

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from NSObject

#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version

Constructor Details

This class inherits a constructor from NSObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class NSObject

Class Method Details

+ (NSUbiquitousKeyValueStore) defaultStore

Returns the shared iCloud key-value store object. 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.

Returns:

Instance Method Details

- (Array) arrayForKey(aKey)

Returns the array associated with the specified key.

Parameters:

  • aKey (String) —

    A key in the key-value store.

Returns:

  • (Array) —

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

- (Boolean) boolForKey(aKey)

Returns the Boolean value associated with the specified key.

Parameters:

  • aKey (String) —

    A key in the key-value store.

Returns:

  • (Boolean) —

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

- (NSData) dataForKey(aKey)

Returns the data object associated with the specified key.

Parameters:

  • aKey (String) —

    A key in the key-value store.

Returns:

  • (NSData) —

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

- (Hash) dictionaryForKey(aKey)

Returns the dictionary object associated with the specified key.

Parameters:

  • aKey (String) —

    A key in the key-value store.

Returns:

  • (Hash) —

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

- (Hash) dictionaryRepresentation

Returns a dictionary containing all of the key-value pairs in the key-value store. 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.

Returns:

  • (Hash) —

    A dictionary containing the key and value data in the key-value store.

- (Float) doubleForKey(aKey)

Returns the double value associated with the specified key.

Parameters:

  • aKey (String) —

    A key in the key-value store.

Returns:

  • (Float) —

    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.

- (Integer) longLongForKey(aKey)

Returns the long long value associated with the specified key.

Parameters:

  • aKey (String) —

    A key in the key-value store.

Returns:

  • (Integer) —

    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.

- (Object) objectForKey(aKey)

Returns the object associated with the specified key. 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.

Parameters:

  • aKey (String) —

    A key in the key-value store.

Returns:

  • (Object) —

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

- (Object) removeObjectForKey(aKey)

Removes the value associated with the specified key from the key-value store. 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.

Parameters:

  • aKey (String) —

    The key corresponding to the value you want to remove.

Returns:

- (Object) setArray(anArray, forKey:aKey)

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

Parameters:

  • anArray (Array) —

    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 (String) —

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

Returns:

- (Object) setBool(value, forKey:aKey)

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

Parameters:

  • value (Boolean) —

    The Boolean value to store.

  • aKey (String) —

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

Returns:

- (Object) setData(aData, forKey:aKey)

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

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.

Parameters:

  • aData (NSData) —

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

  • aKey (String) —

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

Returns:

- (Object) setDictionary(aDictionary, forKey:aKey)

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

Parameters:

  • aDictionary (Hash) —

    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 (String) —

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

Returns:

- (Object) setDouble(value, forKey:aKey)

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

Parameters:

  • value (Float) —

    The double value to store.

  • aKey (String) —

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

Returns:

- (Object) setLongLong(value, forKey:aKey)

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

Parameters:

  • value (Integer) —

    The long long value to store.

  • aKey (String) —

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

Returns:

- (Object) setObject(anObject, forKey:aKey)

Sets an object for the specified key in the key-value store. 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.

Parameters:

  • anObject (Object) —

    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 (String) —

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

Returns:

- (Object) setString(aString, forKey:aKey)

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

Parameters:

  • aString (String) —

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

  • aKey (String) —

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

Returns:

- (String) stringForKey(aKey)

Returns the string associated with the specified key.

Parameters:

  • aKey (String) —

    A key in the key-value store.

Returns:

  • (String) —

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

- (Boolean) synchronize

Explicitly synchronizes in-memory keys and values with those stored on disk. 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.

Returns:

  • (Boolean) —

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