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