SCPreferences

Overview

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.

Topics

Creating a Preferences Session

func SCPreferencesCreate(CFAllocator?, CFString, CFString?) -> SCPreferences?

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

func SCPreferencesCreateWithAuthorization(CFAllocator?, CFString, CFString?, AuthorizationRef?) -> SCPreferences?

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

Getting Information About a Preferences Session

func SCPreferencesGetTypeID() -> CFTypeID

Returns the type identifier of all SCPreferences instances.

func SCPreferencesCopyKeyList(SCPreferences) -> CFArray?

Returns the currently defined preference keys.

func SCPreferencesGetSignature(SCPreferences) -> CFData?

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

Adding, Getting, and Removing Values

func SCPreferencesAddValue(SCPreferences, CFString, CFPropertyList) -> Bool

Associates the specified value with the specified preference key.

func SCPreferencesGetValue(SCPreferences, CFString) -> CFPropertyList?

Retrieves the value associated with the specified preference key.

func SCPreferencesSetValue(SCPreferences, CFString, CFPropertyList) -> Bool

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

func SCPreferencesRemoveValue(SCPreferences, CFString) -> Bool

Removes the data associated with the specified preference key.

Applying and Committing Changes

func SCPreferencesApplyChanges(SCPreferences) -> Bool

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

func SCPreferencesCommitChanges(SCPreferences) -> Bool

Commits changes made to the configuration preferences to persistent storage.

func SCPreferencesSynchronize(SCPreferences)

Synchronizes accessed preferences with committed changes.

Managing Notifications and Callbacks

func SCPreferencesScheduleWithRunLoop(SCPreferences, CFRunLoop, CFString) -> Bool

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

func SCPreferencesUnscheduleFromRunLoop(SCPreferences, CFRunLoop, CFString) -> Bool

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

func SCPreferencesSetDispatchQueue(SCPreferences, DispatchQueue?) -> Bool

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

Managing Access to a Preferences Session

func SCPreferencesLock(SCPreferences, Bool) -> Bool

Locks access to the configuration preferences.

func SCPreferencesUnlock(SCPreferences) -> Bool

Releases exclusive access to the configuration preferences.

Data Types

class SCPreferences

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

struct SCPreferencesContext

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

typealias SCPreferencesCallBack

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

Constants

struct SCPreferencesNotification

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