X-Git-Url: https://git.saurik.com/apple/configd.git/blobdiff_plain/8a3cc56ef8bd82b57e913710d53889e0d9c406b3..0fae82ee9e32dcee00597b75650c675a75eab32e:/SystemConfiguration.fproj/SCDynamicStore.h diff --git a/SystemConfiguration.fproj/SCDynamicStore.h b/SystemConfiguration.fproj/SCDynamicStore.h new file mode 100644 index 0000000..9347352 --- /dev/null +++ b/SystemConfiguration.fproj/SCDynamicStore.h @@ -0,0 +1,339 @@ +/* + * 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 +#include +#include +#include + + +/*! + @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 */