SystemConfiguration.fproj/SCPreferences.h

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