SystemConfiguration.fproj/SCDynamicStorePrivate.h

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