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 #include <Security/Security.h>
  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 #if MAC_OS_X_VERSION_MAX_ALLOWED >= 1050
 162
 163 /*!
 164         @function SCPreferencesCreateWithAuthorization
 165         @discussion Initiates access to the per-system set of configuration
 166                 preferences.
 167         @param allocator The CFAllocator that should be used to allocate
 168                 memory for this preferences session.
 169                 This parameter may be NULL in which case the current
 170                 default CFAllocator is used.
 171                 If this reference is not a valid CFAllocator, the behavior
 172                 is undefined.
 173         @param name A string that describes the name of the calling
 174                 process.
 175         @param prefsID A string that identifies the name of the
 176                 group of preferences to be accessed or updated.
 177         @param authorization An authorization reference that is used to
 178                 authorize any access to the enhanced privileges needed
 179                 to manage the preferences session.
 180         @result Returns a reference to the new SCPreferences.
 181                 You must release the returned value.
 182  */
 183 SCPreferencesRef
 184 SCPreferencesCreateWithAuthorization    (
 185                                         CFAllocatorRef          allocator,
 186                                         CFStringRef             name,
 187                                         CFStringRef             prefsID,
 188                                         AuthorizationRef        authorization
 189                                         )                               AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
 190
 191 #endif  /* MAC_OS_X_VERSION_MAX_ALLOWED >= 1050 */
 192
 193 /*!
 194         @function SCPreferencesLock
 195         @discussion Locks access to the configuration preferences.
 196
 197                 This function obtains exclusive access to the configuration
 198                 preferences.  Clients attempting to obtain exclusive access
 199                 to the preferences will either receive a kSCStatusPrefsBusy
 200                 error or block waiting for the lock to be released.
 201         @param prefs The preferences session.
 202         @param wait A boolean flag indicating whether the calling process
 203                 should block waiting for another process to complete its update
 204                 operation and release its lock.
 205         @result Returns TRUE if the lock was obtained;
 206                 FALSE if an error occurred.
 207  */
 208 Boolean
 209 SCPreferencesLock               (
 210                                 SCPreferencesRef        prefs,
 211                                 Boolean                 wait
 212                                 );
 213
 214 /*!
 215         @function SCPreferencesCommitChanges
 216         @discussion Commits changes made to the configuration preferences to
 217                 persistent storage.
 218
 219                 This function commits any changes to permanent storage.
 220                 Implicit calls to the SCPreferencesLock and SCPreferencesUnlock
 221                 functions will be made if exclusive access has not already been
 222                 established.
 223
 224                 Note: This routine commits changes to persistent storage.
 225                 Call the SCPreferencesApplyChanges function to apply the
 226                 changes to the running system.
 227         @param prefs The preferences session.
 228         @result Returns TRUE if the lock was obtained;
 229                 FALSE if an error occurred.
 230  */
 231 Boolean
 232 SCPreferencesCommitChanges      (
 233                                 SCPreferencesRef        prefs
 234                                 );
 235
 236 /*!
 237         @function SCPreferencesApplyChanges
 238         @discussion Requests that the currently stored configuration
 239                 preferences be applied to the active configuration.
 240         @param prefs The preferences session.
 241         @result Returns TRUE if the lock was obtained;
 242                 FALSE if an error occurred.
 243  */
 244 Boolean
 245 SCPreferencesApplyChanges       (
 246                                 SCPreferencesRef        prefs
 247                                 );
 248
 249 /*!
 250         @function SCPreferencesUnlock
 251         @discussion Releases exclusive access to the configuration preferences.
 252
 253                 This function releases the exclusive access lock to the
 254                 preferences.  Other clients will be now be able to establish
 255                 exclusive access to the preferences.
 256         @param prefs The preferences session.
 257         @result Returns TRUE if the lock was obtained;
 258                 FALSE if an error occurred.
 259  */
 260 Boolean
 261 SCPreferencesUnlock             (
 262                                 SCPreferencesRef        prefs
 263                                 );
 264
 265 /*!
 266         @function SCPreferencesGetSignature
 267         @discussion Returns a sequence of bytes that can be used to determine
 268                 if the saved configuration preferences have changed.
 269         @param prefs The preferences session.
 270         @result Returns a CFDataRef that reflects the signature of the configuration
 271                 preferences at the time of the call to the SCPreferencesCreate function.
 272  */
 273 CFDataRef
 274 SCPreferencesGetSignature       (
 275                                 SCPreferencesRef        prefs
 276                                 );
 277
 278 /*!
 279         @function SCPreferencesCopyKeyList
 280         @discussion Returns an array of currently defined preference keys.
 281         @param prefs The preferences session.
 282         @result Returns the list of keys.
 283                 You must release the returned value.
 284  */
 285 CFArrayRef
 286 SCPreferencesCopyKeyList        (
 287                                 SCPreferencesRef        prefs
 288                                 );
 289
 290 /*!
 291         @function SCPreferencesGetValue
 292         @discussion Returns the data associated with a preference key.
 293
 294                 This function retrieves data associated with the specified
 295                 key.
 296
 297                 Note: To avoid inadvertantly reading stale data, first call
 298                 the SCPreferencesLock function.
 299         @param prefs The preferences session.
 300         @param key The preference key to be returned.
 301         @result Returns the value associated with the specified preference key;
 302                 NULL if no value was located.
 303  */
 304 CFPropertyListRef
 305 SCPreferencesGetValue           (
 306                                 SCPreferencesRef        prefs,
 307                                 CFStringRef             key
 308                                 );
 309
 310 /*!
 311         @function SCPreferencesAddValue
 312         @discussion Adds data for a preference key.
 313
 314                 This function associates new data with the specified key.
 315                 To commit these changes to permanent storage, a call must
 316                 be made to the SCPreferencesCommitChanges function.
 317         @param prefs The preferences session.
 318         @param key The preference key to be updated.
 319         @param value The CFPropertyListRef object containing the
 320                 value to be associated with the specified preference key.
 321         @result Returns TRUE if the value was added;
 322                 FALSE if the key already exists or
 323                 if an error occurred.
 324  */
 325 Boolean
 326 SCPreferencesAddValue           (
 327                                 SCPreferencesRef        prefs,
 328                                 CFStringRef             key,
 329                                 CFPropertyListRef       value
 330                                 );
 331
 332 /*!
 333         @function SCPreferencesSetValue
 334         @discussion Updates the data associated with a preference key.
 335
 336                 This function adds or replaces the value associated with the
 337                 specified key.  To commit these changes to permanent storage
 338                 a call must be made to the SCPreferencesCommitChanges function.
 339         @param prefs The preferences session.
 340         @param key The preference key to be updated.
 341         @param value The CFPropertyListRef object containing the
 342                 data to be associated with the specified preference key.
 343         @result Returns TRUE if the value was set;
 344                 FALSE if an error occurred.
 345  */
 346 Boolean
 347 SCPreferencesSetValue           (
 348                                 SCPreferencesRef        prefs,
 349                                 CFStringRef             key,
 350                                 CFPropertyListRef       value
 351                                 );
 352
 353 /*!
 354         @function SCPreferencesRemoveValue
 355         @discussion Removes the data associated with a preference key.
 356
 357                 This function removes the data associated with the specified
 358                 key.  To commit these changes to permanent storage a call must
 359                 be made to the SCPreferencesCommitChanges function.
 360         @param prefs The preferences session.
 361         @param key The preference key to be removed.
 362         @result Returns TRUE if the value was removed;
 363                 FALSE if the key did not exist or if an error occurred.
 364  */
 365 Boolean
 366 SCPreferencesRemoveValue        (
 367                                 SCPreferencesRef        prefs,
 368                                 CFStringRef             key
 369                                 );
 370
 371 #if MAC_OS_X_VERSION_MAX_ALLOWED >= 1040
 372
 373 /*!
 374         @function SCPreferencesSetCallback
 375         @discussion Assigns a callback to a preferences session.  The function
 376                 is called when the changes to the preferences have been
 377                 committed or applied.
 378         @param prefs The preferences session.
 379         @param callout The function to be called when the preferences have
 380                 been changed or applied.
 381                 If NULL, the current callback is removed.
 382         @param context The SCPreferencesContext associated with
 383                 the callout.
 384         @result Returns TRUE if the notification client was successfully set.
 385  */
 386 Boolean
 387 SCPreferencesSetCallback                (
 388                                         SCPreferencesRef        prefs,
 389                                         SCPreferencesCallBack   callout,
 390                                         SCPreferencesContext    *context
 391                                         )                               AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
 392
 393 /*!
 394         @function SCPreferencesScheduleWithRunLoop
 395         @discussion Schedule commit and apply notifications for the specified
 396                 preferences session using the specified run loop and mode.
 397         @param prefs The preferences session.
 398         @param runLoop A reference to a run loop on which the notification
 399                 should be scheduled.
 400                 Must be non-NULL.
 401         @param runLoopMode The mode on which to schedule the notification.
 402                 Must be non-NULL.
 403         @result Returns TRUE if the notifications are successfully scheduled;
 404                 FALSE otherwise.
 405  */
 406 Boolean
 407 SCPreferencesScheduleWithRunLoop        (
 408                                         SCPreferencesRef        prefs,
 409                                         CFRunLoopRef            runLoop,
 410                                         CFStringRef             runLoopMode
 411                                         )                               AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
 412
 413 /*!
 414         @function SCPreferencesUnscheduleFromRunLoop
 415         @discussion Unschedule commit and apply notifications for the specified
 416                 preferences session from the specified run loop and mode.
 417         @param prefs The preferences session.
 418         @param runLoop A reference to a run loop from which the notification
 419                 should be unscheduled.
 420                 Must be non-NULL.
 421         @param runLoopMode The mode on which to unschedule the notification.
 422                 Must be non-NULL.
 423         @result Returns TRUE if the notifications are successfully unscheduled;
 424                 FALSE otherwise.
 425  */
 426 Boolean
 427 SCPreferencesUnscheduleFromRunLoop      (
 428                                         SCPreferencesRef        prefs,
 429                                         CFRunLoopRef            runLoop,
 430                                         CFStringRef             runLoopMode
 431                                         )                               AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
 432
 433 /*!
 434         @function SCPreferencesSynchronize
 435         @discussion Synchronizes accessed preferences with committed changes.
 436
 437                 Any references to preference values returned by calls to the
 438                 SCPreferencesGetValue function are no longer valid unless they
 439                 were explicitly retained or copied.  Any preference values
 440                 that were updated (add, set, remove) but not committed will
 441                 be discarded.
 442         @param prefs The preferences session.
 443  */
 444 void
 445 SCPreferencesSynchronize                (
 446                                         SCPreferencesRef        prefs
 447                                         )                               AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
 448
 449 #endif  /* MAC_OS_X_VERSION_MAX_ALLOWED >= 1040 */
 450
 451 __END_DECLS
 452
 453 #endif /* _SCPREFERENCES_H */