SCPreferences Reference

Framework
Declared in
SCPreferences.h

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.

Functions by Task

Creating a Preferences Session

Getting Information About a Preferences Session

Adding, Getting, and Removing Values

Applying and Committing Changes

Managing Notifications and Callbacks

Managing Access to a Preferences Session

Functions

SCPreferencesAddValue

Associates the specified value with the specified preference key.

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.

Availability
  • Available in OS X v10.1 and later.
Declared In
SCPreferences.h

SCPreferencesApplyChanges

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

Boolean SCPreferencesApplyChanges (
   SCPreferencesRef prefs
);
Parameters
prefs

The preferences session.

Return Value

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

Availability
  • Available in OS X v10.1 and later.
Declared In
SCPreferences.h

SCPreferencesCommitChanges

Commits changes made to the configuration preferences to persistent storage.

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.

Availability
  • Available in OS X v10.1 and later.
Declared In
SCPreferences.h

SCPreferencesCopyKeyList

Returns the currently defined preference keys.

CFArrayRef SCPreferencesCopyKeyList (
   SCPreferencesRef prefs
);
Parameters
prefs

The preferences session.

Return Value

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

Availability
  • Available in OS X v10.1 and later.
Declared In
SCPreferences.h

SCPreferencesCreate

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

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.

Availability
  • Available in OS X v10.1 and later.
Declared In
SCPreferences.h

SCPreferencesCreateWithAuthorization

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

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.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCPreferences.h

SCPreferencesGetSignature

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

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.

Availability
  • Available in OS X v10.1 and later.
Declared In
SCPreferences.h

SCPreferencesGetTypeID

Returns the type identifier of all SCPreferences instances.

CFTypeID SCPreferencesGetTypeID (
   void
);
Availability
  • Available in OS X v10.1 and later.
Declared In
SCPreferences.h

SCPreferencesGetValue

Retrieves the value associated with the specified preference key.

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.

Availability
  • Available in OS X v10.1 and later.
Declared In
SCPreferences.h

SCPreferencesLock

Locks access to the configuration preferences.

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.

Availability
  • Available in OS X v10.1 and later.
Declared In
SCPreferences.h

SCPreferencesRemoveValue

Removes the data associated with the specified preference key.

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.

Availability
  • Available in OS X v10.1 and later.
Declared In
SCPreferences.h

SCPreferencesScheduleWithRunLoop

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

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCPreferences.h

SCPreferencesSetCallback

Assigns the specified callback to the specified preferences session.

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCPreferences.h

SCPreferencesSetDispatchQueue

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

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
SCPreferences.h

SCPreferencesSetValue

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

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.

Availability
  • Available in OS X v10.1 and later.
Declared In
SCPreferences.h

SCPreferencesSynchronize

Synchronizes accessed preferences with committed changes.

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCPreferences.h

SCPreferencesUnlock

Releases exclusive access to the configuration preferences.

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.

Availability
  • Available in OS X v10.1 and later.
Declared In
SCPreferences.h

SCPreferencesUnscheduleFromRunLoop

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

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCPreferences.h

Data Types

SCPreferencesRef

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

typedef const struct __SCPreferences *    SCPreferencesRef;
Availability
  • Available in OS X v10.1 and later.
Declared In
SCPreferences.h

SCPreferencesContext

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

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.
Declared In
SCPreferences.h

SCPreferencesCallBack

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

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

The preferences session.

notificationType

The type of notification, such as changes committed or changes applied. See “Preferences Notification Values” for information about possible values.

info

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

Availability
  • Available in OS X v10.4 and later.
Declared In
SCPreferences.h

Constants

Preferences Notification Values

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

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

Indicates when new preferences have been saved.

Available in OS X v10.4 and later.

Declared in SCPreferences.h.

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.

Declared in SCPreferences.h.