SystemConfiguration.fproj/SCPreferencesPath.h

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