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 40typedef 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 */ 74typedef 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 */ 86enum { 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 91typedef 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 */ 112typedef 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 */ 129typedef 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 */ 142CFTypeID 143SCPreferencesGetTypeID (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 */ 162SCPreferencesRef 163SCPreferencesCreate ( 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 */ 190SCPreferencesRef 191SCPreferencesCreateWithAuthorization ( 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 */ 213Boolean 214SCPreferencesLock ( 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 */ 236Boolean 237SCPreferencesCommitChanges ( 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 */ 249Boolean 250SCPreferencesApplyChanges ( 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 */ 265Boolean 266SCPreferencesUnlock ( 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 */ 278CFDataRef 279SCPreferencesGetSignature ( 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 */ 290CFArrayRef 291SCPreferencesCopyKeyList ( 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 */ 309CFPropertyListRef 310SCPreferencesGetValue ( 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 */ 330Boolean 331SCPreferencesAddValue ( 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 */ 351Boolean 352SCPreferencesSetValue ( 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 */ 370Boolean 371SCPreferencesRemoveValue ( 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 */ 389Boolean 390SCPreferencesSetCallback ( 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 */ 409Boolean 410SCPreferencesScheduleWithRunLoop ( 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 */ 429Boolean 430SCPreferencesUnscheduleFromRunLoop ( 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 */ 445Boolean 446SCPreferencesSetDispatchQueue ( 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 */ 462void 463SCPreferencesSynchronize ( 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 */ 471