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