SystemConfiguration.fproj/SCPreferencesPath.h

   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  */
  93 CFStringRef
  94 SCPreferencesPathCreateUniqueChild      (
  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  */
 108 CFDictionaryRef
 109 SCPreferencesPathGetValue               (
 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  */
 123 CFStringRef
 124 SCPreferencesPathGetLink                (
 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  */
 138 Boolean
 139 SCPreferencesPathSetValue               (
 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  */
 155 Boolean
 156 SCPreferencesPathSetLink                (
 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  */
 169 Boolean
 170 SCPreferencesPathRemoveValue            (
 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 */