iOS Developer Library

Developer

Core Foundation Framework Reference Preferences Utilities Reference

Options
Deployment Target:

On This Page
Language:

Preferences Utilities Reference

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

  • 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.

  • 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.

  • 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.

  • 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.

Constants

Identifying Preference Domains

  • 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.