SystemConfiguration.fproj/SCPreferences.h

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