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