SystemConfiguration.fproj/SCDynamicStorePrivate.h

   1 /*
   2  * Copyright (c) 2000, 2001, 2004, 2005, 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 _SCDYNAMICSTOREPRIVATE_H
  25 #define _SCDYNAMICSTOREPRIVATE_H
  26
  27 #include <sys/cdefs.h>
  28 #include <mach/message.h>
  29 #include <CoreFoundation/CoreFoundation.h>
  30 #include <SystemConfiguration/SCDynamicStore.h>
  31
  32 /*!
  33         @header SCDynamicStorePrivate
  34         @discussion The SCDynamicStore APIs provide access to a key-value
  35                 dictionary maintained by a server process.  The dictionary is
  36                 accessible by all processes on the system.  The APIs allow you
  37                 to list the current key-value pairs, add or remove key-value
  38                 pairs, add or change the values associated with a key, and
  39                 request change notifications.
  40
  41                 The SCDynamicStore is not "persistent" (the store content
  42                 starts off empty and is not saved across boot).
  43
  44                 All interaction with the SCDynamicStore [server] is via Mach
  45                 IPC (MiG) messages.
  46
  47                 A client process, using the SCDynamicStoreSetNotificationKeys
  48                 API, specifies a list of specific keys of interest and/or a
  49                 list of regex(3) pattern strings that will be matched on
  50                 current (and future) keys in the store.  Any matched keys that
  51                 are added, updated, or removed will trigger a notification.
  52                 The notification is delivered to the monitoring session via
  53                 a "something has changed" Mach IPC message.  The callback
  54                 notification, as part of its implementation, issues a request
  55                 to the server to identify the specific list of changes and
  56                 this list is passed along as part of the callback.  Any
  57                 subsequent changes to the SCDynamicStore will trigger a new
  58                 "something has changed" Mach IPC message and an additional
  59                 callback.
  60
  61                 Note: the list (array) of changed keys passed to the
  62                       notification callback will be always be non-NULL
  63                       and non-empty with one exception.  That exception
  64                       is when the SCDynamicStore server has been restarted.
  65                       In that case, if no reconnect callback was setup
  66                       with the SCDynamicStoreSetReconnectCallBack API
  67                       then a non-NULL but empty array will be passed.
  68
  69                 Disconnect/reconnect considerations:
  70
  71                 1. We don't expect the SCDynamicStore server to fail but one
  72                    should always be prepared for the unexpected.
  73
  74                 2. Processes that write to the SCDynamicStore should be
  75                    prepared to repost any content when/if the server fails.
  76                    A callout, registered with the SCDynamicStoreSetReconnectCallBack
  77                    API, should be used to post any updates the SCDynamicStore
  78                    after a failure.
  79
  80                 3. Processes that cache SCDynamicStore content (or otherwise
  81                    maintain state based on previous notifications) should be
  82                    aware that all store content is lost when/if the server
  83                    fails.  After handling a SCDynamicStore notification with
  84                    no keys or a disconnect/reconnect callout, your code should
  85                    assume that any cached content is no longer valid.
  86
  87                 Performance considerations:
  88
  89                 1. We recommend that any code trying to capture a snapshot of
  90                    more than one SCDynamicStore key should use the SCDynamicStoreCopyMultiple
  91                    API (and not make multiple calls to SCDynamicStoreCopyValue).
  92
  93                 2. We recommend that any code making multiple (and related)
  94                    changes to the SCDynamicStore should batch them into a
  95                    single call using the SCDynamicStoreSetMultiple API (and
  96                    not make multiple calls to SCDynamicStoreSetValue).
  97  */
  98
  99 /*!
 100         @typedef SCDynamicStoreCallBack
 101         @discussion Type of the callback function used when a
 102                 dynamic store change is delivered.
 103         @param store The "dynamic store" session.
 104         @param info ....
 105  */
 106 typedef boolean_t (*SCDynamicStoreCallBack_v1)  (
 107                                                 SCDynamicStoreRef       store,
 108                                                 void                    *info
 109                                                 );
 110
 111 /*!
 112         @typedef SCDynamicStoreDisconnectCallBack
 113         @discussion Type of callback function used when notification of
 114                 the dynamic store session being disconnected is delivered.
 115         @param store The dynamic store session.
 116         @param info A C pointer to a user-specified block of data.
 117  */
 118 typedef void (*SCDynamicStoreDisconnectCallBack)        (
 119                                                          SCDynamicStoreRef      store,
 120                                                          void                   *info
 121                                                          );
 122
 123
 124 __BEGIN_DECLS
 125
 126 /*!
 127         @function SCDynamicStoreLock
 128         @discussion Locks access to the configuration "dynamic store".  All
 129                 other clients attempting to access the "dynamic store" will
 130                 block. All change notifications will be deferred until the
 131                 lock is released.
 132         @param store The "dynamic store" session that should be locked.
 133         @result TRUE if the lock was obtained; FALSE if an error was encountered.
 134  */
 135 Boolean
 136 SCDynamicStoreLock                      (SCDynamicStoreRef              store);
 137
 138 /*!
 139         @function SCDynamicStoreUnlock
 140         @discussion Unlocks access to the configuration "dynamic store".  Other
 141                 clients will be able to access the "dynamic store". Any change
 142                 notifications will be delivered.
 143         @param store The "dynamic store" session that should be unlocked.
 144         @result TRUE if the lock was released; FALSE if an error was encountered.
 145  */
 146 Boolean
 147 SCDynamicStoreUnlock                    (SCDynamicStoreRef              store);
 148
 149 /*!
 150         @function SCDynamicStoreTouchValue
 151         @discussion Updates the value of the specified key in the
 152                 "dynamic store".
 153                 If the value does not exist then a CFDate object
 154                 will be associated with the key.
 155                 If the associated data is already a CFDate object
 156                 then it will be updated with the current time.
 157         @param store The "dynamic store" session.
 158         @param key The key of the value to updated.
 159         @result TRUE if the value was updated; FALSE if an error was encountered.
 160  */
 161 Boolean
 162 SCDynamicStoreTouchValue                (SCDynamicStoreRef              store,
 163                                          CFStringRef                    key);
 164
 165 /*!
 166         @function SCDynamicStoreAddWatchedKey
 167         @discussion Adds the specified key to the list of "dynamic store"
 168                 values that are being monitored for changes.
 169         @param store The "dynamic store" session being watched.
 170         @param key The key to be monitored.
 171         @param isRegex A booolean indicating whether a specific key should
 172                 be monitored or if it consists of a regex(3) pattern string
 173                 of keys.
 174         @result TRUE if the key was successfully added to the "watch"
 175                 list; FALSE if an error was encountered.
 176  */
 177 Boolean
 178 SCDynamicStoreAddWatchedKey             (SCDynamicStoreRef              store,
 179                                          CFStringRef                    key,
 180                                          Boolean                        isRegex);
 181
 182 /*!
 183         @function SCDynamicStoreRemoveWatchedKey
 184         @discussion Removes the specified key from the list of "dynamic store"
 185                 values that are being monitored for changes.
 186         @param store The "dynamic store" session being watched.
 187         @param key The key that should no longer be monitored.
 188         @param isRegex A booolean indicating whether a specific key should
 189                 be monitored or if it consists of a regex(3) pattern string
 190                 of keys.
 191         @result TRUE if the key was successfully removed from the "watch"
 192                 list; FALSE if an error was encountered.
 193  */
 194 Boolean
 195 SCDynamicStoreRemoveWatchedKey          (SCDynamicStoreRef              store,
 196                                          CFStringRef                    key,
 197                                          Boolean                        isRegex);
 198
 199 /*!
 200         @function SCDynamicStoreNotifyCallback
 201         @discussion Requests that the specified function be called whenever a
 202                 change has been detected to one of the "dynamic store" values
 203                 being monitored.
 204
 205         The callback function will be called with two arguments, store and
 206         context, that correspond to the current "dynamic store" session and
 207         the provided context argument.
 208
 209         The callback function should return a Boolean value indicating
 210         whether an error occurred during execution of the callback.
 211
 212         Note: An additional run loop source will be added for the notification.
 213         This additional source will be removed if the notification is cancelled
 214         or if the callback indicates that an error was detected.
 215
 216         @param store The "dynamic store" session.
 217         @param runLoop A pointer to the run loop.
 218         @param func The callback function to call for each notification.
 219                 If this parameter is not a pointer to a function of the
 220                 correct prototype, the behavior is undefined.
 221         @param context A pointer-sized user-defined value, that is passed as
 222                 the second parameter to the notification callback function,
 223                 but is otherwise unused by this function.  If the context
 224                 is not what is expected by the notification function, the
 225                 behavior is undefined.
 226         @result TRUE if the notification callback runloop source was
 227                 successfully added; FALSE if an error was encountered.
 228  */
 229 Boolean
 230 SCDynamicStoreNotifyCallback            (SCDynamicStoreRef              store,
 231                                          CFRunLoopRef                   runLoop,
 232                                          SCDynamicStoreCallBack_v1      func,
 233                                          void                           *context);
 234
 235 /*!
 236         @function SCDynamicStoreNotifyMachPort
 237         @discussion Allocates a mach port that can be used to detect changes to
 238                 one of the system configuration data entries associated with the
 239                 current session's notifier keys. When a change is detected, an
 240                 empty (no data) mach message with the specified identifier will
 241                 be delivered to the calling application via the allocated port.
 242
 243         @param store An SCDynamicStoreRef that should be used for communication with the server.
 244         @param msgid A mach message ID to be included with any notifications.
 245         @param port A pointer to a mach port.  Upon return, port will be filled
 246                 with the mach port that will be used for any notifications.
 247         @result A boolean indicating the success (or failure) of the call.
 248  */
 249 Boolean
 250 SCDynamicStoreNotifyMachPort            (SCDynamicStoreRef              store,
 251                                          mach_msg_id_t                  msgid,
 252                                          mach_port_t                    *port);
 253
 254 /*!
 255         @function SCDynamicStoreNotifyFileDescriptor
 256         @discussion Allocates a file descriptor that can be used to detect changes
 257                 to one of the system configuration data entries associated with the
 258                 current session's notifier keys. When a change is detected, the
 259                 specified identifier (4 bytes) will be delivered to the calling
 260                 application via the allocated file descriptor.
 261
 262         @param store An SCDynamicStoreRef that should be used for communication with the server.
 263         @param identifier A (4 byte) integer that can be used to identify this
 264                 notification.
 265         @param fd A pointer to a file descriptor.  Upon return, fd will
 266                 contain the file descriptor that will be used for any notifications.
 267         @result A boolean indicating the success (or failure) of the call.
 268  */
 269 Boolean
 270 SCDynamicStoreNotifyFileDescriptor      (SCDynamicStoreRef              store,
 271                                          int32_t                        identifier,
 272                                          int                            *fd);
 273
 274 /*!
 275         @function SCDynamicStoreNotifySignal
 276         @discussion Requests that the specified BSD signal be sent to the process
 277                 with the indicated process id whenever a change has been detected
 278                 to one of the system configuration data entries associated with the
 279                 current session's notifier keys.
 280
 281                 Note: this function is not valid for "configd" plug-ins.
 282
 283         @param store An SCDynamicStoreRef that should be used for communication with the server.
 284         @param pid A UNIX process ID that should be signalled for any notifications.
 285         @param sig A signal number to be used.
 286         @result A boolean indicating the success (or failure) of the call.
 287  */
 288 Boolean
 289 SCDynamicStoreNotifySignal              (SCDynamicStoreRef              store,
 290                                          pid_t                          pid,
 291                                          int                            sig);
 292
 293 /*!
 294         @function SCDynamicStoreNotifyWait
 295         @discussion Waits for a change to be made to a value in the
 296                 "dynamic store" that is being monitored.
 297         @param store The "dynamic store" session.
 298         @result TRUE if a change has been detected; FALSE if an error was encountered.
 299  */
 300 Boolean
 301 SCDynamicStoreNotifyWait                (SCDynamicStoreRef              store);
 302
 303 /*!
 304         @function SCDynamicStoreNotifyCancel
 305         @discussion Cancels any outstanding notification requests for
 306                 this "dynamic store" session.
 307
 308         @param store The "dynamic store" session.
 309         @result TRUE if all notifications have been cancelled; FALSE if an
 310                 error was encountered.
 311  */
 312 Boolean
 313 SCDynamicStoreNotifyCancel              (SCDynamicStoreRef              store);
 314
 315 /*!
 316         @function SCDynamicStoreSetDisconnectCallBack
 317         @discussion Assigns a callback to a SCDynamicStore session.  The function
 318                 is called when the session has been disconnected.  The callback
 319                 should be established before a client writes any content to the
 320                 SCDynamicStore to ensure that the information can be re-posted
 321                 when/if a disconnect is detected.
 322         @param store A reference to the dynamic store session.
 323         @param callout The function to be called when the session was disconnected.
 324                 If NULL, the current callback is removed.
 325         @result Returns TRUE on success, FALSE on failure.
 326  */
 327 Boolean
 328 SCDynamicStoreSetDisconnectCallBack     (
 329                                          SCDynamicStoreRef                      store,
 330                                          SCDynamicStoreDisconnectCallBack       callout
 331                                         )                               __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0/*SPI*/);
 332
 333 Boolean
 334 SCDynamicStoreSnapshot                  (SCDynamicStoreRef              store);
 335
 336 __END_DECLS
 337
 338 #endif /* _SCDYNAMICSTOREPRIVATE_H */