Mac Developer Library

Developer

SystemConfiguration Framework Reference SCDynamicStore Reference

Options
Deployment Target:

On This Page
Language:

SCDynamicStore Reference

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

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

    Declaration

    Swift

    func SCDynamicStoreCreateWithOptions(_ allocator: CFAllocator!, _ name: CFString!, _ storeOptions: CFDictionary!, _ callout: SCDynamicStoreCallBack, _ context: UnsafeMutablePointer<SCDynamicStoreContext>) -> Unmanaged<SCDynamicStore>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func SCDynamicStoreCreate(_ allocator: CFAllocator!, _ name: CFString!, _ callout: SCDynamicStoreCallBack, _ context: UnsafeMutablePointer<SCDynamicStoreContext>) -> Unmanaged<SCDynamicStore>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    func SCDynamicStoreAddTemporaryValue(_ store: SCDynamicStore!, _ key: CFString!, _ value: CFPropertyList!) -> Boolean

    Objective-C

    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.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    func SCDynamicStoreAddValue(_ store: SCDynamicStore!, _ key: CFString!, _ value: CFPropertyList!) -> Boolean

    Objective-C

    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.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

  • Updates multiple values in the dynamic store.

    Declaration

    Swift

    func SCDynamicStoreSetMultiple(_ store: SCDynamicStore!, _ keysToSet: CFDictionary!, _ keysToRemove: CFArray!, _ keysToNotify: CFArray!) -> Boolean

    Objective-C

    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.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    func SCDynamicStoreSetValue(_ store: SCDynamicStore!, _ key: CFString!, _ value: CFPropertyList!) -> Boolean

    Objective-C

    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.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    func SCDynamicStoreCopyKeyList(_ store: SCDynamicStore!, _ pattern: CFString!) -> Unmanaged<CFArray>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    func SCDynamicStoreCopyMultiple(_ store: SCDynamicStore!, _ keys: CFArray!, _ patterns: CFArray!) -> Unmanaged<CFDictionary>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    func SCDynamicStoreCopyNotifiedKeys(_ store: SCDynamicStore!) -> Unmanaged<CFArray>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

  • Returns the value associated with the specified key.

    Declaration

    Swift

    func SCDynamicStoreCopyValue(_ store: SCDynamicStore!, _ key: CFString!) -> Unmanaged<CFPropertyList>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    func SCDynamicStoreNotifyValue(_ store: SCDynamicStore!, _ key: CFString!) -> Boolean

    Objective-C

    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.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    func SCDynamicStoreSetNotificationKeys(_ store: SCDynamicStore!, _ keys: CFArray!, _ patterns: CFArray!) -> Boolean

    Objective-C

    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.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    func SCDynamicStoreSetDispatchQueue(_ store: SCDynamicStore!, _ queue: dispatch_queue_t!) -> Boolean

    Objective-C

    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.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    func SCDynamicStoreRemoveValue(_ store: SCDynamicStore!, _ key: CFString!) -> Boolean

    Objective-C

    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.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    func SCDynamicStoreCreateRunLoopSource(_ allocator: CFAllocator!, _ store: SCDynamicStore!, _ order: CFIndex) -> Unmanaged<CFRunLoopSource>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

  • Returns the type identifier of all SCDynamicStore instances.

    Declaration

    Swift

    func SCDynamicStoreGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID SCDynamicStoreGetTypeID ( void );

    Return Value

    The type identifier of all SCDynamicStore instances.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

Data Types

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

    Declaration

    Swift

    typealias SCDynamicStoreCallBack = CFunctionPointer<((SCDynamicStore!, CFArray!, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

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

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    struct SCDynamicStoreContext { var version: CFIndex var info: UnsafeMutablePointer<Void> var retain: CFunctionPointer<((UnsafePointer<Void>) -> UnsafePointer<Void>)> var release: CFunctionPointer<((UnsafePointer<Void>) -> Void)> var copyDescription: CFunctionPointer<((UnsafePointer<Void>) -> Unmanaged<CFString>!)> }

    Objective-C

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

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    typealias SCDynamicStoreRef = SCDynamicStore

    Objective-C

    typedef const struct __SCDynamicStore * SCDynamicStoreRef;

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.

Constants

  • Keys that indicate the options for a dynamic store session.

    Declaration

    Swift

    let kSCDynamicStoreUseSessionKeys: CFString!

    Objective-C

    const CFStringRef kSCDynamicStoreUseSessionKeys;

    Constants

    • kSCDynamicStoreUseSessionKeys

      kSCDynamicStoreUseSessionKeys

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

      Available in OS X v10.4 and later.