overby.me
this repo has no description
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 */
108typedef 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 */
129Boolean
130SCDynamicStoreAddWatchedKey (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 */
146Boolean
147SCDynamicStoreRemoveWatchedKey (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 */
166Boolean
167SCDynamicStoreNotifyFileDescriptor (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 */
178Boolean
179SCDynamicStoreNotifyWait (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 */
190Boolean
191SCDynamicStoreNotifyCancel (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 */
205Boolean
206SCDynamicStoreSetDisconnectCallBack (
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
211Boolean
212SCDynamicStoreSnapshot (SCDynamicStoreRef store);
213
214
215Boolean
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
219Boolean
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
223Boolean
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
227Boolean
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
231void
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 */