SystemConfiguration.fproj/SCPreferencesPrivate.h

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