SystemConfiguration.fproj/SCDynamicStore.h

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