SystemConfiguration.fproj/SCPreferences.h

   1 /*
   2  * Copyright (c) 2000-2003 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25
  26 #ifndef _SCPREFERENCES_H
  27 #define _SCPREFERENCES_H
  28
  29
  30 #include <sys/cdefs.h>
  31 #include <CoreFoundation/CoreFoundation.h>
  32 #include <SystemConfiguration/SCDynamicStore.h>
  33
  34
  35 /*!
  36         @header SCPreferences
  37         The SCPreferencesXXX() APIs allow an application to load and
  38         store XML configuration data in a controlled manner and provide
  39         the necessary notifications to other applications that need to
  40         be aware of configuration changes.
  41
  42         The stored XML configuration data is accessed using a prefsID. A
  43         NULL value indicates that the default system preferences are to
  44         be accessed.
  45         A string which starts with a leading "/" character specifies the
  46         path to the file containing te preferences to be accessed.
  47         A string which does not start with a leading "/" character
  48         specifies a file relative to the default system preferences
  49         directory.
  50  */
  51
  52
  53 /*!
  54         @typedef SCPreferencesRef
  55         @discussion This is the handle to an open "session" for
  56                 accessing system configuration preferences.
  57  */
  58 typedef const struct __SCPreferences *  SCPreferencesRef;
  59
  60
  61 __BEGIN_DECLS
  62
  63 /*!
  64         @function SCPreferencesGetTypeID
  65         Returns the type identifier of all SCPreferences instances.
  66  */
  67 CFTypeID
  68 SCPreferencesGetTypeID          (void);
  69
  70
  71 /*!
  72         @function SCPreferencesCreate
  73         @discussion Initiates access to the per-system set of configuration
  74                 preferences.
  75         @param allocator ...
  76         @param name A string that describes the name of the calling
  77                 process.
  78         @param prefsID A string that identifies the name of the
  79                 group of preferences to be accessed/updated.
  80         @result prefs A pointer to memory that will be filled with an
  81                 SCPreferencesRef handle to be used for all subsequent requests.
  82                 If a session cannot be established, the contents of
  83                 memory pointed to by this parameter are undefined.
  84  */
  85 SCPreferencesRef
  86 SCPreferencesCreate             (
  87                                 CFAllocatorRef          allocator,
  88                                 CFStringRef             name,
  89                                 CFStringRef             prefsID
  90                                 );
  91
  92 /*!
  93         @function SCPreferencesLock
  94         @discussion Locks access to the configuration preferences.
  95
  96         This function obtains exclusive access to the configuration
  97         preferences associated with this prefsID. Clients attempting
  98         to obtain exclusive access to the preferences will either receive
  99         an kSCStatusPrefsBusy error or block waiting for the lock to be
 100         released.
 101         @param session An SCPreferencesRef handle that should be used for
 102                 all API calls.
 103         @param wait A boolean flag indicating whether the calling process
 104                 should block waiting for another process to complete its update
 105                 operation and release its lock.
 106         @result TRUE if the lock was obtained; FALSE if an error occurred.
 107  */
 108 Boolean
 109 SCPreferencesLock               (
 110                                 SCPreferencesRef        session,
 111                                 Boolean                 wait
 112                                 );
 113
 114 /*!
 115         @function SCPreferencesCommitChanges
 116         @discussion Commits changes made to the configuration preferences to
 117                 persitent storage.
 118
 119                 This function commits any changes to permanent storage. An
 120                 implicit call to SCPreferencesLock/SCPreferencesUnlock will
 121                 be made if exclusive access has not already been established.
 122
 123                 Note:  This routine commits changes to persistent storage.
 124                 Call SCPreferencesApplyChanges() to apply the changes
 125                 to the running system.
 126         @param session An SCPreferencesRef handle that should be used for
 127                 all API calls.
 128         @result TRUE if the lock was obtained; FALSE if an error occurred.
 129  */
 130 Boolean
 131 SCPreferencesCommitChanges      (
 132                                 SCPreferencesRef        session
 133                                 );
 134
 135 /*!
 136         @function SCPreferencesApplyChanges
 137         @discussion Requests that the currently stored configuration
 138                 preferences be applied to the active configuration.
 139         @param session An SCPreferencesRef handle that should be used for
 140                 all API calls.
 141         @result TRUE if the lock was obtained; FALSE if an error occurred.
 142  */
 143 Boolean
 144 SCPreferencesApplyChanges       (
 145                                 SCPreferencesRef        session
 146                                 );
 147
 148 /*!
 149         @function SCPreferencesUnlock
 150         @discussion Releases exclusive access to the configuration preferences.
 151
 152                 This function releases the exclusive access "lock" for this prefsID.
 153                 Other clients will be now be able to establish exclusive access to
 154                 the preferences.
 155         @param session An SCPreferencesRef handle that should be used for
 156                 all API calls.
 157         @result TRUE if the lock was obtained; FALSE if an error occurred.
 158  */
 159 Boolean
 160 SCPreferencesUnlock             (
 161                                 SCPreferencesRef        session
 162                                 );
 163
 164 /*!
 165         @function SCPreferencesGetSignature
 166         @discussion Returns a sequence of bytes that can be used to determine
 167                 if the saved configuration preferences have changed.
 168         @param session An SCPreferencesRef handle that should be used for
 169                 all API calls.
 170         @param signature A pointer to a CFDataRef that will reflect
 171                 the signature of the configuration preferences at the time
 172                 of the call to SCPreferencesCreate().
 173         @result A CFDataRef that reflects the signature of the configuration
 174                 preferences at the time of the call to SCPreferencesCreate().
 175  */
 176 CFDataRef
 177 SCPreferencesGetSignature       (
 178                                 SCPreferencesRef        session
 179                                 );
 180
 181 /*!
 182         @function SCPreferencesCopyKeyList
 183         @discussion Returns an array of currently defined preference keys.
 184         @param session An SCPreferencesRef handle that should be used for
 185                 all API calls.
 186         @result The list of keys.  You must release the returned value.
 187  */
 188 CFArrayRef
 189 SCPreferencesCopyKeyList        (
 190                                 SCPreferencesRef        session
 191                                 );
 192
 193 /*!
 194         @function SCPreferencesGetValue
 195         @discussion Returns the data associated with a preference key.
 196
 197                 This function retrieves data associated with a key for the prefsID.
 198
 199                 Note:  You could read stale data and not know it, unless you
 200                 first call SCPreferencesLock().
 201         @param session An SCPreferencesRef handle that should be used for
 202                 all API calls.
 203         @param key The preference key to be returned.
 204         @result The value associated with the specified preference key; If no
 205                 value was located, NULL is returned.
 206  */
 207 CFPropertyListRef
 208 SCPreferencesGetValue           (
 209                                 SCPreferencesRef        session,
 210                                 CFStringRef             key
 211                                 );
 212
 213 /*!
 214         @function SCPreferencesAddValue
 215         @discussion Adds data for a preference key.
 216
 217         This function associates new data with the specified key. In order
 218         to commit these changes to permanent storage a call must be made to
 219         SCPreferencesCommitChanges().
 220         @param session The SCPreferencesRef handle that should be used to
 221                 communicate with the APIs.
 222         @param key The preference key to be updated.
 223         @param value The CFPropertyListRef object containing the
 224                 value to be associated with the specified preference key.
 225         @result TRUE if the value was added; FALSE if the key already exists or
 226                 if an error occurred.
 227  */
 228 Boolean
 229 SCPreferencesAddValue           (
 230                                 SCPreferencesRef        session,
 231                                 CFStringRef             key,
 232                                 CFPropertyListRef       value
 233                                 );
 234
 235 /*!
 236         @function SCPreferencesSetValue
 237         @discussion Updates the data associated with a preference key.
 238
 239         This function adds or replaces the value associated with the
 240         specified key. In order to commit these changes to permanent
 241         storage a call must be made to SCPreferencesCommitChanges().
 242         @param session The SCPreferencesRef handle that should be used to
 243                 communicate with the APIs.
 244         @param key The preference key to be updated.
 245         @param value The CFPropertyListRef object containing the
 246                 data to be associated with the specified preference key.
 247         @result TRUE if the value was set; FALSE if an error occurred.
 248  */
 249 Boolean
 250 SCPreferencesSetValue           (
 251                                 SCPreferencesRef        session,
 252                                 CFStringRef             key,
 253                                 CFPropertyListRef       value
 254                                 );
 255
 256 /*!
 257         @function SCPreferencesRemoveValue
 258         @discussion Removes the data associated with a preference key.
 259
 260         This function removes the data associated with the specified
 261         key. In order to commit these changes to permanent storage a
 262         call must be made to SCPreferencesCommitChanges().
 263         @param session The SCPreferencesRef handle that should be used to
 264                 communicate with the APIs.
 265         @param key The preference key to be removed.
 266         @result TRUE if the value was removed; FALSE if the key did not exist or
 267                 if an error occurred.
 268  */
 269 Boolean
 270 SCPreferencesRemoveValue        (
 271                                 SCPreferencesRef        session,
 272                                 CFStringRef             key
 273                                 );
 274
 275 __END_DECLS
 276
 277 #endif /* _SCPREFERENCES_H */