SystemConfiguration.fproj/SCDynamicStorePrivate.h

   1 /*
   2  * Copyright (c) 2000, 2001, 2004, 2005 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 _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  */
  35
  36 /*!
  37         @typedef SCDynamicStoreCallBack
  38         @discussion Type of the callback function used when a
  39                 dynamic store change is delivered.
  40         @param store The "dynamic store" session.
  41         @param info ....
  42  */
  43 typedef boolean_t (*SCDynamicStoreCallBack_v1)  (
  44                                                 SCDynamicStoreRef       store,
  45                                                 void                    *info
  46                                                 );
  47
  48
  49 __BEGIN_DECLS
  50
  51 /*!
  52         @function SCDynamicStoreLock
  53         @discussion Locks access to the configuration "dynamic store".  All
  54                 other clients attempting to access the "dynamic store" will
  55                 block. All change notifications will be deferred until the
  56                 lock is released.
  57         @param store The "dynamic store" session that should be locked.
  58         @result TRUE if the lock was obtained; FALSE if an error was encountered.
  59  */
  60 Boolean
  61 SCDynamicStoreLock                      (SCDynamicStoreRef              store);
  62
  63 /*!
  64         @function SCDynamicStoreUnlock
  65         @discussion Unlocks access to the configuration "dynamic store".  Other
  66                 clients will be able to access the "dynamic store". Any change
  67                 notifications will be delivered.
  68         @param store The "dynamic store" session that should be unlocked.
  69         @result TRUE if the lock was released; FALSE if an error was encountered.
  70  */
  71 Boolean
  72 SCDynamicStoreUnlock                    (SCDynamicStoreRef              store);
  73
  74 /*!
  75         @function SCDynamicStoreTouchValue
  76         @discussion Updates the value of the specified key in the
  77                 "dynamic store".
  78                 If the value does not exist then a CFDate object
  79                 will be associated with the key.
  80                 If the associated data is already a CFDate object
  81                 then it will be updated with the current time.
  82         @param store The "dynamic store" session.
  83         @param key The key of the value to updated.
  84         @result TRUE if the value was updated; FALSE if an error was encountered.
  85  */
  86 Boolean
  87 SCDynamicStoreTouchValue                (SCDynamicStoreRef              store,
  88                                          CFStringRef                    key);
  89
  90 /*!
  91         @function SCDynamicStoreAddWatchedKey
  92         @discussion Adds the specified key to the list of "dynamic store"
  93                 values that are being monitored for changes.
  94         @param store The "dynamic store" session being watched.
  95         @param key The key to be monitored.
  96         @param isRegex A booolean indicating whether a specific key should
  97                 be monitored or if it consists of a regex(3) pattern string
  98                 of keys.
  99         @result TRUE if the key was successfully added to the "watch"
 100                 list; FALSE if an error was encountered.
 101  */
 102 Boolean
 103 SCDynamicStoreAddWatchedKey             (SCDynamicStoreRef              store,
 104                                          CFStringRef                    key,
 105                                          Boolean                        isRegex);
 106
 107 /*!
 108         @function SCDynamicStoreRemoveWatchedKey
 109         @discussion Removes the specified key from the list of "dynamic store"
 110                 values that are being monitored for changes.
 111         @param store The "dynamic store" session being watched.
 112         @param key The key that should no longer be monitored.
 113         @param isRegex A booolean indicating whether a specific key should
 114                 be monitored or if it consists of a regex(3) pattern string
 115                 of keys.
 116         @result TRUE if the key was successfully removed from the "watch"
 117                 list; FALSE if an error was encountered.
 118  */
 119 Boolean
 120 SCDynamicStoreRemoveWatchedKey          (SCDynamicStoreRef              store,
 121                                          CFStringRef                    key,
 122                                          Boolean                        isRegex);
 123
 124 /*!
 125         @function SCDynamicStoreNotifyCallback
 126         @discussion Requests that the specified function be called whenever a
 127                 change has been detected to one of the "dynamic store" values
 128                 being monitored.
 129
 130         The callback function will be called with two arguments, store and
 131         context, that correspond to the current "dynamic store" session and
 132         the provided context argument.
 133
 134         The callback function should return a Boolean value indicating
 135         whether an error occurred during execution of the callback.
 136
 137         Note: An additional run loop source will be added for the notification.
 138         This additional source will be removed if the notification is cancelled
 139         or if the callback indicates that an error was detected.
 140
 141         @param store The "dynamic store" session.
 142         @param runLoop A pointer to the run loop.
 143         @param func The callback function to call for each notification.
 144                 If this parameter is not a pointer to a function of the
 145                 correct prototype, the behavior is undefined.
 146         @param context A pointer-sized user-defined value, that is passed as
 147                 the second parameter to the notification callback function,
 148                 but is otherwise unused by this function.  If the context
 149                 is not what is expected by the notification function, the
 150                 behavior is undefined.
 151         @result TRUE if the notification callback runloop source was
 152                 successfully added; FALSE if an error was encountered.
 153  */
 154 Boolean
 155 SCDynamicStoreNotifyCallback            (SCDynamicStoreRef              store,
 156                                          CFRunLoopRef                   runLoop,
 157                                          SCDynamicStoreCallBack_v1      func,
 158                                          void                           *context);
 159
 160 /*!
 161         @function SCDynamicStoreNotifyMachPort
 162         @discussion Allocates a mach port that can be used to detect changes to
 163                 one of the system configuration data entries associated with the
 164                 current session's notifier keys. When a change is detected, an
 165                 empty (no data) mach message with the specified identifier will
 166                 be delivered to the calling application via the allocated port.
 167
 168         @param store An SCDynamicStoreRef that should be used for communication with the server.
 169         @param msgid A mach message ID to be included with any notifications.
 170         @param port A pointer to a mach port.  Upon return, port will be filled
 171                 with the mach port that will be used for any notifications.
 172         @result A boolean indicating the success (or failure) of the call.
 173  */
 174 Boolean
 175 SCDynamicStoreNotifyMachPort            (SCDynamicStoreRef              store,
 176                                          mach_msg_id_t                  msgid,
 177                                          mach_port_t                    *port);
 178
 179 /*!
 180         @function SCDynamicStoreNotifyFileDescriptor
 181         @discussion Allocates a file descriptor that can be used to detect changes
 182                 to one of the system configuration data entries associated with the
 183                 current session's notifier keys. When a change is detected, the
 184                 specified identifier (4 bytes) will be delivered to the calling
 185                 application via the allocated file descriptor.
 186
 187         @param store An SCDynamicStoreRef that should be used for communication with the server.
 188         @param identifier A (4 byte) integer that can be used to identify this
 189                 notification.
 190         @param fd A pointer to a file descriptor.  Upon return, fd will
 191                 contain the file descriptor that will be used for any notifications.
 192         @result A boolean indicating the success (or failure) of the call.
 193  */
 194 Boolean
 195 SCDynamicStoreNotifyFileDescriptor      (SCDynamicStoreRef              store,
 196                                          int32_t                        identifier,
 197                                          int                            *fd);
 198
 199 /*!
 200         @function SCDynamicStoreNotifySignal
 201         @discussion Requests that the specified BSD signal be sent to the process
 202                 with the indicated process id whenever a change has been detected
 203                 to one of the system configuration data entries associated with the
 204                 current session's notifier keys.
 205
 206                 Note: this function is not valid for "configd" plug-ins.
 207
 208         @param store An SCDynamicStoreRef that should be used for communication with the server.
 209         @param pid A UNIX process ID that should be signalled for any notifications.
 210         @param sig A signal number to be used.
 211         @result A boolean indicating the success (or failure) of the call.
 212  */
 213 Boolean
 214 SCDynamicStoreNotifySignal              (SCDynamicStoreRef              store,
 215                                          pid_t                          pid,
 216                                          int                            sig);
 217
 218 /*!
 219         @function SCDynamicStoreNotifyWait
 220         @discussion Waits for a change to be made to a value in the
 221                 "dynamic store" that is being monitored.
 222         @param store The "dynamic store" session.
 223         @result TRUE if a change has been detected; FALSE if an error was encountered.
 224  */
 225 Boolean
 226 SCDynamicStoreNotifyWait                (SCDynamicStoreRef              store);
 227
 228 /*!
 229         @function SCDynamicStoreNotifyCancel
 230         @discussion Cancels any outstanding notification requests for
 231                 this "dynamic store" session.
 232
 233         @param store The "dynamic store" session.
 234         @result TRUE if all notifications have been cancelled; FALSE if an
 235                 error was encountered.
 236  */
 237 Boolean
 238 SCDynamicStoreNotifyCancel              (SCDynamicStoreRef              store);
 239
 240 Boolean
 241 SCDynamicStoreSnapshot                  (SCDynamicStoreRef              store);
 242
 243 __END_DECLS
 244
 245 #endif /* _SCDYNAMICSTOREPRIVATE_H */