SystemConfiguration.fproj/SCPreferences.h

   1 /*
   2  * Copyright (c) 2000, 2001, 2004, 2005 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 #include <AvailabilityMacros.h>
  28 #include <sys/cdefs.h>
  29 #include <CoreFoundation/CoreFoundation.h>
  30 #include <SystemConfiguration/SCDynamicStore.h>
  31
  32
  33 /*!
  34         @header SCPreferences
  35         @discussion The SCPreferences API allows 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                 To access configuration preferences, you must first establish a
  41                 preferences session using the SCPreferencesCreate function.
  42                 To identify a specific set of preferences to access, you pass a
  43                 value in the prefsID parameter.
  44                 A NULL value indicates that the default system preferences are
  45                 to be accessed.
  46                 A string that starts with a leading "/" character specifies
  47                 the absolute path to the file containing the preferences to
  48                 be accessed.
  49                 A string that does not start with a leading "/" character
  50                 specifies a file relative to the default system preferences
  51                 directory.
  52
  53                 When you are finished with the preferences session, use
  54                 CFRelease to close it.
  55  */
  56
  57
  58 /*!
  59         @typedef SCPreferencesRef
  60         @discussion This is the handle to an open preferences session for
  61                 accessing system configuration preferences.
  62  */
  63 typedef const struct __SCPreferences *  SCPreferencesRef;
  64
  65 #if MAC_OS_X_VERSION_MAX_ALLOWED >= 1040
  66
  67 /*!
  68         @enum SCPreferencesNotification
  69         @discussion Used with the SCPreferencesCallBack callback
  70                 to describe the type of notification.
  71         @constant kSCPreferencesNotificationCommit Indicates when new
  72                 preferences have been saved.
  73         @constant kSCPreferencesNotificationApply Key Indicates when a
  74                 request has been made to apply the currently saved
  75                 preferences to the active system configuration.
  76  */
  77 enum {
  78         kSCPreferencesNotificationCommit        = 1<<0,
  79         kSCPreferencesNotificationApply         = 1<<1
  80 };
  81 typedef uint32_t        SCPreferencesNotification;
  82
  83 /*!
  84         @typedef SCPreferencesContext
  85         Structure containing user-specified data and callbacks for SCPreferences.
  86         @field version The version number of the structure type being passed
  87                 in as a parameter to the SCPreferencesSetCallback function.
  88                 This structure is version 0.
  89         @field info A C pointer to a user-specified block of data.
  90         @field retain The callback used to add a retain for the info field.
  91                 If this parameter is not a pointer to a function of the correct
  92                 prototype, the behavior is undefined.
  93                 The value may be NULL.
  94         @field release The calllback used to remove a retain previously added
  95                 for the info field.
  96                 If this parameter is not a pointer to a function of the
  97                 correct prototype, the behavior is undefined.
  98                 The value may be NULL.
  99         @field copyDescription The callback used to provide a description of
 100                 the info field.
 101  */
 102 typedef struct {
 103         CFIndex         version;
 104         void *          info;
 105         const void      *(*retain)(const void *info);
 106         void            (*release)(const void *info);
 107         CFStringRef     (*copyDescription)(const void *info);
 108 } SCPreferencesContext;
 109
 110 /*!
 111         @typedef SCPreferencesCallBack
 112         @discussion Type of the callback function used when the
 113                 preferences have been updated and/or applied.
 114         @param prefs The preferences session.
 115         @param notificationType The type of notification, such as changes
 116                 committed, changes applied, etc.
 117         @param info A C pointer to a user-specified block of data.
 118  */
 119 typedef void (*SCPreferencesCallBack)   (
 120                                         SCPreferencesRef                prefs,
 121                                         SCPreferencesNotification       notificationType,
 122                                         void                            *info
 123                                         );
 124
 125 #endif  /* MAC_OS_X_VERSION_MAX_ALLOWED >= 1040 */
 126
 127
 128 __BEGIN_DECLS
 129
 130 /*!
 131         @function SCPreferencesGetTypeID
 132         @discussion Returns the type identifier of all SCPreferences instances.
 133  */
 134 CFTypeID
 135 SCPreferencesGetTypeID          (void);
 136
 137 /*!
 138         @function SCPreferencesCreate
 139         @discussion Initiates access to the per-system set of configuration
 140                 preferences.
 141         @param allocator The CFAllocator that should be used to allocate
 142                 memory for this preferences session.
 143                 This parameter may be NULL in which case the current
 144                 default CFAllocator is used.
 145                 If this reference is not a valid CFAllocator, the behavior
 146                 is undefined.
 147         @param name A string that describes the name of the calling
 148                 process.
 149         @param prefsID A string that identifies the name of the
 150                 group of preferences to be accessed or updated.
 151         @result Returns a reference to the new SCPreferences.
 152                 You must release the returned value.
 153  */
 154 SCPreferencesRef
 155 SCPreferencesCreate             (
 156                                 CFAllocatorRef          allocator,
 157                                 CFStringRef             name,
 158                                 CFStringRef             prefsID
 159                                 );
 160
 161 /*!
 162         @function SCPreferencesLock
 163         @discussion Locks access to the configuration preferences.
 164
 165                 This function obtains exclusive access to the configuration
 166                 preferences.  Clients attempting to obtain exclusive access
 167                 to the preferences will either receive a kSCStatusPrefsBusy
 168                 error or block waiting for the lock to be released.
 169         @param prefs The preferences session.
 170         @param wait A boolean flag indicating whether the calling process
 171                 should block waiting for another process to complete its update
 172                 operation and release its lock.
 173         @result Returns TRUE if the lock was obtained;
 174                 FALSE if an error occurred.
 175  */
 176 Boolean
 177 SCPreferencesLock               (
 178                                 SCPreferencesRef        prefs,
 179                                 Boolean                 wait
 180                                 );
 181
 182 /*!
 183         @function SCPreferencesCommitChanges
 184         @discussion Commits changes made to the configuration preferences to
 185                 persistent storage.
 186
 187                 This function commits any changes to permanent storage.
 188                 Implicit calls to the SCPreferencesLock and SCPreferencesUnlock
 189                 functions will be made if exclusive access has not already been
 190                 established.
 191
 192                 Note: This routine commits changes to persistent storage.
 193                 Call the SCPreferencesApplyChanges function to apply the
 194                 changes to the running system.
 195         @param prefs The preferences session.
 196         @result Returns TRUE if the lock was obtained;
 197                 FALSE if an error occurred.
 198  */
 199 Boolean
 200 SCPreferencesCommitChanges      (
 201                                 SCPreferencesRef        prefs
 202                                 );
 203
 204 /*!
 205         @function SCPreferencesApplyChanges
 206         @discussion Requests that the currently stored configuration
 207                 preferences be applied to the active configuration.
 208         @param prefs The preferences session.
 209         @result Returns TRUE if the lock was obtained;
 210                 FALSE if an error occurred.
 211  */
 212 Boolean
 213 SCPreferencesApplyChanges       (
 214                                 SCPreferencesRef        prefs
 215                                 );
 216
 217 /*!
 218         @function SCPreferencesUnlock
 219         @discussion Releases exclusive access to the configuration preferences.
 220
 221                 This function releases the exclusive access lock to the
 222                 preferences.  Other clients will be now be able to establish
 223                 exclusive access to the preferences.
 224         @param prefs The preferences session.
 225         @result Returns TRUE if the lock was obtained;
 226                 FALSE if an error occurred.
 227  */
 228 Boolean
 229 SCPreferencesUnlock             (
 230                                 SCPreferencesRef        prefs
 231                                 );
 232
 233 /*!
 234         @function SCPreferencesGetSignature
 235         @discussion Returns a sequence of bytes that can be used to determine
 236                 if the saved configuration preferences have changed.
 237         @param prefs The preferences session.
 238         @result Returns a CFDataRef that reflects the signature of the configuration
 239                 preferences at the time of the call to the SCPreferencesCreate function.
 240  */
 241 CFDataRef
 242 SCPreferencesGetSignature       (
 243                                 SCPreferencesRef        prefs
 244                                 );
 245
 246 /*!
 247         @function SCPreferencesCopyKeyList
 248         @discussion Returns an array of currently defined preference keys.
 249         @param prefs The preferences session.
 250         @result Returns the list of keys.
 251                 You must release the returned value.
 252  */
 253 CFArrayRef
 254 SCPreferencesCopyKeyList        (
 255                                 SCPreferencesRef        prefs
 256                                 );
 257
 258 /*!
 259         @function SCPreferencesGetValue
 260         @discussion Returns the data associated with a preference key.
 261
 262                 This function retrieves data associated with the specified
 263                 key.
 264
 265                 Note: To avoid inadvertantly reading stale data, first call
 266                 the SCPreferencesLock function.
 267         @param prefs The preferences session.
 268         @param key The preference key to be returned.
 269         @result Returns the value associated with the specified preference key;
 270                 NULL if no value was located.
 271  */
 272 CFPropertyListRef
 273 SCPreferencesGetValue           (
 274                                 SCPreferencesRef        prefs,
 275                                 CFStringRef             key
 276                                 );
 277
 278 /*!
 279         @function SCPreferencesAddValue
 280         @discussion Adds data for a preference key.
 281
 282                 This function associates new data with the specified key.
 283                 To commit these changes to permanent storage, a call must
 284                 be made to the SCPreferencesCommitChanges function.
 285         @param prefs The preferences session.
 286         @param key The preference key to be updated.
 287         @param value The CFPropertyListRef object containing the
 288                 value to be associated with the specified preference key.
 289         @result Returns TRUE if the value was added;
 290                 FALSE if the key already exists or
 291                 if an error occurred.
 292  */
 293 Boolean
 294 SCPreferencesAddValue           (
 295                                 SCPreferencesRef        prefs,
 296                                 CFStringRef             key,
 297                                 CFPropertyListRef       value
 298                                 );
 299
 300 /*!
 301         @function SCPreferencesSetValue
 302         @discussion Updates the data associated with a preference key.
 303
 304                 This function adds or replaces the value associated with the
 305                 specified key.  To commit these changes to permanent storage
 306                 a call must be made to the SCPreferencesCommitChanges function.
 307         @param prefs The preferences session.
 308         @param key The preference key to be updated.
 309         @param value The CFPropertyListRef object containing the
 310                 data to be associated with the specified preference key.
 311         @result Returns TRUE if the value was set;
 312                 FALSE if an error occurred.
 313  */
 314 Boolean
 315 SCPreferencesSetValue           (
 316                                 SCPreferencesRef        prefs,
 317                                 CFStringRef             key,
 318                                 CFPropertyListRef       value
 319                                 );
 320
 321 /*!
 322         @function SCPreferencesRemoveValue
 323         @discussion Removes the data associated with a preference key.
 324
 325                 This function removes the data associated with the specified
 326                 key.  To commit these changes to permanent storage a call must
 327                 be made to the SCPreferencesCommitChanges function.
 328         @param prefs The preferences session.
 329         @param key The preference key to be removed.
 330         @result Returns TRUE if the value was removed;
 331                 FALSE if the key did not exist or if an error occurred.
 332  */
 333 Boolean
 334 SCPreferencesRemoveValue        (
 335                                 SCPreferencesRef        prefs,
 336                                 CFStringRef             key
 337                                 );
 338
 339 #if MAC_OS_X_VERSION_MAX_ALLOWED >= 1040
 340
 341 /*!
 342         @function SCPreferencesSetCallback
 343         @discussion Assigns a callback to a preferences session.  The function
 344                 is called when the changes to the preferences have been
 345                 committed or applied.
 346         @param prefs The preferences session.
 347         @param callout The function to be called when the preferences have
 348                 been changed or applied.
 349                 If NULL, the current callback is removed.
 350         @param context The SCPreferencesContext associated with
 351                 the callout.
 352         @result Returns TRUE if the notification client was successfully set.
 353  */
 354 Boolean
 355 SCPreferencesSetCallback                (
 356                                         SCPreferencesRef        prefs,
 357                                         SCPreferencesCallBack   callout,
 358                                         SCPreferencesContext    *context
 359                                         )                               AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
 360
 361 /*!
 362         @function SCPreferencesScheduleWithRunLoop
 363         @discussion Schedule commit and apply notifications for the specified
 364                 preferences session using the specified run loop and mode.
 365         @param prefs The preferences session.
 366         @param runLoop A reference to a run loop on which the notification
 367                 should be scheduled.
 368                 Must be non-NULL.
 369         @param runLoopMode The mode on which to schedule the notification.
 370                 Must be non-NULL.
 371         @result Returns TRUE if the notifications are successfully scheduled;
 372                 FALSE otherwise.
 373  */
 374 Boolean
 375 SCPreferencesScheduleWithRunLoop        (
 376                                         SCPreferencesRef        prefs,
 377                                         CFRunLoopRef            runLoop,
 378                                         CFStringRef             runLoopMode
 379                                         )                               AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
 380
 381 /*!
 382         @function SCPreferencesUnscheduleFromRunLoop
 383         @discussion Unschedule commit and apply notifications for the specified
 384                 preferences session from the specified run loop and mode.
 385         @param prefs The preferences session.
 386         @param runLoop A reference to a run loop from which the notification
 387                 should be unscheduled.
 388                 Must be non-NULL.
 389         @param runLoopMode The mode on which to unschedule the notification.
 390                 Must be non-NULL.
 391         @result Returns TRUE if the notifications are successfully unscheduled;
 392                 FALSE otherwise.
 393  */
 394 Boolean
 395 SCPreferencesUnscheduleFromRunLoop      (
 396                                         SCPreferencesRef        prefs,
 397                                         CFRunLoopRef            runLoop,
 398                                         CFStringRef             runLoopMode
 399                                         )                               AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
 400
 401 /*!
 402         @function SCPreferencesSynchronize
 403         @discussion Synchronizes accessed preferences with committed changes.
 404
 405                 Any references to preference values returned by calls to the
 406                 SCPreferencesGetValue function are no longer valid unless they
 407                 were explicitly retained or copied.  Any preference values
 408                 that were updated (add, set, remove) but not committed will
 409                 be discarded.
 410         @param prefs The preferences session.
 411  */
 412 void
 413 SCPreferencesSynchronize                (
 414                                         SCPreferencesRef        prefs
 415                                         )                               AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
 416
 417 #endif  /* MAC_OS_X_VERSION_MAX_ALLOWED >= 1040 */
 418
 419 __END_DECLS
 420
 421 #endif /* _SCPREFERENCES_H */