SystemConfiguration.fproj/SCDynamicStore.h

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