NSUserDefaults Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/Foundation.framework |
| Availability | Available in iOS 2.0 and later. |
| Companion guide | |
| Declared in | NSUserDefaults.h |
Overview
The NSUserDefaults class provides a programmatic interface for interacting with the defaults system. The defaults system allows an application to customize its behavior to match a user’s preferences. For example, you can allow users to determine what units of measurement your application displays or how often documents are automatically saved. Applications record such preferences by assigning values to a set of parameters in a user’s defaults database. The parameters are referred to as defaults since they’re commonly used to determine an application’s default state at startup or the way it acts by default.
At runtime, you use an NSUserDefaults object to read the defaults that your application uses from a user’s defaults database. NSUserDefaults caches the information to avoid having to open the user’s defaults database each time you need a default value. The synchronize method, which is automatically invoked at periodic intervals, keeps the in-memory cache in sync with a user’s defaults database.
The NSUserDefaults class provides convenience methods for accessing common types such as floats, doubles, integers, Booleans, and URLs. A default object must be a property list, that is, an instance of (or for collections a combination of instances of): NSData, NSString, NSNumber, NSDate, NSArray, or NSDictionary. If you want to store any other type of object, you should typically archive it to create an instance of NSData. For more details, see Preferences and Settings Programming Guide.
Values returned from NSUserDefaults are immutable, even if you set a mutable object as the value. For example, if you set a mutable string as the value for "MyStringDefault", the string you later retrieve using stringForKey: will be immutable.
A defaults database is created automatically for each user. The NSUserDefaults class does not currently support per-host preferences. To do this, you must use the CFPreferences API (see Preferences Utilities Reference). However, NSUserDefaults correctly reads per-host preferences, so you can safely mix CFPreferences code with NSUserDefaults code.
If your application supports managed environments, you can use an NSUserDefaults object to determine which preferences are managed by an administrator for the benefit of the user. Managed environments correspond to computer labs or classrooms where an administrator or teacher may want to configure the systems in a particular way. In these situations, the teacher can establish a set of default preferences and force those preferences on users. If a preference is managed in this manner, applications should prevent users from editing that preference by disabling any appropriate controls.
The NSUserDefaults class is thread-safe.
Persistence of NSURL and file reference URLs
When using NSURL instances to refer to files within a process, it's important to make the distinction between location-based tracking (file: scheme URLs that are basically paths) versus filesystem identity tracking (file: scheme URLs that are file reference URLs). When persisting an NSURL, you should take that behavior into consideration. If your application tracks the resource being located by its identity so that it can be found if the user moves the file, then you should explicitly write the NSURL's bookmark data or encode a file reference URL.
If you want to track a file by reference but you require explicit control over when resolution occurs, you should take care to write out bookmark data to NSUserDefaults rather than rely on -[NSUserDefaults setURL:forKey:]. This allows you to call +[NSURL URLByResolvingBookmarkData:options:relativeToURL:bookmarkDataIsStale:error:] at a time when you know your application will be able to handle the potential I/O or required user interface interactions.
Sandbox Considerations
A sandboxed app cannot access or modify the preferences for any other app. (For example, if you add another app's domain using the addSuiteNamed: method, you do not gain access to that app's preferences.)
Attempting to access or modify with another app's preferences does not result in an error, but when you do, OS X actually reads and writes files located within your app's container, rather than the actual preference files for the other application.
Tasks
Getting the Shared NSUserDefaults Instance
Initializing an NSUserDefaults Object
Registering Defaults
Getting Default Values
-
– arrayForKey: -
– boolForKey: -
– dataForKey: -
– dictionaryForKey: -
– floatForKey: -
– integerForKey: -
– objectForKey: -
– stringArrayForKey: -
– stringForKey: -
– doubleForKey: -
– URLForKey:
Setting Default Values
-
– setBool:forKey: -
– setFloat:forKey: -
– setInteger:forKey: -
– setObject:forKey: -
– setDouble:forKey: -
– setURL:forKey:
Removing Defaults
Maintaining Persistent Domains
-
– synchronize -
– persistentDomainForName: -
– persistentDomainNames -
– removePersistentDomainForName: -
– setPersistentDomain:forName:
Accessing Managed Environment Keys
Managing the Search List
Maintaining Volatile Domains
-
– removeVolatileDomainForName: -
– setVolatileDomain:forName: -
– volatileDomainForName: -
– volatileDomainNames
Maintaining Suites
Class Methods
resetStandardUserDefaults
Synchronizes any changes made to the shared user defaults object and releases it from memory.
Discussion
A subsequent invocation of standardUserDefaults creates a new shared user defaults object with the standard search list.
Availability
- Available in iOS 2.0 and later.
Declared In
NSUserDefaults.hstandardUserDefaults
Returns the shared defaults object.
Return Value
The shared defaults object.
Discussion
If the shared defaults object does not exist yet, it is created with a search list containing the names of the following domains, in this order:
NSArgumentDomain, consisting of defaults parsed from the application’s argumentsA domain identified by the application’s bundle identifier
NSGlobalDomain, consisting of defaults meant to be seen by all applicationsSeparate domains for each of the user’s preferred languages
NSRegistrationDomain, a set of temporary defaults whose values can be set by the application to ensure that searches will always be successful
The defaults are initialized for the current user. Subsequent modifications to the standard search list remain in effect even when this method is invoked again—the search list is guaranteed to be standard only the first time this method is invoked. The shared instance is provided as a convenience—you can create custom instances using alloc along with initWithUser: or init.
Availability
- Available in iOS 2.0 and later.
Declared In
NSUserDefaults.hInstance Methods
addSuiteNamed:
Inserts the specified domain name into the receiver’s search list.
Parameters
- suiteName
The domain name to insert. This domain is inserted after the application domain.
Discussion
The suiteName domain is similar to a bundle identifier string, but is not tied to a particular application or bundle. A suite can be used to hold preferences that are shared between multiple applications.
Availability
- Available in iOS 2.0 and later.
Declared In
NSUserDefaults.harrayForKey:
Returns the array associated with the specified key.
Parameters
- defaultName
A key in the current user's defaults database.
Return Value
The array associated with the specified key, or nil if the key does not exist or its value is not an NSArray object.
Special Considerations
The returned array and its contents are immutable, even if the values you originally set were mutable.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hboolForKey:
Returns the Boolean value associated with the specified key.
Parameters
- defaultName
A key in the current user's defaults database.
Return Value
If a boolean value is associated with defaultName in the user defaults, that value is returned. Otherwise, NO is returned.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hdataForKey:
Returns the data object associated with the specified key.
Parameters
- defaultName
A key in the current user's defaults database.
Return Value
The data object associated with the specified key, or nil if the key does not exist or its value is not an NSData object.
Special Considerations
The returned data object is immutable, even if the value you originally set was a mutable data object.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hdictionaryForKey:
Returns the dictionary object associated with the specified key.
Parameters
- defaultName
A key in the current user's defaults database.
Return Value
The dictionary object associated with the specified key, or nil if the key does not exist or its value is not an NSDictionary object.
Special Considerations
The returned dictionary and its contents are immutable, even if the values you originally set were mutable.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hdictionaryRepresentation
Returns a dictionary that contains a union of all key-value pairs in the domains in the search list.
Return Value
A dictionary containing the keys. The keys are names of defaults and the value corresponding to each key is a property list object (NSData, NSString, NSNumber, NSDate, NSArray, or NSDictionary).
Discussion
As with objectForKey:, key-value pairs in domains that are earlier in the search list take precedence. The combined result does not preserve information about which domain each entry came from.
Availability
- Available in iOS 2.0 and later.
Declared In
NSUserDefaults.hdoubleForKey:
Returns the double value associated with the specified key.
Parameters
- defaultName
A key in the current user's defaults database.
Return Value
The double value associated with the specified key. If the key does not exist, this method returns 0.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hfloatForKey:
Returns the floating-point value associated with the specified key.
Parameters
- defaultName
A key in the current user's defaults database.
Return Value
The floating-point value associated with the specified key. If the key does not exist, this method returns 0.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hinit
Returns an NSUserDefaults object initialized with the defaults for the current user account.
Return Value
An initialized NSUserDefaults object whose argument and registration domains are already set up.
Discussion
This method does not put anything in the search list. Invoke it only if you’ve allocated your own NSUserDefaults instance instead of using the shared one.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hinitWithUser:
Returns an NSUserDefaults object initialized with the defaults for the specified user account.
Parameters
- username
The name of the user account.
Return Value
An initialized NSUserDefaults object whose argument and registration domains are already set up. If the current user does not have access to the specified user account, this method returns nil.
Discussion
This method does not put anything in the search list. Invoke it only if you’ve allocated your own NSUserDefaults instance instead of using the shared one.
You do not normally use this method to initialize an instance of NSUserDefaults. Applications used by a superuser might use this method to update the defaults databases for a number of users. The user who started the application must have appropriate access (read, write, or both) to the defaults database of the new user, or this method returns nil.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hintegerForKey:
Returns the integer value associated with the specified key..
Parameters
- defaultName
A key in the current user's defaults database.
Return Value
The integer value associated with the specified key. If the specified key does not exist, this method returns 0.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hobjectForKey:
Returns the object associated with the first occurrence of the specified default.
Parameters
- defaultName
A key in the current user's defaults database.
Return Value
The object associated with the specified key, or nil if the key was not found.
Discussion
This method searches the domains included in the search list in the order they are listed.
Special Considerations
The returned object is immutable, even if the value you originally set was mutable.
Availability
- Available in iOS 2.0 and later.
Declared In
NSUserDefaults.hobjectIsForcedForKey:
Returns a Boolean value indicating whether the specified key is managed by an administrator.
Parameters
- key
The key whose status you want to check.
Return Value
YES if the value of the specified key is managed by an administrator, otherwise NO.
Discussion
This method assumes that the key is a preference associated with the current user and application. For managed keys, the application should disable any user interface that allows the user to modify the value of key.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hobjectIsForcedForKey:inDomain:
Returns a Boolean value indicating whether the key in the specified domain is managed by an administrator.
Parameters
- key
The key whose status you want to check.
- domain
The domain of the key.
Return Value
YES if the key is managed by an administrator in the specified domain, otherwise NO.
Discussion
This method assumes that the key is a preference associated with the current user. For managed keys, the application should disable any user interface that allows the user to modify the value of key.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hpersistentDomainForName:
Returns a dictionary containing the keys and values in the specified persistent domain.
Parameters
- domainName
The domain whose keys and values you want. This value should be equal to your application's bundle identifier.
Return Value
A dictionary containing the keys. The keys are names of defaults and the value corresponding to each key is a property list object (NSData, NSString, NSNumber, NSDate, NSArray, or NSDictionary).
Availability
- Available in iOS 2.0 and later.
Declared In
NSUserDefaults.hpersistentDomainNames
Returns an array of the current persistent domain names.
Return Value
An array of NSString objects containing the domain names.
Discussion
You can get the keys and values for each domain by passing the returned domain names to the persistentDomainForName: method.
Availability
- Available in iOS 2.0 and later.
Declared In
NSUserDefaults.hregisterDefaults:
Adds the contents of the specified dictionary to the registration domain.
Parameters
- dictionary
The dictionary of keys and values you want to register.
Discussion
If there is no registration domain, one is created using the specified dictionary, and NSRegistrationDomain is added to the end of the search list.
The contents of the registration domain are not written to disk; you need to call this method each time your application starts. You can place a plist file in the application's Resources directory and call registerDefaults: with the contents that you read in from that file.
Availability
- Available in iOS 2.0 and later.
Declared In
NSUserDefaults.hremoveObjectForKey:
Removes the value of the specified default key in the standard application domain.
Parameters
- defaultName
The key whose value you want to remove.
Discussion
Removing a default has no effect on the value returned by the objectForKey: method if the same key exists in a domain that precedes the standard application domain in the search list.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hremovePersistentDomainForName:
Removes the contents of the specified persistent domain from the user’s defaults.
Parameters
- domainName
The domain whose keys and values you want. This value should be equal to your application's bundle identifier.
Discussion
When a persistent domain is changed, an NSUserDefaultsDidChangeNotification is posted.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hremoveSuiteNamed:
Removes the specified domain name from the receiver’s search list.
Parameters
- suiteName
The domain name to remove.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hremoveVolatileDomainForName:
Removes the specified volatile domain from the user’s defaults.
Parameters
- domainName
The volatile domain you want to remove.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hsetBool:forKey:
Sets the value of the specified default key to the specified Boolean value.
Parameters
- value
The Boolean value to store in the defaults database.
- defaultName
The key with which to associate with the value.
Discussion
Invokes setObject:forKey: as part of its implementation.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hsetDouble:forKey:
Sets the value of the specified default key to the double value.
Parameters
- value
The double value.
- defaultName
The key with which to associate with the value.
Availability
- Available in iOS 2.0 and later.
Declared In
NSUserDefaults.hsetFloat:forKey:
Sets the value of the specified default key to the specified floating-point value.
Parameters
- value
The floating-point value to store in the defaults database.
- defaultName
The key with which to associate with the value.
Discussion
Invokes setObject:forKey: as part of its implementation.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hsetInteger:forKey:
Sets the value of the specified default key to the specified integer value.
Parameters
- value
The integer value to store in the defaults database.
- defaultName
The key with which to associate with the value.
Discussion
Invokes setObject:forKey: as part of its implementation.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hsetObject:forKey:
Sets the value of the specified default key in the standard application domain.
Parameters
- value
The object to store in the defaults database.
- defaultName
The key with which to associate with the value.
Discussion
The value parameter can be only property list objects: NSData, NSString, NSNumber, NSDate, NSArray, or NSDictionary. For NSArray and NSDictionary objects, their contents must be property list objects. See “What is a Property List?” in Property List Programming Guide.
Setting a default has no effect on the value returned by the objectForKey: method if the same key exists in a domain that precedes the application domain in the search list.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hsetPersistentDomain:forName:
Sets the dictionary for the specified persistent domain.
Parameters
- domain
The dictionary of keys and values you want to assign to the domain.
- domainName
The domain whose keys and values you want to set. This value should be equal to your application's bundle identifier.
Discussion
When a persistent domain is changed, an NSUserDefaultsDidChangeNotification is posted.
Availability
- Available in iOS 2.0 and later.
Declared In
NSUserDefaults.hsetURL:forKey:
Sets the value of the specified default key to the specified URL.
Parameters
- url
The
NSURLto store in the defaults database.- defaultName
The key with which to associate with the value.
Discussion
When an NSURL is stored using -[NSUserDefaults setURL:forKey:], some adjustments are made:
Any non-file URL is written by calling
+[NSKeyedArchiver archivedDataWithRootObject:]using the NSURL instance as the root object.Any file reference
file:scheme URL will be treated as a non-file URL, and information which makes this URL compatible with 10.5 systems will also be written as part of the archive as well as its minimal bookmark data.Any path-based file: scheme URL is written by first taking the absolute URL, getting the path from that and then determining if the path can be made relative to the user's home directory. If it can, the string is abbreviated by using
stringByAbbreviatingWithTildeInPathand written out. This allows pre-10.6 clients to read the default and use-[NSString stringByExpandingTildeInPath]to use this information.
Availability
- Available in iOS 4.0 and later.
See Also
Declared In
NSUserDefaults.hsetVolatileDomain:forName:
Sets the dictionary for the specified volatile domain.
Parameters
- domain
The dictionary of keys and values you want to assign to the domain.
- domainName
The domain whose keys and values you want to set.
Discussion
This method raises an NSInvalidArgumentException if a volatile domain with the specified name already exists.
Availability
- Available in iOS 2.0 and later.
Declared In
NSUserDefaults.hstringArrayForKey:
Returns the array of strings associated with the specified key.
Parameters
- defaultName
A key in the current user's defaults database.
Return Value
The array of NSString objects, or nil if the specified default does not exist, the default does not contain an array, or the array does not contain NSString objects.
Special Considerations
The returned array and its contents are immutable, even if the values you originally set were mutable.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hstringForKey:
Returns the string associated with the specified key.
Parameters
- defaultName
A key in the current user's defaults database.
Return Value
The string associated with the specified key, or nil if the default does not exist or does not contain a string.
Special Considerations
The returned string is immutable, even if the value you originally set was a mutable string.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hsynchronize
Writes any modifications to the persistent domains to disk and updates all unmodified persistent domains to what is on disk.
Return Value
YES if the data was saved successfully to disk, otherwise NO.
Discussion
Because this method is automatically invoked at periodic intervals, use this method only if you cannot wait for the automatic synchronization (for example, if your application is about to exit) or if you want to update the user defaults to what is on disk even though you have not made any changes.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSUserDefaults.hURLForKey:
Returns the NSURL instance associated with the specified key.
Parameters
- defaultName
A key in the current user's defaults database.
Return Value
The NSURL instance value associated with the specified key. If the key does not exist, this method returns nil.
Discussion
When an NSURL is read using -[NSUserDefaults URLForKey:], the following logic is used:
If the value for the key is an
NSData, theNSDatais used as the argument to+[NSKeyedUnarchiver unarchiveObjectWithData:]. If theNSDatacan be unarchived as an NSURL, the NSURL is returned otherwise nil is returned.If the value for this key was a file reference URL, the file reference URL will be created but its bookmark data will not be resolved until the NSURL instance is later used (e.g. at
-[NSData initWithContentsOfURL:]).If the value for the key is an NSString which begins with a ~, the NSString will be expanded using
-[NSString stringByExpandingTildeInPath]and a file: scheme NSURL will be created from that.
Availability
- Available in iOS 4.0 and later.
See Also
Declared In
NSUserDefaults.hvolatileDomainForName:
Returns the dictionary for the specified volatile domain.
Parameters
- domainName
The domain whose keys and values you want.
Return Value
The dictionary of keys and values belonging to the domain. The keys in the dictionary are names of defaults, and the value corresponding to each key is a property list object (NSData, NSString, NSNumber, NSDate, NSArray, or NSDictionary).
Availability
- Available in iOS 2.0 and later.
Declared In
NSUserDefaults.hvolatileDomainNames
Returns an array of the current volatile domain names.
Return Value
An array of NSString objects with the volatile domain names.
Discussion
You can get the contents of each domain by passing the returned domain names to the volatileDomainForName: method.
Availability
- Available in iOS 2.0 and later.
Declared In
NSUserDefaults.hConstants
NSUserDefaults Domains
These constants specify various user defaults domains.
extern NSString *NSGlobalDomain; extern NSString *NSArgumentDomain; extern NSString *NSRegistrationDomain;
Constants
NSGlobalDomainThe domain consisting of defaults meant to be seen by all applications.
Available in iOS 2.0 and later.
Declared in
NSUserDefaults.h.NSArgumentDomainThe domain consisting of defaults parsed from the application’s arguments. These are one or more pairs of the form -default value included in the command-line invocation of the application.
Available in iOS 2.0 and later.
Declared in
NSUserDefaults.h.NSRegistrationDomainThe domain consisting of a set of temporary defaults whose values can be set by the application to ensure that searches will always be successful.
Available in iOS 2.0 and later.
Declared in
NSUserDefaults.h.
Declared In
NSUserDefaults.hNotifications
NSUserDefaultsDidChangeNotification
The notification object is the NSUserDefaults object. This notification does not contain a userInfo dictionary.
Availability
- Available in iOS 2.0 and later.
Declared In
NSUserDefaults.h© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-01-09)