SystemConfiguration.fproj/SCDynamicStore.h

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