overby.me
this repo has no description
1/*
2 * Copyright (c) 2000, 2001, 2003-2005, 2008-2010, 2015, 2018 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 _SCDYNAMICSTORE_H
25#define _SCDYNAMICSTORE_H
26
27#include <os/availability.h>
28#include <TargetConditionals.h>
29#include <sys/cdefs.h>
30#include <dispatch/dispatch.h>
31#include <CoreFoundation/CoreFoundation.h>
32
33CF_IMPLICIT_BRIDGING_ENABLED
34CF_ASSUME_NONNULL_BEGIN
35
36/*!
37 @header SCDynamicStore
38 @discussion The SCDynamicStore API provides access to the key-value
39 pairs in the dynamic store of a running system. The dynamic
40 store contains, among other items, a copy of the configuration
41 settings for the currently active set (which is sometimes
42 refered to as the location) and information about the current
43 network state.
44
45 The functions in the SCDynamicStore API allow you to find
46 key-value pairs, add or remove key-value pairs, add or change
47 values, and request notifications.
48
49 To use the functions of the SCDynamicStore API, you must first
50 establish a dynamic store session using the SCDynamicStoreCreate
51 function. When you are finished with the session, use CFRelease
52 to close it.
53 */
54
55
56/*!
57 @typedef SCDynamicStoreRef
58 @discussion This is the handle to an open a dynamic store session
59 with the system configuration daemon.
60 */
61typedef const struct CF_BRIDGED_TYPE(id) __SCDynamicStore * SCDynamicStoreRef;
62
63/*!
64 @typedef SCDynamicStoreContext
65 Structure containing user-specified data and callbacks for an
66 SCDynamicStore session.
67 @field version The version number of the structure type being passed
68 in as a parameter to the SCDynamicStore creation function.
69 This structure is version 0.
70 @field info A C pointer to a user-specified block of data.
71 @field retain The callback used to add a retain for the info field.
72 If this parameter is not a pointer to a function of the correct
73 prototype, the behavior is undefined. The value may be NULL.
74 @field release The calllback used to remove a retain previously added
75 for the info field. If this parameter is not a pointer to a
76 function of the correct prototype, the behavior is undefined.
77 The value may be NULL.
78 @field copyDescription The callback used to provide a description of
79 the info field.
80 */
81typedef struct {
82 CFIndex version;
83 void * __nullable info;
84 const void * __nonnull (* __nullable retain)(const void *info);
85 void (* __nullable release)(const void *info);
86 CFStringRef __nonnull (* __nullable copyDescription)(const void *info);
87} SCDynamicStoreContext;
88
89/*!
90 @typedef SCDynamicStoreCallBack
91 @discussion Type of callback function used when notification of
92 changes to the dynamic store is delivered.
93 @param store The dynamic store session.
94 @param changedKeys The list of changed keys.
95
96 The list includes any specific SCDynamicStore keys that
97 changed (add, update, remove, notify) since the last call
98 to SCDynamicStoreSetNotificationKeys or since the last
99 notification callback. The list also includes any specific
100 keys matching one of the pattern string(s) that changed.
101
102 An empty list indicates that the SCDynamicStore server
103 restarted and that any assumptions based on prior content
104 of the SCDynamicStore should be disgarded.
105
106 @param info A C pointer to a user-specified block of data.
107 */
108typedef void (*SCDynamicStoreCallBack) (
109 SCDynamicStoreRef store,
110 CFArrayRef changedKeys,
111 void * __nullable info
112 );
113
114
115__BEGIN_DECLS
116
117/*!
118 @function SCDynamicStoreGetTypeID
119 @discussion Returns the type identifier of all SCDynamicStore instances.
120 */
121CFTypeID
122SCDynamicStoreGetTypeID (void) API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
123
124
125/*!
126 @function SCDynamicStoreCreate
127 @discussion Creates a new session used to interact with the dynamic
128 store maintained by the System Configuration server.
129 @param allocator The CFAllocator that should be used to allocate
130 memory for the local dynamic store object.
131 This parameter may be NULL in which case the current
132 default CFAllocator is used. If this reference is not
133 a valid CFAllocator, the behavior is undefined.
134 @param name A string that describes the name of the calling
135 process or plug-in of the caller.
136 @param callout The function to be called when a watched value
137 in the dynamic store is changed.
138 A NULL value can be specified if no callouts are
139 desired.
140 @param context The SCDynamicStoreContext associated with the callout.
141 @result Returns a reference to the new SCDynamicStore session.
142 You must release the returned value.
143 */
144SCDynamicStoreRef __nullable
145SCDynamicStoreCreate (
146 CFAllocatorRef __nullable allocator,
147 CFStringRef name,
148 SCDynamicStoreCallBack __nullable callout,
149 SCDynamicStoreContext * __nullable context
150 ) API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
151
152/*!
153 @function SCDynamicStoreCreateWithOptions
154 @discussion Creates a new session used to interact with the dynamic
155 store maintained by the System Configuration server.
156 @param allocator The CFAllocator that should be used to allocate
157 memory for the local dynamic store object.
158 This parameter may be NULL in which case the current
159 default CFAllocator is used. If this reference is not
160 a valid CFAllocator, the behavior is undefined.
161 @param name A string that describes the name of the calling
162 process or plug-in of the caller.
163 @param storeOptions A CFDictionary containing options for the
164 dynamic store session (such as whether all keys added or set
165 into the dynamic store should be per-session keys).
166
167 Currently available options include:
168
169 <TABLE BORDER>
170 <TR>
171 <TH>key</TD>
172 <TH>value</TD>
173 </TR>
174 <TR>
175 <TD>kSCDynamicStoreUseSessionKeys</TD>
176 <TD>CFBooleanRef</TD>
177 </TR>
178 </TABLE>
179
180 A NULL value can be specified if no options are desired.
181 @param callout The function to be called when a watched value
182 in the dynamic store is changed.
183 A NULL value can be specified if no callouts are
184 desired.
185 @param context The SCDynamicStoreContext associated with the callout.
186 @result Returns a reference to the new SCDynamicStore session.
187 You must release the returned value.
188 */
189SCDynamicStoreRef __nullable
190SCDynamicStoreCreateWithOptions (
191 CFAllocatorRef __nullable allocator,
192 CFStringRef name,
193 CFDictionaryRef __nullable storeOptions,
194 SCDynamicStoreCallBack __nullable callout,
195 SCDynamicStoreContext * __nullable context
196 ) API_AVAILABLE(macos(10.4)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
197
198extern const CFStringRef kSCDynamicStoreUseSessionKeys API_AVAILABLE(macos(10.4)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0)); /* CFBoolean */
199
200/*!
201 @function SCDynamicStoreCreateRunLoopSource
202 @discussion Creates a CFRunLoopSource object that can be added to the
203 application's run loop. All dynamic store notifications are
204 delivered using this run loop source.
205 @param allocator The CFAllocator that should be used to allocate
206 memory for this run loop source.
207 This parameter may be NULL in which case the current
208 default CFAllocator is used. If this reference is not
209 a valid CFAllocator, the behavior is undefined.
210 @param store A reference to the dynamic store session.
211 @param order On platforms which support it, for source versions
212 which support it, this parameter determines the order in
213 which the sources which are ready to be processed are
214 handled. A lower order number causes processing before
215 higher order number sources. It is inadvisable to depend
216 on the order number for any architectural or design aspect
217 of code. In the absence of any reason to do otherwise,
218 zero should be used.
219 @result A reference to the new CFRunLoopSource.
220 You must release the returned value.
221
222 */
223CFRunLoopSourceRef __nullable
224SCDynamicStoreCreateRunLoopSource (
225 CFAllocatorRef __nullable allocator,
226 SCDynamicStoreRef store,
227 CFIndex order
228 ) API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
229
230/*!
231 @function SCDynamicStoreSetDispatchQueue
232 @discussion Initiates notifications for the Notification
233 Keys in store to the callback contained in store.
234 @param store A reference to the dynamic store session.
235 @param queue The dispatch queue to run the callback function on.
236 Pass NULL to disable notifications, and release the queue.
237 @result Returns TRUE on success, FALSE on failure.
238
239 */
240Boolean
241SCDynamicStoreSetDispatchQueue (
242 SCDynamicStoreRef store,
243 dispatch_queue_t __nullable queue
244 ) API_AVAILABLE(macos(10.6)) SPI_AVAILABLE(ios(4.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
245
246/*!
247 @function SCDynamicStoreCopyKeyList
248 @discussion Returns an array of CFString keys representing the
249 current dynamic store entries that match a specified pattern.
250 @param store The dynamic store session.
251 @param pattern A regex(3) regular expression pattern
252 used to match the dynamic store keys.
253 @result Returns the list of matching keys; NULL if an error was
254 encountered.
255 You must release the returned value.
256 */
257CFArrayRef __nullable
258SCDynamicStoreCopyKeyList (
259 SCDynamicStoreRef __nullable store,
260 CFStringRef pattern
261 ) API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
262
263/*!
264 @function SCDynamicStoreAddValue
265 @discussion Adds the key-value pair to the dynamic store if no
266 such key already exists.
267 @param store The dynamic store session.
268 @param key The key of the value to add to the dynamic store.
269 @param value The value to add to the dynamic store.
270 @result Returns TRUE if the key was added; FALSE if the key was already
271 present in the dynamic store or if an error was encountered.
272 */
273Boolean
274SCDynamicStoreAddValue (
275 SCDynamicStoreRef __nullable store,
276 CFStringRef key,
277 CFPropertyListRef value
278 ) API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
279
280/*!
281 @function SCDynamicStoreAddTemporaryValue
282 @discussion Temporarily adds the key-value pair to the dynamic store
283 if no such key already exists. Unless the key is updated by another
284 session, the key-value pair will be removed automatically when the
285 session is closed.
286 @param store The dynamic store session.
287 @param key The key of the value to add to the dynamic store.
288 @param value The value to add to the dynamic store.
289 @result Returns TRUE if the key was added; FALSE if the key was already
290 present in the dynamic store or if an error was encountered.
291 */
292Boolean
293SCDynamicStoreAddTemporaryValue (
294 SCDynamicStoreRef store,
295 CFStringRef key,
296 CFPropertyListRef value
297 ) API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
298
299/*!
300 @function SCDynamicStoreCopyValue
301 @discussion Gets the value of the specified key from the dynamic store.
302 @param store The dynamic store session.
303 @param key The key associated with the value you want to get.
304 @result Returns the value from the dynamic store that is associated with the given
305 key; NULL if no value was located or an error was encountered.
306 You must release the returned value.
307 */
308CFPropertyListRef __nullable
309SCDynamicStoreCopyValue (
310 SCDynamicStoreRef __nullable store,
311 CFStringRef key
312 ) API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
313
314/*!
315 @function SCDynamicStoreCopyMultiple
316 @discussion Gets the values of multiple keys in the dynamic store.
317 @param store The dynamic store session.
318 @param keys The keys associated with the values you want to get; NULL if no specific
319 keys are requested.
320 @param patterns An array of regex(3) pattern strings used to match the keys; NULL
321 if no key patterns are requested.
322 @result Returns a dictionary containing the key-value pairs of specific keys and the
323 key-value pairs of keys that matched the specified patterns;
324 NULL if an error was encountered.
325 You must release the returned value.
326 */
327CFDictionaryRef __nullable
328SCDynamicStoreCopyMultiple (
329 SCDynamicStoreRef __nullable store,
330 CFArrayRef __nullable keys,
331 CFArrayRef __nullable patterns
332 ) API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
333
334/*!
335 @function SCDynamicStoreSetValue
336 @discussion Adds or replaces a value in the dynamic store for
337 the specified key.
338 @param store The dynamic store session.
339 @param key The key you want to set.
340 @param value The value to add to or replace in the dynamic store.
341 @result Returns TRUE if the key was updated; FALSE if an error was encountered.
342 */
343Boolean
344SCDynamicStoreSetValue (
345 SCDynamicStoreRef __nullable store,
346 CFStringRef key,
347 CFPropertyListRef value
348 ) API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
349
350/*!
351 @function SCDynamicStoreSetMultiple
352 @discussion Updates multiple values in the dynamic store.
353 @param store The dynamic store session.
354 @param keysToSet A dictionary of key-value pairs you want to set into the dynamic store.
355 @param keysToRemove An array of keys you want to remove from the dynamic store.
356 @param keysToNotify An array of keys to flag as changed (without changing their values).
357 @result Returns TRUE if the dynamic store updates were successful; FALSE if an error was encountered.
358 */
359Boolean
360SCDynamicStoreSetMultiple (
361 SCDynamicStoreRef __nullable store,
362 CFDictionaryRef __nullable keysToSet,
363 CFArrayRef __nullable keysToRemove,
364 CFArrayRef __nullable keysToNotify
365 ) API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
366
367/*!
368 @function SCDynamicStoreRemoveValue
369 @discussion Removes the value of the specified key from the
370 dynamic store.
371 @param store The dynamic store session.
372 @param key The key of the value you want to remove.
373 @result Returns TRUE if the key was removed; FALSE if no value was
374 located or an error was encountered.
375 */
376Boolean
377SCDynamicStoreRemoveValue (
378 SCDynamicStoreRef __nullable store,
379 CFStringRef key
380 ) API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
381
382/*!
383 @function SCDynamicStoreNotifyValue
384 @discussion Triggers a notification to be delivered for the
385 specified key in the dynamic store.
386 @param store The dynamic store session.
387 @param key The key that should be flagged as changed. Any dynamic store sessions
388 that are monitoring this key will received a notification. Note that the
389 key's value is not updated.
390 @result Returns TRUE if the notification was processed; FALSE if an error was encountered.
391 */
392Boolean
393SCDynamicStoreNotifyValue (
394 SCDynamicStoreRef __nullable store,
395 CFStringRef key
396 ) API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
397
398/*!
399 @function SCDynamicStoreSetNotificationKeys
400 @discussion Specifies a set of specific keys and key patterns
401 that should be monitored for changes.
402 @param store The dynamic store session being watched.
403 @param keys An array of keys to be monitored; NULL if no specific keys
404 are to be monitored.
405 @param patterns An array of regex(3) pattern strings used to match keys to be monitored;
406 NULL if no key patterns are to be monitored.
407 @result Returns TRUE if the set of notification keys and patterns was successfully
408 updated; FALSE if an error was encountered.
409 */
410Boolean
411SCDynamicStoreSetNotificationKeys (
412 SCDynamicStoreRef store,
413 CFArrayRef __nullable keys,
414 CFArrayRef __nullable patterns
415 ) API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
416
417/*!
418 @function SCDynamicStoreCopyNotifiedKeys
419 @discussion Returns an array of CFString keys representing the
420 dynamic store entries that have changed since this
421 function was last called. If possible, your application should
422 use the notification functions instead of polling for the list
423 of changed keys returned by this function.
424 @param store The dynamic store session.
425 @result Returns the list of changed keys;
426 NULL if an error was encountered.
427 You must release the returned value.
428 */
429CFArrayRef __nullable
430SCDynamicStoreCopyNotifiedKeys (
431 SCDynamicStoreRef store
432 ) API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
433
434__END_DECLS
435
436CF_ASSUME_NONNULL_END
437CF_IMPLICIT_BRIDGING_DISABLED
438
439#endif /* _SCDYNAMICSTORE_H */