ADC Home > Reference Library > Reference > Networking > System Configuration Framework Reference

SCDynamicStore.h

Include Path:	<SystemConfiguration/SCDynamicStore.h>
Path:	/System/Library/Frameworks/SystemConfiguration.framework/Versions/A/Headers/SCDynamicStore.h
Includes:	<AvailabilityMacros.h> <sys/cdefs.h> <CoreFoundation/CoreFoundation.h>

Overview

The SCDynamicStore API provides access to the key-value pairs in the dynamic store of a running system. The dynamic store contains, among other items, a copy of the configuration settings for the currently active set (which is sometimes refered to as the location) and information about the current network state.

The functions in the SCDynamicStore API allow you to find key-value pairs, add or remove key-value pairs, add or change values, and request notifications. Note that these functions follow Core Foundation function-name conventions in that a function that has "Create" or "Copy" in its name returns a reference you must release with CFRelease.

To use the functions of the SCDynamicStore API, you must first establish a dynamic store session using the SCDynamicStoreCreate function. When you are finished with the session, use CFRelease to close it.

For more information on using System Configuration framework APIs, see System Configuration Programming Guidelines.

Functions

SCDynamicStoreAddTemporaryValue
SCDynamicStoreAddValue
SCDynamicStoreCopyKeyList
SCDynamicStoreCopyMultiple
SCDynamicStoreCopyNotifiedKeys
SCDynamicStoreCopyValue
SCDynamicStoreCreate
SCDynamicStoreCreateRunLoopSource
SCDynamicStoreCreateWithOptions
SCDynamicStoreGetTypeID
SCDynamicStoreNotifyValue
SCDynamicStoreRemoveValue
SCDynamicStoreSetMultiple
SCDynamicStoreSetNotificationKeys
SCDynamicStoreSetValue

SCDynamicStoreAddTemporaryValue

Boolean SCDynamicStoreAddTemporaryValue ( 
    SCDynamicStoreRef store, 
    CFStringRef key, 
    CFPropertyListRef value );

Parameters

store: The dynamic store session.
key: The key of the value to add to the dynamic store.
value: The value to add to the dynamic store.

Return Value

Returns TRUE if the key was added; FALSE if the key was already present in the dynamic store or if an error was encountered.

Discussion

Temporarily adds the key-value pair to the dynamic store if no such key already exists. Unless the key is updated by another session, the key-value pair will be removed automatically when the session is closed.

SCDynamicStoreAddValue

Boolean SCDynamicStoreAddValue ( 
    SCDynamicStoreRef store, 
    CFStringRef key, 
    CFPropertyListRef value );

Parameters

store: The dynamic store session.
key: The key of the value to add to the dynamic store.
value: The value to add to the dynamic store.

Return Value

Returns TRUE if the key was added; FALSE if the key was already present in the dynamic store or if an error was encountered.

Discussion

Adds the key-value pair to the dynamic store if no such key already exists.

SCDynamicStoreCopyKeyList

CFArrayRef SCDynamicStoreCopyKeyList ( 
    SCDynamicStoreRef store, 
    CFStringRef pattern );

Parameters

store: The dynamic store session.
pattern: A regex(3) regular expression pattern used to match the dynamic store keys.

Return Value

Returns the list of matching keys; NULL if an error was encountered. You must release the returned value.

Discussion

Returns an array of CFString keys representing the current dynamic store entries that match a specified pattern.

SCDynamicStoreCopyMultiple

CFDictionaryRef SCDynamicStoreCopyMultiple ( 
    SCDynamicStoreRef store, 
    CFArrayRef keys, 
    CFArrayRef patterns );

Parameters

store: The dynamic store session.
keys: The keys associated with the values you want to get; NULL if no specific keys are requested.
patterns: An array of regex(3) pattern strings used to match the keys; NULL if no key patterns are requested.

Return Value

Returns a dictionary containing the key-value pairs of specific keys and the key-value pairs of keys that matched the specified patterns; NULL if an error was encountered. You must release the returned value.

Discussion

Gets the values of multiple keys in the dynamic store.

SCDynamicStoreCopyNotifiedKeys

CFArrayRef SCDynamicStoreCopyNotifiedKeys ( 
    SCDynamicStoreRef store );

Parameters

store: The dynamic store session.

Return Value

Returns the list of changed keys; NULL if an error was encountered. You must release the returned value.

Discussion

Returns an array of CFString keys representing the dynamic store entries that have changed since this function was last called. If possible, your application should use the notification functions instead of polling for the list of changed keys returned by this function.

SCDynamicStoreCopyValue

CFPropertyListRef SCDynamicStoreCopyValue ( 
    SCDynamicStoreRef store, 
    CFStringRef key );

Parameters

store: The dynamic store session.
key: The key associated with the value you want to get.

Return Value

Returns the value from the dynamic store that is associated with the given key; NULL if no value was located or an error was encountered. You must release the returned value.

Discussion

Gets the value of the specified key from the dynamic store.

SCDynamicStoreCreate

SCDynamicStoreRef SCDynamicStoreCreate ( 
    CFAllocatorRef allocator, 
    CFStringRef name, 
    SCDynamicStoreCallBack callout, 
    SCDynamicStoreContext *context );

Parameters

allocator: The CFAllocator that should be used to allocate memory for the local dynamic store object. 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 or plug-in of the caller.
callout: The function to be called when a watched value in the dynamic store is changed. A NULL value can be specified if no callouts are desired.
context: The SCDynamicStoreContext associated with the callout.

Return Value

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

Discussion

Creates a new session used to interact with the dynamic store maintained by the System Configuration server.

SCDynamicStoreCreateRunLoopSource

CFRunLoopSourceRef SCDynamicStoreCreateRunLoopSource ( 
    CFAllocatorRef allocator, 
    SCDynamicStoreRef store, 
    CFIndex order );

Parameters

allocator: The CFAllocator that should be used to allocate memory for this run loop source. 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.
store: A reference to the dynamic store session.
order: On platforms which support it, for source versions which support it, this parameter determines the order in which the sources which are ready to be processed are handled. A lower order number causes processing before higher order number sources. It is inadvisable to depend on the order number for any architectural or design aspect of code. In the absence of any reason to do otherwise, zero should be used.

Return Value

A reference to the new CFRunLoopSource. You must release the returned value.

Discussion

Creates a CFRunLoopSource object that can be added to the application's run loop. All dynamic store notifications are delivered using this run loop source.

SCDynamicStoreCreateWithOptions

SCDynamicStoreRef SCDynamicStoreCreateWithOptions ( 
    CFAllocatorRef allocator, 
    CFStringRef name, 
    CFDictionaryRef storeOptions, 
    SCDynamicStoreCallBack callout, 
    SCDynamicStoreContext *context );

Parameters

allocator

The CFAllocator that should be used to allocate memory for the local dynamic store object. 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 or plug-in of the caller.

storeOptions

A CFDictionary containing options for the dynamic store session (such as whether all keys added or set into the dynamic store should be per-session keys).

Currently available options include:

key	value
kSCDynamicStoreUseSessionKeys	CFBooleanRef

A NULL value can be specified if no options are desired.

callout

The function to be called when a watched value in the dynamic store is changed. A NULL value can be specified if no callouts are desired.

context

The SCDynamicStoreContext associated with the callout.

Return Value

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

Discussion

Creates a new session used to interact with the dynamic store maintained by the System Configuration server.

Availability: Introduced in Mac OS X v10.4.

SCDynamicStoreGetTypeID

CFTypeID SCDynamicStoreGetTypeID (
    void);

Discussion

Returns the type identifier of all SCDynamicStore instances.

SCDynamicStoreNotifyValue

Boolean SCDynamicStoreNotifyValue ( 
    SCDynamicStoreRef store, 
    CFStringRef key );

Parameters

store: The dynamic store session.
key: The key that should be flagged as changed. Any dynamic store sessions that are monitoring this key will received a notification. Note that the key's value is not updated.

Return Value

Returns TRUE if the notification was processed; FALSE if an error was encountered.

Discussion

Triggers a notification to be delivered for the specified key in the dynamic store.

SCDynamicStoreRemoveValue

Boolean SCDynamicStoreRemoveValue ( 
    SCDynamicStoreRef store, 
    CFStringRef key );

Parameters

store: The dynamic store session.
key: The key of the value you want to remove.

Return Value

Returns TRUE if the key was removed; FALSE if no value was located or an error was encountered.

Discussion

Removes the value of the specified key from the dynamic store.

SCDynamicStoreSetMultiple

Boolean SCDynamicStoreSetMultiple ( 
    SCDynamicStoreRef store, 
    CFDictionaryRef keysToSet, 
    CFArrayRef keysToRemove, 
    CFArrayRef keysToNotify );

Parameters

store: The dynamic store session.
keysToSet: A dictionary of key-value pairs you want to set into the dynamic store.
keysToRemove: An array of keys you want to remove from the dynamic store.
keysToNotify: An array of keys to flag as changed (without changing their values).

Return Value

Returns TRUE if the dynamic store updates were successful; FALSE if an error was encountered.

Discussion

Updates multiple values in the dynamic store.

SCDynamicStoreSetNotificationKeys

Boolean SCDynamicStoreSetNotificationKeys ( 
    SCDynamicStoreRef store, 
    CFArrayRef keys, 
    CFArrayRef patterns );

Parameters

store: The dynamic store session being watched.
keys: An array of keys to be monitored; NULL if no specific keys are to be monitored.
patterns: An array of regex(3) pattern strings used to match keys to be monitored; NULL if no key patterns are to be monitored.

Return Value

Returns TRUE if the set of notification keys and patterns was successfully updated; FALSE if an error was encountered.

Discussion

Specifies a set of specific keys and key patterns that should be monitored for changes.

SCDynamicStoreSetValue

Boolean SCDynamicStoreSetValue ( 
    SCDynamicStoreRef store, 
    CFStringRef key, 
    CFPropertyListRef value );

Parameters

store: The dynamic store session.
key: The key you want to set.
value: The value to add to or replace in the dynamic store.

Return Value

Returns TRUE if the key was updated; FALSE if an error was encountered.

Discussion

Adds or replaces a value in the dynamic store for the specified key.

Typedefs

SCDynamicStoreCallBack

typedef void ( *SCDynamicStoreCallBack) ( 
    SCDynamicStoreRef store, 
    CFArrayRef changedKeys, 
    void *info );

Parameters

store
The dynamic store session.

changedKeys
The list of changed keys.

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

Discussion

Type of callback function used when notification of changes to the dynamic store is delivered.

SCDynamicStoreContext

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

Fields

version
The version number of the structure type being passed in as a parameter to the SCDynamicStore creation 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 an SCDynamicStore session.

SCDynamicStoreRef

typedef const struct __SCDynamicStore * SCDynamicStoreRef;

Discussion

This is the handle to an open a dynamic store session with the system configuration daemon.

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