SystemConfiguration.fproj/SCPreferences.h

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