SystemConfiguration.fproj/SCPreferencesPrivate.h

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