Preferences Utilities Reference

Inherits From

Not Applicable

Conforms To

Not Applicable

Import Statement

Objective-C

@import CoreFoundation;

Swift

import CoreFoundation

Availability

Not Applicable

Core Foundation provides a simple, standard way to manage user (and application) preferences. Core Foundation stores preferences as key-value pairs that are assigned a scope using a combination of user name, application ID, and host (computer) names. This makes it possible to save and retrieve preferences that apply to different classes of users. Core Foundation preferences is useful to all applications that support user preferences. Note that modification of some preferences domains (those not belonging to the “Current User”) requires root privileges (or Admin privileges prior to OS X v10.6)—see Authorization Services Programming Guide for information on how to gain suitable privileges.

Unlike some other Core Foundation types, CFPreferences is not toll-free bridged to its corresponding Cocoa Foundation framework class (NSUserDefaults). CFPreferences is thread-safe.

Functions

Getting Preference Values


    
      
           CFPreferencesCopyAppValue(_:_:)
      
      
           CFPreferencesCopyAppValue

Obtains a preference value for the specified key and application.

Declaration

Swift

func CFPreferencesCopyAppValue(_ key: CFString!, _ applicationID: CFString!) -> CFPropertyList!

Objective-C

CFPropertyListRef CFPreferencesCopyAppValue ( CFStringRef key, CFStringRef applicationID );

Parameters

`key`	The preference key whose value to obtain.
`applicationID`	The identifier of the application whose preferences to search, typically `kCFPreferencesCurrentApplication`. Do not pass `NULL` or `kCFPreferencesAnyApplication`. Takes the form of a Java package name, `com.foosoft`.

Return Value

The preference data for the specified key and application. If no value was located, returns NULL. Ownership follows the Create Rule.

Discussion

Note that values returned from this function are immutable, even if you have recently set the value using a mutable object.

Availability

Available in iOS 2.0 and later.


    
      
           CFPreferencesCopyKeyList(_:_:_:)
      
      
           CFPreferencesCopyKeyList

Constructs and returns the list of all keys set in the specified domain.

Declaration

Swift

func CFPreferencesCopyKeyList(_ applicationID: CFString!, _ userName: CFString!, _ hostName: CFString!) -> CFArray!

Objective-C

CFArrayRef CFPreferencesCopyKeyList ( CFStringRef applicationID, CFStringRef userName, CFStringRef hostName );

Parameters

`applicationID`	The ID of the application whose preferences to search. Takes the form of a Java package name, `com.foosoft`.
`userName`	`kCFPreferencesCurrentUser` to search the current-user domain, otherwise `kCFPreferencesAnyUser` to search the any-user domain.
`hostName`	`kCFPreferencesCurrentHost` to search the current-host domain, otherwise `kCFPreferencesAnyHost` to search the any-host domain.

Return Value

The list of keys. Ownership follows the Create Rule.

Availability

Available in iOS 2.0 and later.


    
      
           CFPreferencesCopyMultiple(_:_:_:_:)
      
      
           CFPreferencesCopyMultiple

Returns a dictionary containing preference values for multiple keys.

Declaration

Swift

func CFPreferencesCopyMultiple(_ keysToFetch: CFArray!, _ applicationID: CFString!, _ userName: CFString!, _ hostName: CFString!) -> CFDictionary!

Objective-C

CFDictionaryRef CFPreferencesCopyMultiple ( CFArrayRef keysToFetch, CFStringRef applicationID, CFStringRef userName, CFStringRef hostName );

Parameters

`keysToFetch`	An array of preference keys the values of which to obtain.
`applicationID`	The ID of the application whose preferences are searched. Takes the form of a Java package name, such as `com.foosoft`.
`userName`	`kCFPreferencesCurrentUser` to search the current-user domain, otherwise `kCFPreferencesAnyUser` to search the any-user domain.
`hostName`	`kCFPreferencesCurrentHost` to search the current-host domain, otherwise `kCFPreferencesAnyHost` to search the any-host domain.

Return Value

A dictionary containing the preference values for the keys specified by keysToFetch for the specified domain. If no values were located, returns an empty dictionary. Ownership follows the Create Rule.

Discussion

Note that values returned from this function are immutable, even if you have recently set the value using a mutable object.

Availability

Available in iOS 2.0 and later.


    
      
           CFPreferencesCopyValue(_:_:_:_:)
      
      
           CFPreferencesCopyValue

Returns a preference value for a given domain.

Declaration

Swift

func CFPreferencesCopyValue(_ key: CFString!, _ applicationID: CFString!, _ userName: CFString!, _ hostName: CFString!) -> CFPropertyList!

Objective-C

CFPropertyListRef CFPreferencesCopyValue ( CFStringRef key, CFStringRef applicationID, CFStringRef userName, CFStringRef hostName );

Parameters

`key`	Preferences key for the value to obtain.
`applicationID`	The ID of the application whose preferences are searched. Takes the form of a Java package name, such as `com.foosoft`.
`userName`	`kCFPreferencesCurrentUser` if to search the current-user domain, otherwise `kCFPreferencesAnyUser` to search the any-user domain.
`hostName`	`kCFPreferencesCurrentHost` if to search the current-host domain, otherwise `kCFPreferencesAnyHost` to search the any-host domain.

Return Value

The preference data for the specified domain. If the no value was located, returns NULL. Ownership follows the Create Rule.

Discussion

This function is the primitive get mechanism for the higher level preference function CFPreferencesCopyAppValue Unlike the high-level function, CFPreferencesCopyValue searches only the exact domain specified. Do not use this function directly unless you have a need. All arguments must be non-NULL. Do not use arbitrary user and host names, instead pass the pre-defined domain qualifier constants.

Note that values returned from this function are immutable, even if you have recently set the value using a mutable object.

Availability

Available in iOS 2.0 and later.


    
      
           CFPreferencesGetAppBooleanValue(_:_:_:)
      
      
           CFPreferencesGetAppBooleanValue

Convenience function that directly obtains a boolean preference value for the specified key.

Declaration

Swift

func CFPreferencesGetAppBooleanValue(_ key: CFString!, _ applicationID: CFString!, _ keyExistsAndHasValidFormat: UnsafeMutablePointer<DarwinBoolean>) -> Bool

Objective-C

Boolean CFPreferencesGetAppBooleanValue ( CFStringRef key, CFStringRef applicationID, Boolean *keyExistsAndHasValidFormat );

Parameters

`key`	The preference key whose value to obtain. The key must specify a preference whose value is of type `Boolean`.
`applicationID`	The identifier of the application whose preferences are searched, typically `kCFPreferencesCurrentApplication`. Do not pass `NULL` or `kCFPreferencesAnyApplication`. Takes the form of a Java package name, such as `com.foosoft`.
`keyExistsAndHasValidFormat`	On return, `true` if the preference value for the specified key was located and found to be of type `Boolean`, otherwise `false`.

Return Value

The preference data for the specified key and application, or if no value was located, false.

Availability

Available in iOS 2.0 and later.


    
      
           CFPreferencesGetAppIntegerValue(_:_:_:)
      
      
           CFPreferencesGetAppIntegerValue

Convenience function that directly obtains an integer preference value for the specified key.

Declaration

Swift

func CFPreferencesGetAppIntegerValue(_ key: CFString!, _ applicationID: CFString!, _ keyExistsAndHasValidFormat: UnsafeMutablePointer<DarwinBoolean>) -> CFIndex

Objective-C

CFIndex CFPreferencesGetAppIntegerValue ( CFStringRef key, CFStringRef applicationID, Boolean *keyExistsAndHasValidFormat );

Parameters

`key`	The preference key whose value you wish to obtain. The key must specify a preference whose value is of type `int`.
`applicationID`	The identifier of the application whose preferences you wish to search, typically `kCFPreferencesCurrentApplication`. Do not pass `NULL` or `kCFPreferencesAnyApplication`. Takes the form of a Java package name, `com.foosoft`.
`keyExistsAndHasValidFormat`	On return, indicates whether the preference value for the specified key was located and found to be of type `int`.

Return Value

The preference data for the specified key and application. If no value was located, 0 is returned.

Availability

Available in iOS 2.0 and later.

Setting Preference Values


    
      
           CFPreferencesSetAppValue(_:_:_:)
      
      
           CFPreferencesSetAppValue

Adds, modifies, or removes a preference.

Declaration

Swift

func CFPreferencesSetAppValue(_ key: CFString!, _ value: CFPropertyList!, _ applicationID: CFString!)

Objective-C

void CFPreferencesSetAppValue ( CFStringRef key, CFPropertyListRef value, CFStringRef applicationID );

Parameters

`key`	The preference key whose value you wish to set.
`value`	The value to set for the specified `key` and application. Pass `NULL` to remove the specified key from the application’s preferences.
`applicationID`	The ID of the application whose preferences you wish to create or modify, typically `kCFPreferencesCurrentApplication`. Do not pass `NULL` or `kCFPreferencesAnyApplication`. Takes the form of a Java package name, `com.foosoft`.

Discussion

New preference values are stored in the standard application preference location, ~/Library/Preferences/. When called with kCFPreferencesCurrentApplication, modifications are performed in the preference domain “Current User, Current Application, Any Host.” If you need to create preferences in some other domain, use the low-level function CFPreferencesSetValue.

You must call the CFPreferencesAppSynchronize function in order for your changes to be saved to permanent storage.

Availability

Available in iOS 2.0 and later.


    
      
           CFPreferencesSetMultiple(_:_:_:_:_:)
      
      
           CFPreferencesSetMultiple

Convenience function that allows you to set and remove multiple preference values.

Declaration

Swift

func CFPreferencesSetMultiple(_ keysToSet: CFDictionary!, _ keysToRemove: CFArray!, _ applicationID: CFString!, _ userName: CFString!, _ hostName: CFString!)

Objective-C

void CFPreferencesSetMultiple ( CFDictionaryRef keysToSet, CFArrayRef keysToRemove, CFStringRef applicationID, CFStringRef userName, CFStringRef hostName );

Parameters

`keysToSet`	A dictionary containing the key/value pairs for the preferences to set.
`keysToRemove`	An array containing a list of keys to remove.
`applicationID`	The ID of the application whose preferences you wish to modify. Takes the form of a Java package name, `com.foosoft`.
`userName`	`kCFPreferencesCurrentUser` to modify the current user’s preferences, otherwise `kCFPreferencesAnyUser` to modify the preferences of all users.
`hostName`	`kCFPreferencesCurrentHost` to modify the preferences of the current host, otherwise `kCFPreferencesAnyHost` to modify the preferences of all hosts.

Discussion

Behavior is undefined if a key is in both keysToSet and keysToRemove

Availability

Available in iOS 2.0 and later.


    
      
           CFPreferencesSetValue(_:_:_:_:_:)
      
      
           CFPreferencesSetValue

Adds, modifies, or removes a preference value for the specified domain.

Declaration

Swift

func CFPreferencesSetValue(_ key: CFString!, _ value: CFPropertyList!, _ applicationID: CFString!, _ userName: CFString!, _ hostName: CFString!)

Objective-C

void CFPreferencesSetValue ( CFStringRef key, CFPropertyListRef value, CFStringRef applicationID, CFStringRef userName, CFStringRef hostName );

Parameters

`key`	Preferences key for the value you wish to set.
`value`	The value to set for `key` and application. Pass `NULL` to remove `key` from the domain.
`applicationID`	The ID of the application whose preferences you wish to modify. Takes the form of a Java package name, `com.foosoft`.
`userName`	`kCFPreferencesCurrentUser` to modify the current user’s preferences, otherwise `kCFPreferencesAnyUser` to modify the preferences of all users.
`hostName`	`kCFPreferencesCurrentHost` to modify the preferences of the current host, otherwise `kCFPreferencesAnyHost` to modify the preferences of all hosts.

Discussion

This function is the primitive set mechanism for the higher level preference function CFPreferencesSetAppValue. Only the exact domain specified is modified. Do not use this function directly unless you have a specific need. All arguments except value must be non-NULL. Do not use arbitrary user and host names, instead pass the pre-defined constants.

You must call the CFPreferencesSynchronize function in order for your changes to be saved to permanent storage. Note that you can only save preferences for “Any User” if you have root privileges (or Admin privileges prior to OS X v10.6).

Availability

Available in iOS 2.0 and later.

Synchronizing Preferences


    
      
           CFPreferencesAppSynchronize(_:)
      
      
           CFPreferencesAppSynchronize

Writes to permanent storage all pending changes to the preference data for the application, and reads the latest preference data from permanent storage.

Declaration

Swift

func CFPreferencesAppSynchronize(_ applicationID: CFString!) -> Bool

Objective-C

Boolean CFPreferencesAppSynchronize ( CFStringRef applicationID );

Parameters


  applicationID

The ID of the application whose preferences to write to storage, typically kCFPreferencesCurrentApplication. Do not pass NULL or kCFPreferencesAnyApplication. Takes the form of a Java package name, com.foosoft.

Return Value

true if synchronization was successful, otherwise false.

Discussion

Calling the function CFPreferencesSetAppValue is not in itself sufficient for storing preferences. The CFPreferencesAppSynchronize function writes to permanent storage all pending preference changes for the application. Typically you would call this function after multiple calls to CFPreferencesSetAppValue. Conversely, preference data is cached after it is first read. Changes made externally are not automatically incorporated. The CFPreferencesAppSynchronize function reads the latest preferences from permanent storage.

Availability

Available in iOS 2.0 and later.


    
      
           CFPreferencesSynchronize(_:_:_:)
      
      
           CFPreferencesSynchronize

For the specified domain, writes all pending changes to preference data to permanent storage, and reads latest preference data from permanent storage.

Declaration

Swift

func CFPreferencesSynchronize(_ applicationID: CFString!, _ userName: CFString!, _ hostName: CFString!) -> Bool

Objective-C

Boolean CFPreferencesSynchronize ( CFStringRef applicationID, CFStringRef userName, CFStringRef hostName );

Parameters

`applicationID`	The ID of the application whose preferences you wish to modify. Takes the form of a Java package name, `com.foosoft`.
`userName`	`kCFPreferencesCurrentUser` to modify the current user’s preferences, otherwise `kCFPreferencesAnyUser` to modify the preferences of all users.
`hostName`	`kCFPreferencesCurrentHost` to search the current-host domain, otherwise `kCFPreferencesAnyHost` to search the any-host domain.

Return Value

true if synchronization was successful, false if an error occurred.

Discussion

This function is the primitive synchronize mechanism for the higher level preference function CFPreferencesAppSynchronize; it writes updated preferences to permanent storage, and reads the latest preferences from permanent storage. Only the exact domain specified is modified. Note that to modify “Any User” preferences requires root privileges (or Admin privileges prior to OS X v10.6)—see Authorization Services Programming Guide.

Do not use this function directly unless you have a specific need. All arguments must be non- NULL. Do not use arbitrary user and host names, instead pass the pre-defined constants.

Availability

Available in iOS 2.0 and later.

Adding and Removing Suite Preferences


    
      
           CFPreferencesAddSuitePreferencesToApp(_:_:)
      
      
           CFPreferencesAddSuitePreferencesToApp

Adds suite preferences to an application’s preference search chain.

Declaration

Swift

func CFPreferencesAddSuitePreferencesToApp(_ applicationID: CFString!, _ suiteID: CFString!)

Objective-C

void CFPreferencesAddSuitePreferencesToApp ( CFStringRef applicationID, CFStringRef suiteID );

Parameters

`applicationID`	The ID of the application to which to add suite preferences, typically `kCFPreferencesCurrentApplication`. Do not pass `NULL` or `kCFPreferencesAnyApplication`. Takes the form of a Java package name, `com.foosoft`.
`suiteID`	The ID of the application suite preferences to add. Takes the form of a Java package name, `com.foosoft`.

Discussion

Suite preferences allow you to maintain a set of preferences that are common to all applications in the suite. When a suite is added to an application’s search chain, all of the domains pertaining to that suite are inserted into the chain. Suite preferences are added between the “Current Application” domains and the “Any Application” domains. If you add multiple suite preferences to one application, the order of the suites in the search chain is non-deterministic. You can override a suite preference for a given application by defining the same preference key in the application specific preferences.

Availability

Available in iOS 2.0 and later.


    
      
           CFPreferencesRemoveSuitePreferencesFromApp(_:_:)
      
      
           CFPreferencesRemoveSuitePreferencesFromApp

Removes suite preferences from an application’s search chain.

Declaration

Swift

func CFPreferencesRemoveSuitePreferencesFromApp(_ applicationID: CFString!, _ suiteID: CFString!)

Objective-C

void CFPreferencesRemoveSuitePreferencesFromApp ( CFStringRef applicationID, CFStringRef suiteID );

Parameters

`applicationID`	The ID of the application from which to remove suite preferences, typically `kCFPreferencesCurrentApplication`. Do not pass `NULL` or `kCFPreferencesAnyApplication`. Takes the form of a Java package name, `com.foosoft`.
`suiteID`	The ID of the application suite preferences to remove. Takes the form of a Java package name, `com.foosoft`.

Availability

Available in iOS 2.0 and later.

Miscellaneous Functions


    
      
           CFPreferencesAppValueIsForced(_:_:)
      
      
           CFPreferencesAppValueIsForced

Determines whether or not a given key has been imposed on the user.

Declaration

Swift

func CFPreferencesAppValueIsForced(_ key: CFString!, _ applicationID: CFString!) -> Bool

Objective-C

Boolean CFPreferencesAppValueIsForced ( CFStringRef key, CFStringRef applicationID );

Parameters

`key`	The key you are querying.
`applicationID`	The application’s ID, typically `kCFPreferencesCurrentApplication`. Do not pass `NULL` or `kCFPreferencesAnyApplication`. Takes the form of a Java package name, `com.foosoft`.

Return Value

true if value of the key cannot be changed by the user, otherwise false.

Discussion

In cases where machines and/or users are under some kind of management, you should use this function to determine whether or not to disable UI elements corresponding to those preference keys.

Availability

Available in iOS 2.0 and later.


    
      
           CFPreferencesCopyApplicationList

(iOS 7.0)

Constructs and returns the list of all applications that have preferences in the scope of the specified user and host.

Declaration

Objective-C

CFArrayRef CFPreferencesCopyApplicationList ( CFStringRef userName, CFStringRef hostName );

Parameters

`userName`	`kCFPreferencesCurrentUser` to search the current-user domain, otherwise `kCFPreferencesAnyUser` to search the any-user domain.
`hostName`	`kCFPreferencesCurrentHost` to search the current-host domain, otherwise `kCFPreferencesAnyHost` to search the any-host domain.

Return Value

The list of application IDs. Ownership follows the Create Rule.

Availability

Available in iOS 2.0 and later.

Deprecated in iOS 7.0.

Constants

Identifying Preference Domains

Application, Host, and User Keys
Keys used to specify the common preference domains.

Declaration

Swift

let kCFPreferencesAnyApplication: CFString! let kCFPreferencesAnyHost: CFString! let kCFPreferencesAnyUser: CFString! let kCFPreferencesCurrentApplication: CFString! let kCFPreferencesCurrentHost: CFString! let kCFPreferencesCurrentUser: CFString!

Objective-C

const CFStringRef kCFPreferencesAnyApplication; const CFStringRef kCFPreferencesAnyHost; const CFStringRef kCFPreferencesAnyUser; const CFStringRef kCFPreferencesCurrentApplication; const CFStringRef kCFPreferencesCurrentHost; const CFStringRef kCFPreferencesCurrentUser;

Constants
- kCFPreferencesAnyApplication
  
  kCFPreferencesAnyApplication
  
  Indicates a preference that applies to any application.
  
  Available in iOS 2.0 and later.
- kCFPreferencesAnyHost
  
  kCFPreferencesAnyHost
  
  Indicates a preference that applies to any host.
  
  This option is not supported.
  
  Available in iOS 2.0 and later.
- kCFPreferencesAnyUser
  
  kCFPreferencesAnyUser
  
  Indicates a preference that applies to any user.
  
  Available in iOS 2.0 and later.
- kCFPreferencesCurrentApplication
  
  kCFPreferencesCurrentApplication
  
  Indicates a preference that applies only to the current application.
  
  Available in iOS 2.0 and later.
- kCFPreferencesCurrentHost
  
  kCFPreferencesCurrentHost
  
  Indicates a preference that applies only to the current host.
  
  Available in iOS 2.0 and later.
- kCFPreferencesCurrentUser
  
  kCFPreferencesCurrentUser
  
  Indicates a preference that applies only to the current user.
  
  Available in iOS 2.0 and later.
Discussion

Not all combinations of application, host, and user are supported preference domains. Specifically, kCFPreferencesAnyHost is not supported in any combination with other options.