SystemConfiguration.fproj/SCDynamicStore.h

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