SCPreferences

Overview

The SCPreferences API 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 CFRelease to close it.

Functions

SCPreferencesAddValue

SCPreferencesApplyChanges

SCPreferencesCommitChanges

SCPreferencesCopyKeyList

SCPreferencesCreate

SCPreferencesCreateWithAuthorization

SCPreferencesGetSignature

SCPreferencesGetTypeID

SCPreferencesGetValue

SCPreferencesLock

SCPreferencesRemoveValue

SCPreferencesScheduleWithRunLoop

SCPreferencesSetCallback

SCPreferencesSetValue

SCPreferencesSynchronize

SCPreferencesUnlock

SCPreferencesUnscheduleFromRunLoop

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

Parameters

prefs

The preferences session.

key

The preference key to be updated.

value

The CFPropertyListRef object containing the value to be associated with the specified preference key.

Return Value

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

Discussion

Adds data for a preference key.

This function associates new data with the specified key. To commit these changes to permanent storage, a call must be made to the SCPreferencesCommitChanges function.

Boolean SCPreferencesApplyChanges ( 
    SCPreferencesRef prefs );  

Parameters

prefs

The preferences session.

Return Value

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

Discussion

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

Boolean SCPreferencesCommitChanges ( 
    SCPreferencesRef prefs );  

Parameters

prefs

The preferences session.

Return Value

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

Discussion

Commits changes made to the configuration preferences to persistent storage.

This function commits any changes to permanent storage. Implicit calls to the SCPreferencesLock and SCPreferencesUnlock functions will be made if exclusive access has not already been established.

Note: This routine commits changes to persistent storage. Call the SCPreferencesApplyChanges function to apply the changes to the running system.

CFArrayRef SCPreferencesCopyKeyList ( 
    SCPreferencesRef prefs );  

Parameters

prefs

The preferences session.

Return Value

Returns the list of keys. You must release the returned value.

Discussion

Returns an array of currently defined preference keys.

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

Parameters

allocator

The CFAllocator that should be used to allocate memory for this preferences session. This parameter may be NULL in which case the current default CFAllocator is used. If this reference is not a valid CFAllocator, the behavior is undefined.

name

A string that describes the name of the calling process.

prefsID

A string that identifies the name of the group of preferences to be accessed or updated.

Return Value

Returns a reference to the new SCPreferences. You must release the returned value.

Discussion

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

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

Parameters

allocator

The CFAllocator that should be used to allocate memory for this preferences session. This parameter may be NULL in which case the current default CFAllocator is used. If this reference is not a valid CFAllocator, the behavior is undefined.

name

A string that describes the name of the calling process.

prefsID

A string that identifies the name of the group of preferences to be accessed or updated.

authorization

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

Return Value

Returns a reference to the new SCPreferences. You must release the returned value.

Discussion

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

Availability

Introduced in Mac OS X v10.5.

CFDataRef SCPreferencesGetSignature ( 
    SCPreferencesRef prefs );  

Parameters

prefs

The preferences session.

Return Value

Returns a CFDataRef that reflects the signature of the configuration preferences at the time of the call to the SCPreferencesCreate function.

Discussion

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

CFTypeID SCPreferencesGetTypeID (
    void);  

Discussion

Returns the type identifier of all SCPreferences instances.

CFPropertyListRef SCPreferencesGetValue ( 
    SCPreferencesRef prefs, 
    CFStringRef key );  

Parameters

prefs

The preferences session.

key

The preference key to be returned.

Return Value

Returns the value associated with the specified preference key; NULL if no value was located.

Discussion

Returns the data associated with a preference key.

This function retrieves data associated with the specified key.

Note: To avoid inadvertantly reading stale data, first call the SCPreferencesLock function.

Boolean SCPreferencesLock ( 
    SCPreferencesRef prefs, 
    Boolean wait );  

Parameters

prefs

The preferences session.

wait

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

Return Value

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

Discussion

Locks access to the configuration preferences.

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

Boolean SCPreferencesRemoveValue ( 
    SCPreferencesRef prefs, 
    CFStringRef key );  

Parameters

prefs

The preferences session.

key

The preference key to be removed.

Return Value

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

Discussion

Removes the data associated with a preference key.

This function removes the data associated with the specified key. To commit these changes to permanent storage a call must be made to the SCPreferencesCommitChanges function.

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

Parameters

prefs

The preferences session.

runLoop

A reference to a run loop on which the notification should be scheduled. Must be non-NULL.

runLoopMode

The mode on which to schedule the notification. Must be non-NULL.

Return Value

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

Discussion

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

Availability

Introduced in Mac OS X v10.4.

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.

context

The SCPreferencesContext associated with the callout.

Return Value

Returns TRUE if the notification client was successfully set.

Discussion

Assigns a callback to a preferences session. The function is called when the changes to the preferences have been committed or applied.

Availability

Introduced in Mac OS X v10.4.

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

Parameters

prefs

The preferences session.

key

The preference key to be updated.

value

The CFPropertyListRef object containing the data to be associated with the specified preference key.

Return Value

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

Discussion

Updates the data associated with a preference key.

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

void SCPreferencesSynchronize ( 
    SCPreferencesRef prefs );  

Parameters

prefs

The preferences session.

Discussion

Synchronizes accessed preferences with committed changes.

Any references to preference values returned by calls to the SCPreferencesGetValue function are no longer valid unless they were explicitly retained or copied. Any preference values that were updated (add, set, remove) but not committed will be discarded.

Availability

Introduced in Mac OS X v10.4.

Boolean SCPreferencesUnlock ( 
    SCPreferencesRef prefs );  

Parameters

prefs

The preferences session.

Return Value

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

Discussion

Releases exclusive access to the configuration preferences.

This function releases the exclusive access lock to the preferences. Other clients will be now be able to establish exclusive access to the preferences.

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

Parameters

prefs

The preferences session.

runLoop

A reference to a run loop from which the notification should be unscheduled. Must be non-NULL.

runLoopMode

The mode on which to unschedule the notification. Must be non-NULL.

Return Value

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

Discussion

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

Availability

Introduced in Mac OS X v10.4.

Typedefs

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

Parameters

prefs

The preferences session.

notificationType

The type of notification, such as changes committed, changes applied, etc.

info

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

Discussion

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

Availability

Introduced in Mac OS X v10.4.

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 the SCPreferencesSetCallback function. 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.

Discussion

Structure containing user-specified data and callbacks for SCPreferences.

Availability

Introduced in Mac OS X v10.4.

typedef const struct __SCPreferences * SCPreferencesRef;  

Discussion

This is the handle to an open preferences session for accessing system configuration preferences.

Enumerations

enum { 
    kSCPreferencesNotificationCommit = 1<<0, 
    kSCPreferencesNotificationApply = 1<<1 
};  

Constants

kSCPreferencesNotificationCommit

Indicates when new preferences have been saved.

kSCPreferencesNotificationApply

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

Discussion

Used with the SCPreferencesCallBack callback to describe the type of notification.

Availability

Introduced in Mac OS X v10.4.

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-03-11