overby.me
this repo has no description
1/*
2 * Copyright (c) 2000, 2001, 2004, 2005, 2008, 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 _SCPREFERENCESPATH_H
25#define _SCPREFERENCESPATH_H
26
27#include <os/availability.h>
28#include <sys/cdefs.h>
29#include <CoreFoundation/CoreFoundation.h>
30#include <SystemConfiguration/SCPreferences.h>
31
32CF_IMPLICIT_BRIDGING_ENABLED
33CF_ASSUME_NONNULL_BEGIN
34
35/*!
36 @header SCPreferencesPath
37 @discussion The SCPreferencesPath API allows an application to
38 load and store XML configuration data in a controlled
39 manner and provide the necessary notifications to other
40 applications that need to be aware of configuration
41 changes.
42
43 The functions in the SCPreferencesPath API make certain
44 assumptions about the layout of the preferences data.
45 These functions view the data as a collection of dictionaries
46 of key-value pairs and an associated path name.
47 The root path ("/") identifies the top-level dictionary.
48 Additional path components specify the keys for subdictionaries.
49
50 For example, the following dictionary can be accessed via
51 two paths. The root ("/") path would return a dictionary
52 with all keys and values. The path "/path1" would only
53 return the dictionary with the "key3" and "key4" properties.
54
55 <pre>
56 @textblock
57 <dict>
58 <key>key1</key>
59 <string>val1</string>
60 <key>key2</key>
61 <string>val2</string>
62 <key>path1</key>
63 <dict>
64 <key>key3</key>
65 <string>val3</string>
66 <key>key4</key>
67 <string>val4</string>
68 </dict>
69 </dict>
70 @/textblock
71 </pre>
72
73 Each dictionary can also include the kSCResvLink ("__LINK__") key.
74 The value associated with this key is interpreted as a link to
75 another path. If this key is present, a call to the
76 SCPreferencesPathGetValue function returns the dictionary
77 specified by the link.
78 */
79
80
81__BEGIN_DECLS
82
83/*!
84 @function SCPreferencesPathCreateUniqueChild
85 @discussion Creates a new path component within the dictionary
86 hierarchy.
87 @param prefs The preferences session.
88 @param prefix A string that represents the parent path.
89 @result Returns a string representing the new (unique) child path; NULL
90 if the specified path does not exist.
91 */
92CFStringRef __nullable
93SCPreferencesPathCreateUniqueChild (
94 SCPreferencesRef prefs,
95 CFStringRef prefix
96 ) API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
97
98/*!
99 @function SCPreferencesPathGetValue
100 @discussion Returns the dictionary associated with the specified
101 path.
102 @param prefs The preferences session.
103 @param path A string that represents the path to be returned.
104 @result Returns the dictionary associated with the specified path; NULL
105 if the path does not exist.
106 */
107CFDictionaryRef __nullable
108SCPreferencesPathGetValue (
109 SCPreferencesRef prefs,
110 CFStringRef path
111 ) API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
112
113/*!
114 @function SCPreferencesPathGetLink
115 @discussion Returns the link (if one exists) associated with the
116 specified path.
117 @param prefs The preferences session.
118 @param path A string that represents the path to be returned.
119 @result Returns the dictionary associated with the specified path; NULL
120 if the path is not a link or does not exist.
121 */
122CFStringRef __nullable
123SCPreferencesPathGetLink (
124 SCPreferencesRef prefs,
125 CFStringRef path
126 ) API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
127
128/*!
129 @function SCPreferencesPathSetValue
130 @discussion Associates a dictionary with the specified path.
131 @param prefs The preferences session.
132 @param path A string that represents the path to be updated.
133 @param value A dictionary that represents the data to be
134 stored at the specified path.
135 @result Returns TRUE if successful; FALSE otherwise.
136 */
137Boolean
138SCPreferencesPathSetValue (
139 SCPreferencesRef prefs,
140 CFStringRef path,
141 CFDictionaryRef value
142 ) API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
143
144/*!
145 @function SCPreferencesPathSetLink
146 @discussion Associates a link to a second dictionary at the
147 specified path.
148 @param prefs The preferences session.
149 @param path A string that represents the path to be updated.
150 @param link A string that represents the link to be stored
151 at the specified path.
152 @result Returns TRUE if successful; FALSE otherwise.
153 */
154Boolean
155SCPreferencesPathSetLink (
156 SCPreferencesRef prefs,
157 CFStringRef path,
158 CFStringRef link
159 ) API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
160
161/*!
162 @function SCPreferencesPathRemoveValue
163 @discussion Removes the data associated with the specified path.
164 @param prefs The preferences session.
165 @param path A string that represents the path to be returned.
166 @result Returns TRUE if successful; FALSE otherwise.
167 */
168Boolean
169SCPreferencesPathRemoveValue (
170 SCPreferencesRef prefs,
171 CFStringRef path
172 ) API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
173
174__END_DECLS
175
176CF_ASSUME_NONNULL_END
177CF_IMPLICIT_BRIDGING_DISABLED
178
179#endif /* _SCPREFERENCESPATH_H */