SystemConfiguration.fproj/SCDynamicStorePrivate.h

   1 /*
   2  * Copyright (c) 2000, 2001, 2004, 2005, 2010, 2011, 2013, 2015, 2018, 2019 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 <TargetConditionals.h>
  28 #include <os/availability.h>
  29 #include <sys/cdefs.h>
  30 #include <mach/message.h>
  31 #include <CoreFoundation/CoreFoundation.h>
  32 #include <SystemConfiguration/SCDynamicStore.h>
  33
  34 /*!
  35         @header SCDynamicStorePrivate
  36         @discussion The SCDynamicStore APIs provide access to a key-value
  37                 dictionary maintained by a server process.  The dictionary is
  38                 accessible by all processes on the system.  The APIs allow you
  39                 to list the current key-value pairs, add or remove key-value
  40                 pairs, add or change the values associated with a key, and
  41                 request change notifications.
  42
  43                 The SCDynamicStore is not "persistent" (the store content
  44                 starts off empty and is not saved across boot).
  45
  46                 All interaction with the SCDynamicStore [server] is via Mach
  47                 IPC (MiG) messages.
  48
  49                 A client process, using the SCDynamicStoreSetNotificationKeys
  50                 API, specifies a list of specific keys of interest and/or a
  51                 list of regex(3) pattern strings that will be matched on
  52                 current (and future) keys in the store.  Any matched keys that
  53                 are added, updated, or removed will trigger a notification.
  54                 The notification is delivered to the monitoring session via
  55                 a "something has changed" Mach IPC message.  The callback
  56                 notification, as part of its implementation, issues a request
  57                 to the server to identify the specific list of changes and
  58                 this list is passed along as part of the callback.  Any
  59                 subsequent changes to the SCDynamicStore will trigger a new
  60                 "something has changed" Mach IPC message and an additional
  61                 callback.
  62
  63                 Note: the list (array) of changed keys passed to the
  64                       notification callback will be always be non-NULL
  65                       and non-empty with one exception.  That exception
  66                       is when the SCDynamicStore server has been restarted.
  67                       In that case, if no reconnect callback was setup
  68                       with the SCDynamicStoreSetReconnectCallBack API
  69                       then a non-NULL but empty array will be passed.
  70
  71                 Disconnect/reconnect considerations:
  72
  73                 1. We don't expect the SCDynamicStore server to fail but one
  74                    should always be prepared for the unexpected.
  75
  76                 2. Processes that write to the SCDynamicStore should be
  77                    prepared to repost any content when/if the server fails.
  78                    A callout, registered with the SCDynamicStoreSetReconnectCallBack
  79                    API, should be used to post any updates the SCDynamicStore
  80                    after a failure.
  81
  82                 3. Processes that cache SCDynamicStore content (or otherwise
  83                    maintain state based on previous notifications) should be
  84                    aware that all store content is lost when/if the server
  85                    fails.  After handling a SCDynamicStore notification with
  86                    no keys or a disconnect/reconnect callout, your code should
  87                    assume that any cached content is no longer valid.
  88
  89                 Performance considerations:
  90
  91                 1. We recommend that any code trying to capture a snapshot of
  92                    more than one SCDynamicStore key should use the SCDynamicStoreCopyMultiple
  93                    API (and not make multiple calls to SCDynamicStoreCopyValue).
  94
  95                 2. We recommend that any code making multiple (and related)
  96                    changes to the SCDynamicStore should batch them into a
  97                    single call using the SCDynamicStoreSetMultiple API (and
  98                    not make multiple calls to SCDynamicStoreSetValue).
  99  */
 100
 101 /*!
 102         @typedef SCDynamicStoreDisconnectCallBack
 103         @discussion Type of callback function used when notification of
 104                 the dynamic store session being disconnected is delivered.
 105         @param store The dynamic store session.
 106         @param info A C pointer to a user-specified block of data.
 107  */
 108 typedef void (*SCDynamicStoreDisconnectCallBack)        (
 109                                                          SCDynamicStoreRef      store,
 110                                                          void                   *info
 111                                                          );
 112
 113
 114
 115 __BEGIN_DECLS
 116
 117 /*!
 118         @function SCDynamicStoreAddWatchedKey
 119         @discussion Adds the specified key to the list of "dynamic store"
 120                 values that are being monitored for changes.
 121         @param store The "dynamic store" session being watched.
 122         @param key The key to be monitored.
 123         @param isRegex A booolean indicating whether a specific key should
 124                 be monitored or if it consists of a regex(3) pattern string
 125                 of keys.
 126         @result TRUE if the key was successfully added to the "watch"
 127                 list; FALSE if an error was encountered.
 128  */
 129 Boolean
 130 SCDynamicStoreAddWatchedKey             (SCDynamicStoreRef              store,
 131                                          CFStringRef                    key,
 132                                          Boolean                        isRegex);
 133
 134 /*!
 135         @function SCDynamicStoreRemoveWatchedKey
 136         @discussion Removes the specified key from the list of "dynamic store"
 137                 values that are being monitored for changes.
 138         @param store The "dynamic store" session being watched.
 139         @param key The key that should no longer be monitored.
 140         @param isRegex A booolean indicating whether a specific key should
 141                 be monitored or if it consists of a regex(3) pattern string
 142                 of keys.
 143         @result TRUE if the key was successfully removed from the "watch"
 144                 list; FALSE if an error was encountered.
 145  */
 146 Boolean
 147 SCDynamicStoreRemoveWatchedKey          (SCDynamicStoreRef              store,
 148                                          CFStringRef                    key,
 149                                          Boolean                        isRegex);
 150
 151 /*!
 152         @function SCDynamicStoreNotifyFileDescriptor
 153         @discussion Allocates a file descriptor that can be used to detect changes
 154                 to one of the system configuration data entries associated with the
 155                 current session's notifier keys. When a change is detected, the
 156                 specified identifier (4 bytes) will be delivered to the calling
 157                 application via the allocated file descriptor.
 158
 159         @param store An SCDynamicStoreRef that should be used for communication with the server.
 160         @param identifier A (4 byte) integer that can be used to identify this
 161                 notification.
 162         @param fd A pointer to a file descriptor.  Upon return, fd will
 163                 contain the file descriptor that will be used for any notifications.
 164         @result A boolean indicating the success (or failure) of the call.
 165  */
 166 Boolean
 167 SCDynamicStoreNotifyFileDescriptor      (SCDynamicStoreRef              store,
 168                                          int32_t                        identifier,
 169                                          int                            *fd);
 170
 171 /*!
 172         @function SCDynamicStoreNotifyWait
 173         @discussion Waits for a change to be made to a value in the
 174                 "dynamic store" that is being monitored.
 175         @param store The "dynamic store" session.
 176         @result TRUE if a change has been detected; FALSE if an error was encountered.
 177  */
 178 Boolean
 179 SCDynamicStoreNotifyWait                (SCDynamicStoreRef              store);
 180
 181 /*!
 182         @function SCDynamicStoreNotifyCancel
 183         @discussion Cancels any outstanding notification requests for
 184                 this "dynamic store" session.
 185
 186         @param store The "dynamic store" session.
 187         @result TRUE if all notifications have been cancelled; FALSE if an
 188                 error was encountered.
 189  */
 190 Boolean
 191 SCDynamicStoreNotifyCancel              (SCDynamicStoreRef              store);
 192
 193 /*!
 194         @function SCDynamicStoreSetDisconnectCallBack
 195         @discussion Assigns a callback to a SCDynamicStore session.  The function
 196                 is called when the session has been disconnected.  The callback
 197                 should be established before a client writes any content to the
 198                 SCDynamicStore to ensure that the information can be re-posted
 199                 when/if a disconnect is detected.
 200         @param store A reference to the dynamic store session.
 201         @param callout The function to be called when the session was disconnected.
 202                 If NULL, the current callback is removed.
 203         @result Returns TRUE on success, FALSE on failure.
 204  */
 205 Boolean
 206 SCDynamicStoreSetDisconnectCallBack     (
 207                                          SCDynamicStoreRef                      store,
 208                                          SCDynamicStoreDisconnectCallBack       callout
 209                                         )                               API_AVAILABLE(macos(10.7)) SPI_AVAILABLE(ios(5.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 210
 211 Boolean
 212 SCDynamicStoreSnapshot                  (SCDynamicStoreRef              store);
 213
 214
 215 Boolean
 216 _SCDynamicStoreCacheIsActive            (SCDynamicStoreRef              store)
 217                                                                         API_AVAILABLE(macos(10.15)) SPI_AVAILABLE(ios(13.0), tvos(13.0), watchos(6.0), bridgeos(4.0));
 218
 219 Boolean
 220 _SCDynamicStoreCacheOpen                (SCDynamicStoreRef              store)
 221                                                                         API_AVAILABLE(macos(10.15)) SPI_AVAILABLE(ios(13.0), tvos(13.0), watchos(6.0), bridgeos(4.0));
 222
 223 Boolean
 224 _SCDynamicStoreCacheCommitChanges       (SCDynamicStoreRef              store)
 225                                                                         API_AVAILABLE(macos(10.15)) SPI_AVAILABLE(ios(13.0), tvos(13.0), watchos(6.0), bridgeos(4.0));
 226
 227 Boolean
 228 _SCDynamicStoreCacheClose               (SCDynamicStoreRef              store)
 229                                                                         API_AVAILABLE(macos(10.15)) SPI_AVAILABLE(ios(13.0), tvos(13.0), watchos(6.0), bridgeos(4.0));
 230
 231 void
 232 _SCDynamicStoreSetSessionWatchLimit     (unsigned int                   limit)
 233                                                                         API_AVAILABLE(macos(10.15)) SPI_AVAILABLE(ios(13.0), tvos(13.0), watchos(6.0), bridgeos(4.0));
 234
 235 __END_DECLS
 236
 237 #endif  /* _SCDYNAMICSTOREPRIVATE_H */