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