Mac Developer Library

Developer

System Configuration 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

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

    Declaration

    Swift

    func SCDynamicStoreCopyKeyList(_ store: SCDynamicStore?, _ pattern: CFString) -> 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.

    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?) -> 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.

    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) -> 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.

    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) -> 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.

    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) -> Bool

    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.

    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?) -> Bool

    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.

    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?) -> Bool

    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.

    Availability

    Available in OS X v10.6 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) -> 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.

    Availability

    Available in OS X v10.1 and later.

Data Types

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.