SystemConfiguration.fproj/SCDynamicStore.h

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