SystemConfiguration.fproj/SCPreferencesPrivate.h

   1 /*
   2  * Copyright (c) 2000-2005, 2007-2009, 2011, 2012, 2017-2020 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 _SCPREFERENCESPRIVATE_H
  25 #define _SCPREFERENCESPRIVATE_H
  26
  27
  28 #include <os/availability.h>
  29 #include <TargetConditionals.h>
  30 #include <sys/cdefs.h>
  31 #include <CoreFoundation/CoreFoundation.h>
  32 #include <SystemConfiguration/SCPreferences.h>
  33
  34
  35 /*!
  36         @header SCPreferencesPrivate
  37  */
  38
  39 /*!
  40         @defined kSCPreferencesOptionChangeNetworkSet
  41         @abstract The SCPreferences "option" used to indicate that only the
  42                 current network set (location) is being changed.
  43  */
  44 #define kSCPreferencesOptionChangeNetworkSet    CFSTR("change-network-set")     // CFBooleanRef
  45
  46 /*!
  47         @defined kSCPreferencesOptionProtectionClass
  48         @abstract The SCPreferences "option" used to indicate the file
  49                  protection class of the .plist.
  50  */
  51 #define kSCPreferencesOptionProtectionClass     CFSTR("ProtectionClass")        // CFStringRef["A"-"F"]
  52
  53 /*!
  54         @defined kSCPreferencesOptionRemoveWhenEmpty
  55         @abstract The SCPreferences "option" used to indicate that the .plist
  56                 file should be removed when/if all keys have been removed.
  57  */
  58 #define kSCPreferencesOptionRemoveWhenEmpty     CFSTR("remove-when-empty")      // CFBooleanRef
  59
  60 /*!
  61         @defined kSCPreferencesAuthorizationRight_network_set
  62         @abstract The authorization right used to control whether the current
  63                 network set (location) can be changed.
  64  */
  65 #define kSCPreferencesAuthorizationRight_network_set    "system.preferences.location"
  66
  67 /*!
  68         @defined kSCPreferencesAuthorizationRight_write
  69         @abstract The authorization right used to control whether the network
  70                 configuration can be changed.
  71  */
  72 #define kSCPreferencesAuthorizationRight_write          "system.services.systemconfiguration.network"
  73
  74 /*!
  75         @enum SCPreferencesKeyType
  76         @discussion Used with the SCDynamicStoreKeyCreatePreferences() function
  77                 to describe the resulting CFStringRef argument.
  78         @constant kSCPreferencesKeyCommit Key used when new preferences are
  79                 committed to the store
  80         @constant kSCPreferencesKeyApply Key used when new preferences are
  81                 to be applied to the active system configuration.
  82  */
  83 enum {
  84         kSCPreferencesKeyLock   = 1,
  85         kSCPreferencesKeyCommit = 2,
  86         kSCPreferencesKeyApply  = 3
  87 };
  88 typedef int32_t SCPreferencesKeyType;
  89
  90
  91 __BEGIN_DECLS
  92
  93 /*!
  94         @const kSCPreferencesUseEntitlementAuthorization
  95         @discussion An authorization value that can be passed to
  96                 the SCPreferencesCreateWithAuthorization API (or
  97                 the SCPreferencesCreateWithOptions SPI) to indicate
  98                 that the entitlements of the current process should
  99                 be used for authorization purposes.
 100
 101                 This value can ONLY be used with the SCPreferences
 102                 APIs.
 103  */
 104 extern const AuthorizationRef   kSCPreferencesUseEntitlementAuthorization;
 105
 106 /*!
 107         @function SCDynamicStoreKeyCreatePreferences
 108         @discussion Creates a key that can be used by the SCDynamicStoreSetNotificationKeys()
 109                 function to receive notifications of changes to the saved
 110                 preferences.
 111         @param allocator ...
 112         @param prefsID A string that identifies the name of the
 113                 group of preferences to be accessed/updated.
 114         @param keyType A kSCPreferencesKeyType indicating the type a notification
 115                 key to be returned.
 116         @result A notification string for the specified preference identifier.
 117  */
 118 CFStringRef
 119 SCDynamicStoreKeyCreatePreferences      (
 120                                         CFAllocatorRef          allocator,
 121                                         CFStringRef             prefsID,
 122                                         SCPreferencesKeyType    keyType
 123                                         )       API_DEPRECATED("No longer supported", macos(10.1,10.4), ios(2.0,2.0));
 124
 125 /*!
 126        @function SCPreferencesCreateCompanion
 127        @discussion Initiates access to a [companion] of the configuration
 128                preferences.
 129        @param prefs The base preferences session.
 130        @param companionPrefsID  A string that identifies the companion name
 131                 of the group of preferences to be accessed or updated.
 132        @result Returns a reference to the new SCPreferences.
 133                You must release the returned value.
 134 */
 135 SCPreferencesRef
 136 SCPreferencesCreateCompanion            (
 137                                          SCPreferencesRef       prefs,
 138                                          CFStringRef            companionPrefsID
 139                                         )       SPI_AVAILABLE(macos(10.15.4), ios(13.4), tvos(13.4), watchos(6.2), bridgeos(4.0));
 140
 141 /*!
 142         @function SCPreferencesCreateWithOptions
 143         @discussion Initiates access to the per-system set of configuration
 144                 preferences.
 145         @param allocator The CFAllocator that should be used to allocate
 146                 memory for this preferences session.
 147                 This parameter may be NULL in which case the current
 148                 default CFAllocator is used.
 149                 If this reference is not a valid CFAllocator, the behavior
 150                 is undefined.
 151         @param name A string that describes the name of the calling
 152                 process.
 153         @param prefsID A string that identifies the name of the
 154                 group of preferences to be accessed or updated.
 155         @param authorization An authorization reference that is used to
 156                 authorize any access to the enhanced privileges needed
 157                 to manage the preferences session.
 158         @param options A CFDictionary with options that affect the
 159                 configuration preferences and how the APIs interact
 160                 with the plist.
 161         @result Returns a reference to the new SCPreferences.
 162                 You must release the returned value.
 163  */
 164 SCPreferencesRef
 165 SCPreferencesCreateWithOptions          (
 166                                          CFAllocatorRef         allocator,
 167                                          CFStringRef            name,
 168                                          CFStringRef            prefsID,
 169                                          AuthorizationRef       authorization,
 170                                          CFDictionaryRef        options
 171                                          )                      API_AVAILABLE(macos(10.7)) SPI_AVAILABLE(ios(5.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 172
 173 /*!
 174         @function SCPreferencesRemoveAllValues
 175         @discussion Removes all data associated with the preferences.
 176
 177         This function removes all data associated with the preferences.
 178         To commit these changes to permanent storage a call must be made
 179         to the SCPreferencesCommitChanges function.
 180         @param prefs The preferences session.
 181         @result Returns TRUE if the value was removed;
 182                 FALSE if the key did not exist or if an error occurred.
 183  */
 184 Boolean
 185 SCPreferencesRemoveAllValues            (
 186                                          SCPreferencesRef       prefs
 187                                          )                      API_AVAILABLE(macos(10.7)) SPI_AVAILABLE(ios(5.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 188
 189 __END_DECLS
 190
 191 #endif  /* _SCPREFERENCESPRIVATE_H */