SystemConfiguration.fproj/SCPreferencesPrivate.h

   1 /*
   2  * Copyright (c) 2000-2005, 2007-2009, 2011, 2012, 2017, 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 _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 SCPreferencesCreateWithOptions
 127         @discussion Initiates access to the per-system set of configuration
 128                 preferences.
 129         @param allocator The CFAllocator that should be used to allocate
 130                 memory for this preferences session.
 131                 This parameter may be NULL in which case the current
 132                 default CFAllocator is used.
 133                 If this reference is not a valid CFAllocator, the behavior
 134                 is undefined.
 135         @param name A string that describes the name of the calling
 136                 process.
 137         @param prefsID A string that identifies the name of the
 138                 group of preferences to be accessed or updated.
 139         @param authorization An authorization reference that is used to
 140                 authorize any access to the enhanced privileges needed
 141                 to manage the preferences session.
 142         @param options A CFDictionary with options that affect the
 143                 configuration preferences and how the APIs interact
 144                 with the plist.
 145         @result Returns a reference to the new SCPreferences.
 146                 You must release the returned value.
 147  */
 148 SCPreferencesRef
 149 SCPreferencesCreateWithOptions          (
 150                                          CFAllocatorRef         allocator,
 151                                          CFStringRef            name,
 152                                          CFStringRef            prefsID,
 153                                          AuthorizationRef       authorization,
 154                                          CFDictionaryRef        options
 155                                          )                      API_AVAILABLE(macos(10.7)) SPI_AVAILABLE(ios(5.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 156
 157 /*!
 158         @function SCPreferencesRemoveAllValues
 159         @discussion Removes all data associated with the preferences.
 160
 161         This function removes all data associated with the preferences.
 162         To commit these changes to permanent storage a call must be made
 163         to the SCPreferencesCommitChanges function.
 164         @param prefs The preferences session.
 165         @result Returns TRUE if the value was removed;
 166                 FALSE if the key did not exist or if an error occurred.
 167  */
 168 Boolean
 169 SCPreferencesRemoveAllValues            (
 170                                          SCPreferencesRef       prefs
 171                                          )                      API_AVAILABLE(macos(10.7)) SPI_AVAILABLE(ios(5.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 172
 173 __END_DECLS
 174
 175 #endif  /* _SCPREFERENCESPRIVATE_H */