SystemConfiguration.fproj/SCDynamicStore.h

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