/* * Copyright (c) 2000 Apple Computer, Inc. All rights reserved. * * @APPLE_LICENSE_HEADER_START@ * * The contents of this file constitute Original Code as defined in and * are subject to the Apple Public Source License Version 1.1 (the * "License"). You may not use this file except in compliance with the * License. Please obtain a copy of the License at * http://www.apple.com/publicsource and read it before using this file. * * This Original Code and all software distributed under the License are * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the * License for the specific language governing rights and limitations * under the License. * * @APPLE_LICENSE_HEADER_END@ */ #ifndef _SCDYNAMICSTORE_H #define _SCDYNAMICSTORE_H #include <sys/cdefs.h> #include <sys/syslog.h> #include <mach/message.h> #include <CoreFoundation/CoreFoundation.h> /*! @header SCDynamicStore The SystemConfiguration framework provides access to the data used to configure a running system. The APIs provided by this framework communicate with the "configd" daemon. The "configd" daemon manages a "dynamic store" reflecting the desired configuration settings as well as the current state of the system. The daemon provides a notification mechanism for user-level processes that need to be aware of changes made to the data. Lastly, the daemon loads a number of bundles (or plug-ins) that monitor low-level kernel events and, via a set of policy modules, keep the state data up to date. */ /*! @typedef SCDynamicStoreRef @discussion This is the handle to an open "dynamic store" session with the system configuration daemon. */ typedef const struct __SCDynamicStore * SCDynamicStoreRef; /*! @typedef SCDynamicStoreContext */ typedef struct { CFIndex version; void * info; const void *(*retain)(const void *info); void (*release)(const void *info); CFStringRef (*copyDescription)(const void *info); } SCDynamicStoreContext; /*! @typedef SCDynamicStoreCallBack @discussion Type of the callback function used when a dynamic store change is delivered. @param store The "dynamic store" session. @param changedKeys The list of changed keys. @param info .... */ typedef void (*SCDynamicStoreCallBack) ( SCDynamicStoreRef store, CFArrayRef changedKeys, void *info ); __BEGIN_DECLS /*! @function SCDynamicStoreGetTypeID Returns the type identifier of all SCDynamicStore instances. */ CFTypeID SCDynamicStoreGetTypeID (void); /*! @function SCDynamicStoreCreate @discussion Creates a new session used to interact with the dynamic store maintained by the SystemConfiguration server. @param allocator The CFAllocator which should be used to allocate memory for the local "dynamic store" and its storage for values. 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. @param name A string that describes the name of the calling process or plug-in of the caller. @param 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. @param context The SCDynamicStoreContext associated with the callout. @result A reference to the new SCDynamicStore. */ SCDynamicStoreRef SCDynamicStoreCreate ( CFAllocatorRef allocator, CFStringRef name, SCDynamicStoreCallBack callout, SCDynamicStoreContext *context ); /*! @function SCDynamicStoreCreateRunLoopSource @discussion Creates a new session used to interact with the dynamic store maintained by the SystemConfiguration server. @param allocator The CFAllocator which should be used to allocate memory for the local "dynamic store" and its storage for values. 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. @param store The "dynamic store" session. @param order On platforms 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. @result A reference to the new CFRunLoopSource. You must release the returned value. */ CFRunLoopSourceRef SCDynamicStoreCreateRunLoopSource ( CFAllocatorRef allocator, SCDynamicStoreRef store, CFIndex order ); /*! @function SCDynamicStoreCopyKeyList @discussion Returns an array of CFString keys representing the configuration "dynamic store" entries that match a specified pattern. @param store The "dynamic store" session. @param pattern A regex(3) regular expression pattern that will be used to match the "dynamic store" keys. @result The list of matching keys. You must release the returned value. A NULL value will be returned if the list could not be obtained. */ CFArrayRef SCDynamicStoreCopyKeyList ( SCDynamicStoreRef store, CFStringRef pattern ); /*! @function SCDynamicStoreAddValue @discussion Adds the key-value pair to the "dynamic store" if no such key already exists. @param store The "dynamic store" session. @param key The key of the value to add to the "dynamic store". @param value The value to add to the "dynamic store". @result TRUE if the key was added; FALSE if the key was already present in the "dynamic store" or if an error was encountered. */ Boolean SCDynamicStoreAddValue ( SCDynamicStoreRef store, CFStringRef key, CFPropertyListRef value ); /*! @function SCDynamicStoreAddTemporaryValue @discussion Adds the key-value pair on a temporary basis to the "dynamic store" if no such key already exists. This entry will, unless updated by another session, automatically be removed when the session is closed. @param store The "dynamic store" session. @param key The key of the value to add to the "dynamic store". @param value The value to add to the "dynamic store". @result TRUE if the key was added; FALSE if the key was already present in the "dynamic store" or if an error was encountered. */ Boolean SCDynamicStoreAddTemporaryValue ( SCDynamicStoreRef store, CFStringRef key, CFPropertyListRef value ); /*! @function SCDynamicStoreCopyValue @discussion Obtains a value from the "dynamic store" for the specified key. @param store The "dynamic store" session. @param key The key you wish to obtain. @result The value from the store that is associated with the given key. The value is returned as a Core Foundation Property List data type. You must release the returned value. If no value was located, NULL is returned. */ CFPropertyListRef SCDynamicStoreCopyValue ( SCDynamicStoreRef store, CFStringRef key ); /*! @function SCDynamicStoreCopyMultiple @discussion Fetches multiple values in the "dynamic store". @param store The "dynamic store" session. @param keys The keys to be fetched; NULL if no specific keys are requested. @param patterns The regex(3) pattern strings to be fetched; NULL if no key patterns are requested. @result A dictionary containing the specific keys which were found in the "dynamic store" and any keys which matched the specified patterns; NULL is returned if an error was encountered. You must release the returned value. */ CFDictionaryRef SCDynamicStoreCopyMultiple ( SCDynamicStoreRef store, CFArrayRef keys, CFArrayRef patterns ); /*! @function SCDynamicStoreSetValue @discussion Adds or replaces a value in the "dynamic store" for the specified key. @param store The "dynamic store" session. @param key The key you wish to set. @param value The value to add to or replace in the "dynamic store". @result TRUE if the key was updated; FALSE if an error was encountered. */ Boolean SCDynamicStoreSetValue ( SCDynamicStoreRef store, CFStringRef key, CFPropertyListRef value ); /*! @function SCDynamicStoreSetMultiple @discussion Updates multiple values in the "dynamic store". @param store The "dynamic store" session. @param keysToSet Key/value pairs you wish to set into the "dynamic store". @param keysToRemove A list of keys you wish to remove from the "dynamic store". @param keysToNotify A list of keys to flag as changed (without actually changing the data). @result TRUE if the dynamic store updates were successful; FALSE if an error was encountered. */ Boolean SCDynamicStoreSetMultiple ( SCDynamicStoreRef store, CFDictionaryRef keysToSet, CFArrayRef keysToRemove, CFArrayRef keysToNotify ); /*! @function SCDynamicStoreRemoveValue @discussion Removes the value of the specified key from the "dynamic store". @param store The "dynamic store" session. @param key The key of the value you wish to remove. @result TRUE if the key was removed; FALSE if no value was located or an error was encountered. */ Boolean SCDynamicStoreRemoveValue ( SCDynamicStoreRef store, CFStringRef key ); /*! @function SCDynamicStoreNotifyValue @discussion Triggers a notification to be delivered for the specified key in the dynamic store. @param store The "dynamic store" session. @param key The key which should be flagged as changed (without actually changing the data). @result TRUE if the value was updated; FALSE if an error was encountered. */ Boolean SCDynamicStoreNotifyValue ( SCDynamicStoreRef store, CFStringRef key ); /*! @function SCDynamicStoreSetNotificationKeys @discussion Specifies a set of specific keys and key patterns which should be monitored for changes. @param store The "dynamic store" session being watched. @param keys The keys to be monitored; NULL if no specific keys are to be monitored. @param patterns The regex(3) pattern strings to be monitored; NULL if no key patterns are to be monitored. @result TRUE if the monitored keys were set; FALSE if an error was encountered. */ Boolean SCDynamicStoreSetNotificationKeys ( SCDynamicStoreRef store, CFArrayRef keys, CFArrayRef patterns ); /*! @function SCDynamicStoreCopyNotifiedKeys @discussion Returns an array of CFString keys representing the "dynamic store" entries that have changed since this function was last called. @param store The "dynamic store" session. @result The list of changed keys. You must release the returned value. A NULL value will be returned if the list could not be obtained. */ CFArrayRef SCDynamicStoreCopyNotifiedKeys ( SCDynamicStoreRef store ); __END_DECLS #endif /* _SCDYNAMICSTORE_H */