SystemConfiguration.fproj/SCDynamicStore.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 #ifndef _SCDYNAMICSTORE_H
  25 #define _SCDYNAMICSTORE_H
  26
  27 #include <sys/cdefs.h>
  28 #include <sys/syslog.h>
  29 #include <mach/message.h>
  30 #include <CoreFoundation/CoreFoundation.h>
  31
  32
  33 /*!
  34         @header SCDynamicStore
  35         The SystemConfiguration framework provides access to the
  36         data used to configure a running system.  The APIs provided
  37         by this framework communicate with the "configd" daemon.
  38
  39         The "configd" daemon manages a "dynamic store" reflecting the
  40         desired configuration settings as well as the current state
  41         of the system.  The daemon provides a notification mechanism
  42         for user-level processes that need to be aware of changes
  43         made to the data.  Lastly, the daemon loads a number of
  44         bundles (or plug-ins) that monitor low-level kernel events
  45         and, via a set of policy modules, keep the state data up
  46         to date.
  47  */
  48
  49
  50 /*!
  51         @typedef SCDynamicStoreRef
  52         @discussion This is the handle to an open "dynamic store" session
  53                 with the system configuration daemon.
  54  */
  55 typedef const struct __SCDynamicStore * SCDynamicStoreRef;
  56
  57 /*!
  58         @typedef SCDynamicStoreContext
  59  */
  60 typedef struct {
  61         CFIndex         version;
  62         void *          info;
  63         const void      *(*retain)(const void *info);
  64         void            (*release)(const void *info);
  65         CFStringRef     (*copyDescription)(const void *info);
  66 } SCDynamicStoreContext;
  67
  68 /*!
  69         @typedef SCDynamicStoreCallBack
  70         @discussion Type of the callback function used when a
  71                 dynamic store change is delivered.
  72         @param store The "dynamic store" session.
  73         @param changedKeys The list of changed keys.
  74         @param info ....
  75  */
  76 typedef void (*SCDynamicStoreCallBack)  (
  77                                         SCDynamicStoreRef       store,
  78                                         CFArrayRef              changedKeys,
  79                                         void                    *info
  80                                         );
  81
  82
  83 __BEGIN_DECLS
  84
  85 /*!
  86         @function SCDynamicStoreGetTypeID
  87         Returns the type identifier of all SCDynamicStore instances.
  88  */
  89 CFTypeID
  90 SCDynamicStoreGetTypeID                 (void);
  91
  92
  93 /*!
  94         @function SCDynamicStoreCreate
  95         @discussion Creates a new session used to interact with the dynamic
  96                 store maintained by the SystemConfiguration server.
  97         @param allocator The CFAllocator which should be used to allocate
  98                 memory for the local "dynamic store" and its storage for
  99                 values.
 100                 This parameter may be NULL in which case the current
 101                 default CFAllocator is used. If this reference is not
 102                 a valid CFAllocator, the behavior is undefined.
 103         @param name A string that describes the name of the calling
 104                 process or plug-in of the caller.
 105         @param callout The function to be called when a watched value
 106                 in the "dynamic store" is changed.
 107                 A NULL value can be specified if no callouts are
 108                 desired.
 109         @param context The SCDynamicStoreContext associated with the callout.
 110         @result A reference to the new SCDynamicStore.
 111  */
 112 SCDynamicStoreRef
 113 SCDynamicStoreCreate                    (
 114                                         CFAllocatorRef                  allocator,
 115                                         CFStringRef                     name,
 116                                         SCDynamicStoreCallBack          callout,
 117                                         SCDynamicStoreContext           *context
 118                                         );
 119
 120 /*!
 121         @function SCDynamicStoreCreateRunLoopSource
 122         @discussion Creates a new session used to interact with the dynamic
 123                 store maintained by the SystemConfiguration server.
 124         @param allocator The CFAllocator which should be used to allocate
 125                 memory for the local "dynamic store" and its storage for
 126                 values.
 127                 This parameter may be NULL in which case the current
 128                 default CFAllocator is used. If this reference is not
 129                 a valid CFAllocator, the behavior is undefined.
 130         @param store The "dynamic store" session.
 131         @param order On platforms which support it, this parameter
 132                 determines the order in which the sources which are
 133                 ready to be processed are handled.  A lower order
 134                 number causes processing before higher order number
 135                 sources. It is inadvisable to depend on the order
 136                 number for any architectural or design aspect of
 137                 code. In the absence of any reason to do otherwise,
 138                 zero should be used.
 139         @result A reference to the new CFRunLoopSource.
 140                 You must release the returned value.
 141
 142  */
 143 CFRunLoopSourceRef
 144 SCDynamicStoreCreateRunLoopSource       (
 145                                         CFAllocatorRef                  allocator,
 146                                         SCDynamicStoreRef               store,
 147                                         CFIndex                         order
 148                                         );
 149
 150 /*!
 151         @function SCDynamicStoreCopyKeyList
 152         @discussion Returns an array of CFString keys representing the
 153                 configuration "dynamic store" entries that match a
 154                 specified pattern.
 155         @param store The "dynamic store" session.
 156         @param pattern A regex(3) regular expression pattern that
 157                 will be used to match the "dynamic store" keys.
 158         @result The list of matching keys.
 159                 You must release the returned value.
 160                 A NULL value will be returned if the list could not be obtained.
 161  */
 162 CFArrayRef
 163 SCDynamicStoreCopyKeyList               (
 164                                         SCDynamicStoreRef               store,
 165                                         CFStringRef                     pattern
 166                                         );
 167
 168 /*!
 169         @function SCDynamicStoreAddValue
 170         @discussion Adds the key-value pair to the "dynamic store" if no
 171                 such key already exists.
 172         @param store The "dynamic store" session.
 173         @param key The key of the value to add to the "dynamic store".
 174         @param value The value to add to the "dynamic store".
 175         @result TRUE if the key was added; FALSE if the key was already
 176                 present in the "dynamic store" or if an error was encountered.
 177  */
 178 Boolean
 179 SCDynamicStoreAddValue                  (
 180                                         SCDynamicStoreRef               store,
 181                                         CFStringRef                     key,
 182                                         CFPropertyListRef               value
 183                                         );
 184
 185 /*!
 186         @function SCDynamicStoreAddTemporaryValue
 187         @discussion Adds the key-value pair on a temporary basis to the
 188                 "dynamic store" if no such key already exists.  This entry
 189                 will, unless updated by another session, automatically be
 190                 removed when the session is closed.
 191         @param store The "dynamic store" session.
 192         @param key The key of the value to add to the "dynamic store".
 193         @param value The value to add to the "dynamic store".
 194         @result TRUE if the key was added; FALSE if the key was already
 195                 present in the "dynamic store" or if an error was encountered.
 196  */
 197 Boolean
 198 SCDynamicStoreAddTemporaryValue         (
 199                                         SCDynamicStoreRef               store,
 200                                         CFStringRef                     key,
 201                                         CFPropertyListRef               value
 202                                         );
 203
 204 /*!
 205         @function SCDynamicStoreCopyValue
 206         @discussion Obtains a value from the "dynamic store" for the
 207                 specified key.
 208         @param store The "dynamic store" session.
 209         @param key The key you wish to obtain.
 210         @result The value from the store that is associated with the
 211                 given key.  The value is returned as a Core Foundation
 212                 Property List data type.
 213                 You must release the returned value.
 214                 If no value was located, NULL is returned.
 215  */
 216 CFPropertyListRef
 217 SCDynamicStoreCopyValue                 (
 218                                         SCDynamicStoreRef               store,
 219                                         CFStringRef                     key
 220                                         );
 221
 222 /*!
 223         @function SCDynamicStoreCopyMultiple
 224         @discussion Fetches multiple values in the "dynamic store".
 225         @param store The "dynamic store" session.
 226         @param keys The keys to be fetched; NULL if no specific keys
 227                 are requested.
 228         @param patterns The regex(3) pattern strings to be fetched; NULL
 229                 if no key patterns are requested.
 230         @result A dictionary containing the specific keys which were found
 231                 in the "dynamic store" and any keys which matched the specified
 232                 patterns; NULL is returned if an error was encountered.
 233                 You must release the returned value.
 234  */
 235 CFDictionaryRef
 236 SCDynamicStoreCopyMultiple              (
 237                                         SCDynamicStoreRef               store,
 238                                         CFArrayRef                      keys,
 239                                         CFArrayRef                      patterns
 240                                         );
 241
 242 /*!
 243         @function SCDynamicStoreSetValue
 244         @discussion Adds or replaces a value in the "dynamic store" for
 245                 the specified key.
 246         @param store The "dynamic store" session.
 247         @param key The key you wish to set.
 248         @param value The value to add to or replace in the "dynamic store".
 249         @result TRUE if the key was updated; FALSE if an error was encountered.
 250  */
 251 Boolean
 252 SCDynamicStoreSetValue                  (
 253                                         SCDynamicStoreRef               store,
 254                                         CFStringRef                     key,
 255                                         CFPropertyListRef               value
 256                                         );
 257
 258 /*!
 259         @function SCDynamicStoreSetMultiple
 260         @discussion Updates multiple values in the "dynamic store".
 261         @param store The "dynamic store" session.
 262         @param keysToSet Key/value pairs you wish to set into the "dynamic store".
 263         @param keysToRemove A list of keys you wish to remove from the "dynamic store".
 264         @param keysToNotify A list of keys to flag as changed (without actually changing the data).
 265         @result TRUE if the dynamic store updates were successful; FALSE if an error was encountered.
 266  */
 267 Boolean
 268 SCDynamicStoreSetMultiple               (
 269                                         SCDynamicStoreRef               store,
 270                                         CFDictionaryRef                 keysToSet,
 271                                         CFArrayRef                      keysToRemove,
 272                                         CFArrayRef                      keysToNotify
 273                                         );
 274
 275 /*!
 276         @function SCDynamicStoreRemoveValue
 277         @discussion Removes the value of the specified key from the
 278                 "dynamic store".
 279         @param store The "dynamic store" session.
 280         @param key The key of the value you wish to remove.
 281         @result TRUE if the key was removed; FALSE if no value was
 282                 located or an error was encountered.
 283  */
 284 Boolean
 285 SCDynamicStoreRemoveValue               (
 286                                         SCDynamicStoreRef               store,
 287                                         CFStringRef                     key
 288                                         );
 289
 290 /*!
 291         @function SCDynamicStoreNotifyValue
 292         @discussion Triggers a notification to be delivered for the
 293                 specified key in the dynamic store.
 294         @param store The "dynamic store" session.
 295         @param key The key which should be flagged as changed (without actually changing the data).
 296         @result TRUE if the value was updated; FALSE if an error was encountered.
 297  */
 298 Boolean
 299 SCDynamicStoreNotifyValue               (
 300                                         SCDynamicStoreRef               store,
 301                                         CFStringRef                     key
 302                                         );
 303
 304 /*!
 305         @function SCDynamicStoreSetNotificationKeys
 306         @discussion Specifies a set of specific keys and key patterns
 307                 which should be monitored for changes.
 308         @param store The "dynamic store" session being watched.
 309         @param keys The keys to be monitored; NULL if no specific keys
 310                 are to be monitored.
 311         @param patterns The regex(3) pattern strings to be monitored; NULL
 312                 if no key patterns are to be monitored.
 313         @result TRUE if the monitored keys were set; FALSE if an error
 314                 was encountered.
 315  */
 316 Boolean
 317 SCDynamicStoreSetNotificationKeys       (
 318                                         SCDynamicStoreRef               store,
 319                                         CFArrayRef                      keys,
 320                                         CFArrayRef                      patterns
 321                                         );
 322
 323 /*!
 324         @function SCDynamicStoreCopyNotifiedKeys
 325         @discussion Returns an array of CFString keys representing the
 326                 "dynamic store" entries that have changed since this
 327                 function was last called.
 328         @param store The "dynamic store" session.
 329         @result The list of changed keys.
 330                 You must release the returned value.
 331                 A NULL value will be returned if the list could not be obtained.
 332  */
 333 CFArrayRef
 334 SCDynamicStoreCopyNotifiedKeys          (
 335                                         SCDynamicStoreRef               store
 336                                         );
 337
 338 __END_DECLS
 339
 340 #endif /* _SCDYNAMICSTORE_H */