SCDynamicStore Reference

Framework
Declared in
SCDynamicStore.h

Overview

The SCDynamicStore programming interface 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 programming interface 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. A function that has "Create" or "Copy" in its name returns a reference you must release with the CFRelease function.

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

Functions by Task

Creating a Dynamic Store Session

Adding or Updating Keys and Values

Getting Keys and Values

Monitoring Keys and Values

Removing Keys and Values

Creating a Run Loop Source

Getting Information About the Dynamic Store

Functions

SCDynamicStoreAddTemporaryValue

Temporarily adds the specified key-value pair to the dynamic store, if no such key already exists.

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

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

Discussion

Unless the key is updated by another session, the key-value pair added by this function is removed automatically when the session is closed.

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

SCDynamicStoreAddValue

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

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

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

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

SCDynamicStoreCopyKeyList

Returns the keys that represent the current dynamic store entries that match the specified pattern.

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

An array of matching keys, or NULL if an error occurred. You must release the returned value.

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

SCDynamicStoreCopyMultiple

Returns the key-value pairs that match the specified keys and key patterns.

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

The dynamic store session.

keys

The keys associated with the desired values or NULL if no specific keys are requested.

patterns

An array of regex(3) pattern strings used to match the keys, or NULL if no key patterns are requested.

Return Value

A dictionary of key-value pairs that match the specified keys and key patterns, or NULL if an error occurred. You must release the returned value.

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

SCDynamicStoreCopyNotifiedKeys

Returns the keys that have changed since the last call to this function.

CFArrayRef SCDynamicStoreCopyNotifiedKeys (
   SCDynamicStoreRef store
);
Parameters
store

The dynamic store session.

Return Value

The keys that have changed, or NULL if an error occurred. You must release the returned value.

Discussion

If possible, your application should use the notification functions instead of polling for the list of changed keys returned by this function.

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

SCDynamicStoreCopyValue

Returns the value associated with the specified key.

CFPropertyListRef SCDynamicStoreCopyValue (
   SCDynamicStoreRef store,
   CFStringRef key
);
Parameters
store

The dynamic store session.

key

The key associated with the desired value.

Return Value

The value associated with the specified key, or NULL if no value was located or if an error occurred. You must release the returned value.

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

SCDynamicStoreCreate

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

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

The allocator that should be used to allocate memory for the local dynamic store object. This parameter may be NULL in which case the current default allocator is used. If this value is not a valid CFAllocatorRef, the behavior is undefined.

name

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. Pass NULL if no callouts are desired.

context

The context associated with the callout. See SCDynamicStoreContext for more information about this value.

Return Value

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

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

SCDynamicStoreCreateRunLoopSource

Creates a run loop source object that can be added to the application's run loop.

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

The allocator that should be used to allocate memory for the run loop source. This parameter may be NULL in which case the current default allocator is used. If this value is not a valid CFAllocatorRef, the behavior is undefined.

store

The dynamic store session.

order

The order in which the sources that are ready to be processed are handled, on platforms that support it and for source versions that support it. A source with a lower order number is processed before a source with a higher order number. 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, pass 0 for this parameter.

Return Value

The new run loop source object. You must release the returned value.

Discussion

Note that all dynamic store notifications are delivered using the run loop source this function returns.

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

SCDynamicStoreCreateWithOptions

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

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

The allocator that should be used to allocate memory for the local dynamic store object. This parameter may be NULL in which case the current default allocator is used. If this value is not a valid CFAllocatorRef, the behavior is undefined.

name

The name of the calling process or plug-in of the caller.

storeOptions

A dictionary of options for the dynamic store session (such as whether all keys added or set into the dynamic store should be per-session keys). Pass NULL if no options are desired.

Currently, the available options are:

Key

Value

kSCDynamicStoreUseSessionKeys

CFBooleanRef

callout

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

context

The context associated with the callout. See SCDynamicStoreContext for more information about this value.

Return Value

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

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

SCDynamicStoreGetTypeID

Returns the type identifier of all SCDynamicStore instances.

CFTypeID SCDynamicStoreGetTypeID (
   void
);
Return Value

The type identifier of all SCDynamicStore instances.

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

SCDynamicStoreNotifyValue

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

Boolean SCDynamicStoreNotifyValue (
   SCDynamicStoreRef store,
   CFStringRef key
);
Parameters
store

The dynamic store session.

key

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

Return Value

TRUE if the notification was processed; FALSE if an error occurred.

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

SCDynamicStoreRemoveValue

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

Boolean SCDynamicStoreRemoveValue (
   SCDynamicStoreRef store,
   CFStringRef key
);
Parameters
store

The dynamic store session.

key

The key of the value to remove.

Return Value

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

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

SCDynamicStoreSetDispatchQueue

Initiates notifications for the notification keys, using the specified dispatch queue for the callback.

Boolean SCDynamicStoreSetDispatchQueue (
   SCDynamicStoreRef store,
   dispatch_queue_t queue
);
Parameters
store

The dynamic store session.

queue

The dispatch queue on which to run the callback function. Pass NULL to disable notifications and release the queue.

Return Value

TRUE if notifications were successfully initiated; otherwise, FALSE.

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

SCDynamicStoreSetMultiple

Updates multiple values in the dynamic store.

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

The dynamic store session.

keysToSet

A dictionary of key-value pairs to add to the dynamic store.

keysToRemove

An array of keys to remove from the dynamic store.

keysToNotify

An array of keys to flag as changed (without changing their values).

Return Value

TRUE if the dynamic store updates were successful; otherwise, FALSE.

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

SCDynamicStoreSetNotificationKeys

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

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

The dynamic store session being watched.

keys

An array of keys to be monitored or NULL if no specific keys are to be monitored.

patterns

An array of regex(3) pattern strings used to match keys to be monitored or NULL if no key patterns are to be monitored.

Return Value

TRUE if the set of notification keys and patterns was successfully updated; otherwise, FALSE.

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

SCDynamicStoreSetValue

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

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

The dynamic store session.

key

The key associated with the value.

value

The value to add to or replace in the dynamic store.

Return Value

TRUE if the key was updated; otherwise, FALSE.

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

Data Types

SCDynamicStoreCallBack

Callback used when notification of changes made to the dynamic store is delivered.

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

The dynamic store session.

changedKeys

The list of changed keys.

info

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

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

SCDynamicStoreContext

Structure containing user-specified data and callbacks for a dynamic store session.

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 (such as SCDynamicStoreCreate). 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 of this parameter can be NULL.

release

The callback 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 of this parameter can be NULL.

copyDescription

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

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

SCDynamicStoreRef

The handle to an open dynamic store session with the system configuration daemon.

typedef const struct __SCDynamicStore *    SCDynamicStoreRef;
Availability
  • Available in OS X v10.1 and later.
Declared In
SCDynamicStore.h

Constants

Dynamic Store Options Keys

Keys that indicate the options for a dynamic store session.

const CFStringRef kSCDynamicStoreUseSessionKeys;
Constants
kSCDynamicStoreUseSessionKeys

All keys added or set into the dynamic store should be per-session keys.

Available in OS X v10.4 and later.

Declared in SCDynamicStore.h.