SystemConfiguration.fproj/SCPreferencesPath.h

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