Mac Developer Library

Developer

SystemConfiguration Framework Reference SCPreferences Reference

Options
Deployment Target:

On This Page
Language:

SCPreferences Reference

The SCPreferences programming interface allows an application to load and store XML configuration data in a controlled manner and provide the necessary notifications to other applications that need to be aware of configuration changes.

To access configuration preferences, you must first establish a preferences session using the SCPreferencesCreate function. To identify a specific set of preferences to access, you pass a value in the prefsID parameter. A NULL value indicates that the default system preferences are to be accessed. A string that starts with a leading "/" character specifies the absolute path to the file containing the preferences to be accessed. A string that does not start with a leading "/" character specifies a file relative to the default system preferences directory.

When you are finished with the preferences session, use the CFRelease function to release it.

Functions

  • Initiates access to the per-system set of configuration preferences.

    Declaration

    Swift

    func SCPreferencesCreate(_ allocator: CFAllocator!, _ name: CFString!, _ prefsID: CFString!) -> Unmanaged<SCPreferences>!

    Objective-C

    SCPreferencesRef SCPreferencesCreate ( CFAllocatorRef allocator, CFStringRef name, CFStringRef prefsID );

    Parameters

    allocator

    The allocator to use to allocate memory for this preferences session. If the value is not a valid CFAllocator, the behavior is undefined. Pass NULL or kCFAllocatorDefault to use the current default CFAllocator.

    name

    The name of the calling process.

    prefsID

    The name of the group of preferences to be accessed or updated. A name that starts with a leading "/" character specifies the absolute path to the file containing the preferences to be accessed. A name that does not start with a leading "/" character specifies a file relative to the default system preferences directory.

    To access the default system preferences, pass in NULL.

    Return Value

    A reference to the new preferences session. You must release the returned value.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

  • Initiates access to the per-system set of configuration preferences with the specified authorization.

    Declaration

    Swift

    func SCPreferencesCreateWithAuthorization(_ allocator: CFAllocator!, _ name: CFString!, _ prefsID: CFString!, _ authorization: AuthorizationRef) -> Unmanaged<SCPreferences>!

    Objective-C

    SCPreferencesRef SCPreferencesCreateWithAuthorization ( CFAllocatorRef allocator, CFStringRef name, CFStringRef prefsID, AuthorizationRef authorization );

    Parameters

    allocator

    The allocator to use to allocate memory for this preferences session. If the value is not a valid CFAllocator, the behavior is undefined. Pass NULL or kCFAllocatorDefault to use the current default CFAllocator.

    name

    The name of the calling process.

    prefsID

    The name of the group of preferences to be accessed or updated. A name that starts with a leading "/" character specifies the absolute path to the file containing the preferences to be accessed. A name that does not start with a leading "/" character specifies a file relative to the default system preferences directory.

    To access the default system preferences, pass in NULL.

    authorization

    An authorization reference that is used to authorize any access to the enhanced privileges needed to manage the preferences session.

    Return Value

    A reference to the new preferences session. You must release the returned value.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.5 and later.

  • Returns the type identifier of all SCPreferences instances.

    Declaration

    Swift

    func SCPreferencesGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID SCPreferencesGetTypeID ( void );

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

  • Returns the currently defined preference keys.

    Declaration

    Swift

    func SCPreferencesCopyKeyList(_ prefs: SCPreferences!) -> Unmanaged<CFArray>!

    Objective-C

    CFArrayRef SCPreferencesCopyKeyList ( SCPreferencesRef prefs );

    Parameters

    prefs

    The preferences session.

    Return Value

    An array of currently defined preference keys. You must release the returned value.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

  • Returns a value that can be used to determine if the saved configuration preferences have changed.

    Declaration

    Swift

    func SCPreferencesGetSignature(_ prefs: SCPreferences!) -> Unmanaged<CFData>!

    Objective-C

    CFDataRef SCPreferencesGetSignature ( SCPreferencesRef prefs );

    Parameters

    prefs

    The preferences session.

    Return Value

    Data that reflects the signature of the configuration preferences at the time of the call to the SCPreferencesCreate function.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

  • Associates the specified value with the specified preference key.

    Declaration

    Swift

    func SCPreferencesAddValue(_ prefs: SCPreferences!, _ key: CFString!, _ value: CFPropertyList!) -> Boolean

    Objective-C

    Boolean SCPreferencesAddValue ( SCPreferencesRef prefs, CFStringRef key, CFPropertyListRef value );

    Parameters

    prefs

    The preferences session.

    key

    The preference key.

    value

    The value to associate with the preference key.

    Return Value

    TRUE if the value was added; FALSE if the key already exists or if an error occurred.

    Discussion

    To commit these changes to permanent storage, you must call SCPreferencesCommitChanges.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

  • Retrieves the value associated with the specified preference key.

    Declaration

    Swift

    func SCPreferencesGetValue(_ prefs: SCPreferences!, _ key: CFString!) -> Unmanaged<CFPropertyList>!

    Objective-C

    CFPropertyListRef SCPreferencesGetValue ( SCPreferencesRef prefs, CFStringRef key );

    Parameters

    prefs

    The preferences session.

    key

    The preference key.

    Return Value

    The value associated with the specified preference key (can be NULL if no value exists).

    Discussion

    To avoid inadvertantly reading stale data, first call SCPreferencesLock before calling this function.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

  • Updates the data associated with the specified preference key with the specified value.

    Declaration

    Swift

    func SCPreferencesSetValue(_ prefs: SCPreferences!, _ key: CFString!, _ value: CFPropertyList!) -> Boolean

    Objective-C

    Boolean SCPreferencesSetValue ( SCPreferencesRef prefs, CFStringRef key, CFPropertyListRef value );

    Parameters

    prefs

    The preferences session.

    key

    The preference key.

    value

    The value to associate with the preference key.

    Return Value

    TRUE if the value was set; FALSE if an error occurred.

    Discussion

    This function adds or replaces the value associated with the specified key. To commit these changes to permanent storage you must call SCPreferencesCommitChanges.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

  • Removes the data associated with the specified preference key.

    Declaration

    Swift

    func SCPreferencesRemoveValue(_ prefs: SCPreferences!, _ key: CFString!) -> Boolean

    Objective-C

    Boolean SCPreferencesRemoveValue ( SCPreferencesRef prefs, CFStringRef key );

    Parameters

    prefs

    The preferences session.

    key

    The preference key.

    Return Value

    TRUE if the value was removed; FALSE if the key does not exist or if an error occurred.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

  • Requests that the currently stored configuration preferences be applied to the active configuration.

    Declaration

    Swift

    func SCPreferencesApplyChanges(_ prefs: SCPreferences!) -> Boolean

    Objective-C

    Boolean SCPreferencesApplyChanges ( SCPreferencesRef prefs );

    Parameters

    prefs

    The preferences session.

    Return Value

    TRUE if the lock was obtained; FALSE if an error occurred.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

  • Commits changes made to the configuration preferences to persistent storage.

    Declaration

    Swift

    func SCPreferencesCommitChanges(_ prefs: SCPreferences!) -> Boolean

    Objective-C

    Boolean SCPreferencesCommitChanges ( SCPreferencesRef prefs );

    Parameters

    prefs

    The preferences session.

    Return Value

    TRUE if the lock was obtained; FALSE if an error occurred.

    Discussion

    Implicit calls to the SCPreferencesLock and SCPreferencesUnlock functions are made if exclusive access has not already been established.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

  • Synchronizes accessed preferences with committed changes.

    Declaration

    Swift

    func SCPreferencesSynchronize(_ prefs: SCPreferences!)

    Objective-C

    void SCPreferencesSynchronize ( SCPreferencesRef prefs );

    Parameters

    prefs

    The preferences session.

    Discussion

    Any references to preference values returned by calls to SCPreferencesGetValue are no longer valid unless they were explicitly retained or copied. Any preference values that were updated (added, set, or removed), but not committed, are discarded.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.4 and later.

  • Assigns the specified callback to the specified preferences session.

    Declaration

    Swift

    func SCPreferencesSetCallback(_ prefs: SCPreferences!, _ callout: SCPreferencesCallBack, _ Term: UnsafeMutablePointer<SCPreferencesContext>) -> Boolean

    Objective-C

    Boolean SCPreferencesSetCallback ( SCPreferencesRef prefs, SCPreferencesCallBack callout, SCPreferencesContext *context );

    Parameters

    prefs

    The preferences session.

    callout

    The function to be called when the preferences have been changed or applied. If NULL, the current callback is removed.

    Term

    The context associated with the callback function. See SCPreferencesContext for more information about this structure.

    Return Value

    TRUE if the callback was successfully associated with the preferences session; otherwise, FALSE.

    Discussion

    This function is called when the changes to the preferences have been committed or applied.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.4 and later.

  • Schedules commit and apply notifications for the specified preferences session using the specified run loop and mode.

    Declaration

    Swift

    func SCPreferencesScheduleWithRunLoop(_ prefs: SCPreferences!, _ runLoop: CFRunLoop!, _ runLoopMode: CFString!) -> Boolean

    Objective-C

    Boolean SCPreferencesScheduleWithRunLoop ( SCPreferencesRef prefs, CFRunLoopRef runLoop, CFStringRef runLoopMode );

    Parameters

    prefs

    The preferences session.

    runLoop

    The run loop on which the notification should be scheduled. Do not pass NULL.

    runLoopMode

    The run loop mode with which to schedule the notification. Do not pass NULL.

    Return Value

    TRUE if the notifications are successfully scheduled; otherwise, FALSE.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.4 and later.

  • Unschedules commit and apply notifications for the specified preferences session from the specified run loop and mode.

    Declaration

    Swift

    func SCPreferencesUnscheduleFromRunLoop(_ prefs: SCPreferences!, _ runLoop: CFRunLoop!, _ runLoopMode: CFString!) -> Boolean

    Objective-C

    Boolean SCPreferencesUnscheduleFromRunLoop ( SCPreferencesRef prefs, CFRunLoopRef runLoop, CFStringRef runLoopMode );

    Parameters

    prefs

    The preferences session.

    runLoop

    The run loop from which the notification should be unscheduled. Do not pass NULL.

    runLoopMode

    The run loop mode associated with the scheduled notification. Do not pass NULL.

    Return Value

    TRUE if the notifications are successfully unscheduled; otherwise, FALSE.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.4 and later.

  • Schedules commit and apply notifications for the specified preferences session using the specified dispatch queue.

    Declaration

    Swift

    func SCPreferencesSetDispatchQueue(_ prefs: SCPreferences!, _ queue: dispatch_queue_t!) -> Boolean

    Objective-C

    Boolean SCPreferencesSetDispatchQueue ( SCPreferencesRef prefs, dispatch_queue_t queue );

    Parameters

    prefs

    The preferences session.

    queue

    The dispatch queue on which to run the callback function.

    Return Value

    TRUE if the notifications are successfully scheduled; otherwise, FALSE.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.6 and later.

  • Locks access to the configuration preferences.

    Declaration

    Swift

    func SCPreferencesLock(_ prefs: SCPreferences!, _ wait: Boolean) -> Boolean

    Objective-C

    Boolean SCPreferencesLock ( SCPreferencesRef prefs, Boolean wait );

    Parameters

    prefs

    The preferences session.

    wait

    A Boolean value indicating whether the calling process should block, waiting for another process to complete its update operation and release its lock.

    Return Value

    TRUE if the lock was obtained; FALSE if an error occurred.

    Discussion

    This function obtains exclusive access to the configuration preferences. Clients attempting to obtain exclusive access to the preferences either receive a kSCStatusPrefsBusy error or they block, waiting for the lock to be released.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

  • Releases exclusive access to the configuration preferences.

    Declaration

    Swift

    func SCPreferencesUnlock(_ prefs: SCPreferences!) -> Boolean

    Objective-C

    Boolean SCPreferencesUnlock ( SCPreferencesRef prefs );

    Parameters

    prefs

    The preferences session.

    Return Value

    TRUE if the lock was obtained; FALSE if an error occurred.

    Discussion

    After exclusive access has been released, other clients can establish exclusive access to the preferences.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

Data Types

  • The handle to an open preferences session for accessing system configuration preferences.

    Declaration

    Swift

    typealias SCPreferencesRef = SCPreferences

    Objective-C

    typedef const struct __SCPreferences * SCPreferencesRef;

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

  • A structure containing user-specified data and callbacks for accessing system configuration preferences.

    Declaration

    Swift

    struct SCPreferencesContext { var version: CFIndex var info: UnsafeMutablePointer<Void> var retain: CFunctionPointer<((UnsafePointer<Void>) -> UnsafePointer<Void>)> var release: CFunctionPointer<((UnsafePointer<Void>) -> Void)> var copyDescription: CFunctionPointer<((UnsafePointer<Void>) -> Unmanaged<CFString>!)> }

    Objective-C

    typedef struct { CFIndex version; void * info; const void *(*retain)(const void *info); void (*release)(const void *info); CFStringRef (*copyDescription)(const void *info); } SCPreferencesContext;

    Fields

    version

    The version number of the structure type being passed in as a parameter to SCPreferencesSetCallback. This structure is version 0.

    info

    A C pointer to a user-specified block of data.

    retain

    The callback used to add a retain for the info field. If this parameter is not a pointer to a function of the correct prototype, the behavior is undefined. The value may be NULL.

    release

    The calllback used to remove a retain previously added for the info field. If this parameter is not a pointer to a function of the correct prototype, the behavior is undefined. The value may be NULL.

    copyDescription

    The callback used to provide a description of the info field.

    Availability

    Available in OS X v10.4 and later.

  • Type of the callback function used when the preferences have been updated or applied.

    Declaration

    Swift

    typealias SCPreferencesCallBack = CFunctionPointer<((SCPreferences!, SCPreferencesNotification, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

    typedef void (*SCPreferencesCallBack) ( SCPreferencesRef prefs, SCPreferencesNotification notificationType, void *info );

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.4 and later.

Constants

  • The type of notification (used with the SCPreferencesCallBack callback).

    Declaration

    Swift

    typealias SCPreferencesNotification = UInt32

    Objective-C

    enum { kSCPreferencesNotificationCommit = 1<<0, kSCPreferencesNotificationApply = 1<<1 }; typedef uint32_t SCPreferencesNotification;

    Constants

    • kSCPreferencesNotificationCommit

      kSCPreferencesNotificationCommit

      Indicates when new preferences have been saved.

      Available in OS X v10.4 and later.

    • kSCPreferencesNotificationApply

      kSCPreferencesNotificationApply

      Indicates when a request has been made to apply the currently saved preferences to the active system configuration.

      Available in OS X v10.4 and later.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.4 and later.