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