SystemConfiguration.fproj/SCPreferencesPath.h

   1 /*
   2  * Copyright (c) 2000-2003 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         The SCPreferencesPathXXX() APIs allow 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 SCPreferencesPathXXX() APIs make certain assumptions
  41         about the layout of the preferences data.  These APIs view
  42         the data as a collection of dictionaries of key/value pairs
  43         and an associated path name.  The root path ("/") identifies
  44         the top-level dictionary.  Additional path components
  45         specify the keys for sub-dictionaries.
  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         <BR>    &lt;dict&gt;
  54         <BR>        &lt;key&gt;key1&lt;/key&gt;
  55         <BR>        &lt;string&gt;val1&lt;/string&gt;
  56         <BR>        &lt;key&gt;key2&lt;/key&gt;
  57         <BR>        &lt;string&gt;val2&lt;/string&gt;
  58         <BR>        &lt;key&gt;path1&lt;/key&gt;
  59         <BR>        &lt;dict&gt;
  60         <BR>            &lt;key&gt;key3&lt;/key&gt;
  61         <BR>            &lt;string&gt;val3&lt;/string&gt;
  62         <BR>        &lt;key&gt;key4&lt;/key&gt;
  63         <BR>        &lt;string&gt;val4&lt;/string&gt;
  64         <BR>        &lt;/dict&gt;
  65         <BR>    &lt;/dict&gt;
  66         </PRE>
  67
  68         Each dictionary can also include the kSCResvLink key.  The
  69         value associated with this key is interpreted as a "link" to
  70         another path.  If this key is present, a call to the
  71         SCPreferencesPathGetValue() API will return the dictionary
  72         specified by the link.
  73  */
  74
  75
  76 __BEGIN_DECLS
  77
  78 /*!
  79         @function SCPreferencesPathCreateUniqueChild
  80         @discussion Creates a new path component within the dictionary
  81                 hierarchy.
  82         @param session The SCPreferencesRef handle that should be used to
  83          communicate with the APIs.
  84         @param prefix A string that represents the parent path.
  85         @result A string representing the new (unique) child path; NULL
  86                 if the specified path does not exist.
  87  */
  88 CFStringRef
  89 SCPreferencesPathCreateUniqueChild      (
  90                                         SCPreferencesRef        session,
  91                                         CFStringRef             prefix
  92                                         );
  93
  94 /*!
  95         @function SCPreferencesPathGetValue
  96         @discussion Returns the dictionary associated with the specified
  97                 path.
  98         @param session The SCPreferencesRef handle that should be used to
  99                 communicate with the APIs.
 100         @param path A string that represents the path to be returned.
 101         @result The dictionary associated with the specified path; NULL
 102                 if the path does not exist.
 103  */
 104 CFDictionaryRef
 105 SCPreferencesPathGetValue               (
 106                                         SCPreferencesRef        session,
 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 session The SCPreferencesRef handle that should be used to
 115          communicate with the APIs.
 116         @param path A string that represents the path to be returned.
 117         @result The dictionary associated with the specified path; NULL
 118                 if the path is not a link or does not exist.
 119  */
 120 CFStringRef
 121 SCPreferencesPathGetLink                (
 122                                         SCPreferencesRef        session,
 123                                         CFStringRef             path
 124                                         );
 125
 126 /*!
 127         @function SCPreferencesPathSetValue
 128         @discussion Associates a dictionary with the specified path.
 129         @param session The SCPreferencesRef handle that should be used to
 130          communicate with the APIs.
 131         @param path A string that represents the path to be updated.
 132         @param value A dictionary that represents the data to be
 133                 stored at the specified path.
 134         @result A boolean indicating the success (or failure) of the call.
 135  */
 136 Boolean
 137 SCPreferencesPathSetValue               (
 138                                         SCPreferencesRef        session,
 139                                         CFStringRef             path,
 140                                         CFDictionaryRef         value
 141                                         );
 142
 143 /*!
 144         @function SCPreferencesPathSetLink
 145         @discussion Associates a link to a second dictionary at the
 146                 specified path.
 147         @param session The SCPreferencesRef handle that should be used to
 148                 communicate with the APIs.
 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 A boolean indicating the success (or failure) of the call.
 153  */
 154 Boolean
 155 SCPreferencesPathSetLink                (
 156                                         SCPreferencesRef        session,
 157                                         CFStringRef             path,
 158                                         CFStringRef             link
 159                                         );
 160
 161 /*!
 162         @function SCPreferencesPathRemoveValue
 163         @discussion Removes the data associated with the specified path.
 164         @param session The SCPreferencesRef handle that should be used to
 165          communicate with the APIs.
 166         @param path A string that represents the path to be returned.
 167         @result A boolean indicating the success (or failure) of the call.
 168  */
 169 Boolean
 170 SCPreferencesPathRemoveValue            (
 171                                         SCPreferencesRef        session,
 172                                         CFStringRef             path
 173                                         );
 174
 175 __END_DECLS
 176
 177 #endif /* _SCPREFERENCESPATH_H */