SystemConfiguration.fproj/SCDynamicStore.h

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