SystemConfiguration.fproj/SCPreferencesPath.h

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