SystemConfiguration.fproj/SCDynamicStorePrivate.h

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