SystemConfiguration.fproj/SCPreferencesPrivate.h

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