SystemConfiguration.fproj/SCDynamicStore.h

   1 /*
   2  * Copyright (c) 2000, 2001, 2003-2005 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 <AvailabilityMacros.h>
  28 #include <sys/cdefs.h>
  29 #include <CoreFoundation/CoreFoundation.h>
  30
  31 /*!
  32         @header SCDynamicStore
  33         @discussion The SCDynamicStore API provides access to the key-value
  34                 pairs in the dynamic store of a running system.  The dynamic
  35                 store contains, among other items, a copy of the configuration
  36                 settings for the currently active set (which is sometimes
  37                 refered to as the location) and information about the current
  38                 network state.
  39
  40                 The functions in the SCDynamicStore API allow you to find
  41                 key-value pairs, add or remove key-value pairs, add or change
  42                 values, and request notifications.
  43
  44                 To use the functions of the SCDynamicStore API, you must first
  45                 establish a dynamic store session using the SCDynamicStoreCreate
  46                 function.  When you are finished with the session, use CFRelease
  47                 to close it.
  48  */
  49
  50
  51 /*!
  52         @typedef SCDynamicStoreRef
  53         @discussion This is the handle to an open a dynamic store session
  54                 with the system configuration daemon.
  55  */
  56 typedef const struct __SCDynamicStore * SCDynamicStoreRef;
  57
  58 /*!
  59         @typedef SCDynamicStoreContext
  60         Structure containing user-specified data and callbacks for an
  61         SCDynamicStore session.
  62         @field version The version number of the structure type being passed
  63                 in as a parameter to the SCDynamicStore creation function.
  64                 This structure is version 0.
  65         @field info A C pointer to a user-specified block of data.
  66         @field retain The callback used to add a retain for the info field.
  67                 If this parameter is not a pointer to a function of the correct
  68                 prototype, the behavior is undefined.  The value may be NULL.
  69         @field release The calllback used to remove a retain previously added
  70                 for the info field.  If this parameter is not a pointer to a
  71                 function of the correct prototype, the behavior is undefined.
  72                 The value may be NULL.
  73         @field copyDescription The callback used to provide a description of
  74                 the info field.
  75  */
  76 typedef struct {
  77         CFIndex         version;
  78         void *          info;
  79         const void      *(*retain)(const void *info);
  80         void            (*release)(const void *info);
  81         CFStringRef     (*copyDescription)(const void *info);
  82 } SCDynamicStoreContext;
  83
  84 /*!
  85         @typedef SCDynamicStoreCallBack
  86         @discussion Type of callback function used when notification of
  87                 changes to the dynamic store is delivered.
  88         @param store The dynamic store session.
  89         @param changedKeys The list of changed keys.
  90         @param info A C pointer to a user-specified block of data.
  91  */
  92 typedef void (*SCDynamicStoreCallBack)  (
  93                                         SCDynamicStoreRef       store,
  94                                         CFArrayRef              changedKeys,
  95                                         void                    *info
  96                                         );
  97
  98
  99 __BEGIN_DECLS
 100
 101 /*!
 102         @function SCDynamicStoreGetTypeID
 103         @discussion Returns the type identifier of all SCDynamicStore instances.
 104  */
 105 CFTypeID
 106 SCDynamicStoreGetTypeID                 (void);
 107
 108
 109 /*!
 110         @function SCDynamicStoreCreate
 111         @discussion Creates a new session used to interact with the dynamic
 112                 store maintained by the System Configuration server.
 113         @param allocator The CFAllocator that should be used to allocate
 114                 memory for the local dynamic store object.
 115                 This parameter may be NULL in which case the current
 116                 default CFAllocator is used. If this reference is not
 117                 a valid CFAllocator, the behavior is undefined.
 118         @param name A string that describes the name of the calling
 119                 process or plug-in of the caller.
 120         @param callout The function to be called when a watched value
 121                 in the dynamic store is changed.
 122                 A NULL value can be specified if no callouts are
 123                 desired.
 124         @param context The SCDynamicStoreContext associated with the callout.
 125         @result Returns a reference to the new SCDynamicStore session.
 126                 You must release the returned value.
 127  */
 128 SCDynamicStoreRef
 129 SCDynamicStoreCreate                    (
 130                                         CFAllocatorRef                  allocator,
 131                                         CFStringRef                     name,
 132                                         SCDynamicStoreCallBack          callout,
 133                                         SCDynamicStoreContext           *context
 134                                         );
 135
 136 #if MAC_OS_X_VERSION_MAX_ALLOWED >= 1040
 137
 138 /*!
 139         @function SCDynamicStoreCreateWithOptions
 140         @discussion Creates a new session used to interact with the dynamic
 141                 store maintained by the System Configuration server.
 142         @param allocator The CFAllocator that should be used to allocate
 143                 memory for the local dynamic store object.
 144                 This parameter may be NULL in which case the current
 145                 default CFAllocator is used. If this reference is not
 146                 a valid CFAllocator, the behavior is undefined.
 147         @param name A string that describes the name of the calling
 148                 process or plug-in of the caller.
 149         @param storeOptions A CFDictionary containing options for the
 150                 dynamic store session (such as whether all keys added or set
 151                 into the dynamic store should be per-session keys).
 152
 153                 Currently available options include:
 154
 155                 <TABLE BORDER>
 156                 <TR>
 157                         <TH>key</TD>
 158                         <TH>value</TD>
 159                 </TR>
 160                 <TR>
 161                         <TD>kSCDynamicStoreUseSessionKeys</TD>
 162                         <TD>CFBooleanRef</TD>
 163                 </TR>
 164                 </TABLE>
 165
 166                 A NULL value can be specified if no options are desired.
 167         @param callout The function to be called when a watched value
 168                 in the dynamic store is changed.
 169                 A NULL value can be specified if no callouts are
 170                 desired.
 171         @param context The SCDynamicStoreContext associated with the callout.
 172         @result Returns a reference to the new SCDynamicStore session.
 173                 You must release the returned value.
 174  */
 175 SCDynamicStoreRef
 176 SCDynamicStoreCreateWithOptions         (
 177                                         CFAllocatorRef                  allocator,
 178                                         CFStringRef                     name,
 179                                         CFDictionaryRef                 storeOptions,
 180                                         SCDynamicStoreCallBack          callout,
 181                                         SCDynamicStoreContext           *context
 182                                         )                               AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
 183
 184 extern const CFStringRef        kSCDynamicStoreUseSessionKeys           AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;      /* CFBoolean */
 185
 186 #endif  /* MAC_OS_X_VERSION_MAX_ALLOWED >= 1040 */
 187
 188 /*!
 189         @function SCDynamicStoreCreateRunLoopSource
 190         @discussion Creates a CFRunLoopSource object that can be added to the
 191                 application's run loop.  All dynamic store notifications are
 192                 delivered using this run loop source.
 193         @param allocator The CFAllocator that should be used to allocate
 194                 memory for this run loop source.
 195                 This parameter may be NULL in which case the current
 196                 default CFAllocator is used. If this reference is not
 197                 a valid CFAllocator, the behavior is undefined.
 198         @param store A reference to the dynamic store session.
 199         @param order On platforms which support it, for source versions
 200                 which support it, this parameter determines the order in
 201                 which the sources which are ready to be processed are
 202                 handled. A lower order number causes processing before
 203                 higher order number sources. It is inadvisable to depend
 204                 on the order number for any architectural or design aspect
 205                 of code. In the absence of any reason to do otherwise,
 206                 zero should be used.
 207         @result A reference to the new CFRunLoopSource.
 208                 You must release the returned value.
 209
 210  */
 211 CFRunLoopSourceRef
 212 SCDynamicStoreCreateRunLoopSource       (
 213                                         CFAllocatorRef                  allocator,
 214                                         SCDynamicStoreRef               store,
 215                                         CFIndex                         order
 216                                         );
 217
 218 /*!
 219         @function SCDynamicStoreCopyKeyList
 220         @discussion Returns an array of CFString keys representing the
 221                 current dynamic store entries that match a specified pattern.
 222         @param store The dynamic store session.
 223         @param pattern A regex(3) regular expression pattern
 224                 used to match the dynamic store keys.
 225         @result Returns the list of matching keys; NULL if an error was
 226                 encountered.
 227                 You must release the returned value.
 228  */
 229 CFArrayRef
 230 SCDynamicStoreCopyKeyList               (
 231                                         SCDynamicStoreRef               store,
 232                                         CFStringRef                     pattern
 233                                         );
 234
 235 /*!
 236         @function SCDynamicStoreAddValue
 237         @discussion Adds the key-value pair to the dynamic store if no
 238                 such key already exists.
 239         @param store The dynamic store session.
 240         @param key The key of the value to add to the dynamic store.
 241         @param value The value to add to the dynamic store.
 242         @result Returns TRUE if the key was added; FALSE if the key was already
 243                 present in the dynamic store or if an error was encountered.
 244  */
 245 Boolean
 246 SCDynamicStoreAddValue                  (
 247                                         SCDynamicStoreRef               store,
 248                                         CFStringRef                     key,
 249                                         CFPropertyListRef               value
 250                                         );
 251
 252 /*!
 253         @function SCDynamicStoreAddTemporaryValue
 254         @discussion Temporarily adds the key-value pair to the dynamic store
 255                 if no such key already exists.  Unless the key is updated by another
 256                 session, the key-value pair will be removed automatically when the
 257                 session is closed.
 258         @param store The dynamic store session.
 259         @param key The key of the value to add to the dynamic store.
 260         @param value The value to add to the dynamic store.
 261         @result Returns TRUE if the key was added; FALSE if the key was already
 262                 present in the dynamic store or if an error was encountered.
 263  */
 264 Boolean
 265 SCDynamicStoreAddTemporaryValue         (
 266                                         SCDynamicStoreRef               store,
 267                                         CFStringRef                     key,
 268                                         CFPropertyListRef               value
 269                                         );
 270
 271 /*!
 272         @function SCDynamicStoreCopyValue
 273         @discussion Gets the value of the specified key from the dynamic store.
 274         @param store The dynamic store session.
 275         @param key The key associated with the value you want to get.
 276         @result Returns the value from the dynamic store that is associated with the given
 277                 key; NULL if no value was located or an error was encountered.
 278                 You must release the returned value.
 279  */
 280 CFPropertyListRef
 281 SCDynamicStoreCopyValue                 (
 282                                         SCDynamicStoreRef               store,
 283                                         CFStringRef                     key
 284                                         );
 285
 286 /*!
 287         @function SCDynamicStoreCopyMultiple
 288         @discussion Gets the values of multiple keys in the dynamic store.
 289         @param store The dynamic store session.
 290         @param keys The keys associated with the values you want to get; NULL if no specific
 291                 keys are requested.
 292         @param patterns An array of regex(3) pattern strings used to match the keys; NULL
 293                 if no key patterns are requested.
 294         @result Returns a dictionary containing the key-value pairs of specific keys and the
 295                 key-value pairs of keys that matched the specified patterns;
 296                 NULL if an error was encountered.
 297                 You must release the returned value.
 298  */
 299 CFDictionaryRef
 300 SCDynamicStoreCopyMultiple              (
 301                                         SCDynamicStoreRef               store,
 302                                         CFArrayRef                      keys,
 303                                         CFArrayRef                      patterns
 304                                         );
 305
 306 /*!
 307         @function SCDynamicStoreSetValue
 308         @discussion Adds or replaces a value in the dynamic store for
 309                 the specified key.
 310         @param store The dynamic store session.
 311         @param key The key you want to set.
 312         @param value The value to add to or replace in the dynamic store.
 313         @result Returns TRUE if the key was updated; FALSE if an error was encountered.
 314  */
 315 Boolean
 316 SCDynamicStoreSetValue                  (
 317                                         SCDynamicStoreRef               store,
 318                                         CFStringRef                     key,
 319                                         CFPropertyListRef               value
 320                                         );
 321
 322 /*!
 323         @function SCDynamicStoreSetMultiple
 324         @discussion Updates multiple values in the dynamic store.
 325         @param store The dynamic store session.
 326         @param keysToSet A dictionary of key-value pairs you want to set into the dynamic store.
 327         @param keysToRemove An array of keys you want to remove from the dynamic store.
 328         @param keysToNotify An array of keys to flag as changed (without changing their values).
 329         @result Returns TRUE if the dynamic store updates were successful; FALSE if an error was encountered.
 330  */
 331 Boolean
 332 SCDynamicStoreSetMultiple               (
 333                                         SCDynamicStoreRef               store,
 334                                         CFDictionaryRef                 keysToSet,
 335                                         CFArrayRef                      keysToRemove,
 336                                         CFArrayRef                      keysToNotify
 337                                         );
 338
 339 /*!
 340         @function SCDynamicStoreRemoveValue
 341         @discussion Removes the value of the specified key from the
 342                 dynamic store.
 343         @param store The dynamic store session.
 344         @param key The key of the value you want to remove.
 345         @result Returns TRUE if the key was removed; FALSE if no value was
 346                 located or an error was encountered.
 347  */
 348 Boolean
 349 SCDynamicStoreRemoveValue               (
 350                                         SCDynamicStoreRef               store,
 351                                         CFStringRef                     key
 352                                         );
 353
 354 /*!
 355         @function SCDynamicStoreNotifyValue
 356         @discussion Triggers a notification to be delivered for the
 357                 specified key in the dynamic store.
 358         @param store The dynamic store session.
 359         @param key The key that should be flagged as changed.  Any dynamic store sessions
 360                 that are monitoring this key will received a notification.  Note that the
 361                 key's value is not updated.
 362         @result Returns TRUE if the notification was processed; FALSE if an error was encountered.
 363  */
 364 Boolean
 365 SCDynamicStoreNotifyValue               (
 366                                         SCDynamicStoreRef               store,
 367                                         CFStringRef                     key
 368                                         );
 369
 370 /*!
 371         @function SCDynamicStoreSetNotificationKeys
 372         @discussion Specifies a set of specific keys and key patterns
 373                 that should be monitored for changes.
 374         @param store The dynamic store session being watched.
 375         @param keys An array of keys to be monitored; NULL if no specific keys
 376                 are to be monitored.
 377         @param patterns An array of regex(3) pattern strings used to match keys to be monitored;
 378                 NULL if no key patterns are to be monitored.
 379         @result Returns TRUE if the set of notification keys and patterns was successfully
 380                 updated; FALSE if an error was encountered.
 381  */
 382 Boolean
 383 SCDynamicStoreSetNotificationKeys       (
 384                                         SCDynamicStoreRef               store,
 385                                         CFArrayRef                      keys,
 386                                         CFArrayRef                      patterns
 387                                         );
 388
 389 /*!
 390         @function SCDynamicStoreCopyNotifiedKeys
 391         @discussion Returns an array of CFString keys representing the
 392                 dynamic store entries that have changed since this
 393                 function was last called.  If possible, your application should
 394                 use the notification functions instead of polling for the list
 395                 of changed keys returned by this function.
 396         @param store The dynamic store session.
 397         @result Returns the list of changed keys;
 398                 NULL if an error was encountered.
 399                 You must release the returned value.
 400  */
 401 CFArrayRef
 402 SCDynamicStoreCopyNotifiedKeys          (
 403                                         SCDynamicStoreRef               store
 404                                         );
 405
 406 __END_DECLS
 407
 408 #endif /* _SCDYNAMICSTORE_H */