CFPreferences.h

   1 /*
   2  * Copyright (c) 2015 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 /*      CFPreferences.h
  25         Copyright (c) 1998-2014, Apple Inc. All rights reserved.
  26 */
  27
  28 #if !defined(__COREFOUNDATION_CFPREFERENCES__)
  29 #define __COREFOUNDATION_CFPREFERENCES__ 1
  30
  31 #include <CoreFoundation/CFBase.h>
  32 #include <CoreFoundation/CFArray.h>
  33 #include <CoreFoundation/CFString.h>
  34
  35 CF_IMPLICIT_BRIDGING_ENABLED
  36 CF_EXTERN_C_BEGIN
  37
  38 CF_EXPORT
  39 const CFStringRef kCFPreferencesAnyApplication;
  40 CF_EXPORT
  41 const CFStringRef kCFPreferencesCurrentApplication;
  42 CF_EXPORT
  43 const CFStringRef kCFPreferencesAnyHost;
  44 CF_EXPORT
  45 const CFStringRef kCFPreferencesCurrentHost;
  46 CF_EXPORT
  47 const CFStringRef kCFPreferencesAnyUser;
  48 CF_EXPORT
  49 const CFStringRef kCFPreferencesCurrentUser;
  50
  51 /* NOTE: All CFPropertyListRef values returned from
  52          CFPreferences API should be assumed to be immutable.
  53 */
  54
  55 /*      The "App" functions search the various sources of defaults that
  56         apply to the given application, and should never be called with
  57         kCFPreferencesAnyApplication - only kCFPreferencesCurrentApplication
  58         or an application's ID (its bundle identifier).
  59 */
  60
  61 /* Searches the various sources of application defaults to find the
  62 value for the given key. key must not be NULL.  If a value is found,
  63 it returns it; otherwise returns NULL.  Caller must release the
  64 returned value */
  65 CF_EXPORT
  66 CFPropertyListRef CFPreferencesCopyAppValue(CFStringRef key, CFStringRef applicationID);
  67
  68 /* Convenience to interpret a preferences value as a boolean directly.
  69 Returns false if the key doesn't exist, or has an improper format; under
  70 those conditions, keyExistsAndHasValidFormat (if non-NULL) is set to false */
  71 CF_EXPORT
  72 Boolean CFPreferencesGetAppBooleanValue(CFStringRef key, CFStringRef applicationID, Boolean *keyExistsAndHasValidFormat);
  73
  74 /* Convenience to interpret a preferences value as an integer directly.
  75 Returns 0 if the key doesn't exist, or has an improper format; under
  76 those conditions, keyExistsAndHasValidFormat (if non-NULL) is set to false */
  77 CF_EXPORT
  78 CFIndex CFPreferencesGetAppIntegerValue(CFStringRef key, CFStringRef applicationID, Boolean *keyExistsAndHasValidFormat);
  79
  80 /* Sets the given value for the given key in the "normal" place for
  81 application preferences.  key must not be NULL.  If value is NULL,
  82 key is removed instead. */
  83 CF_EXPORT
  84 void CFPreferencesSetAppValue(CFStringRef key, CFPropertyListRef value, CFStringRef applicationID);
  85
  86 /* Adds the preferences for the given suite to the app preferences for
  87    the specified application.  To write to the suite domain, use
  88    CFPreferencesSetValue(), below, using the suiteName in place
  89    of the appName */
  90 CF_EXPORT
  91 void CFPreferencesAddSuitePreferencesToApp(CFStringRef applicationID, CFStringRef suiteID);
  92
  93 CF_EXPORT
  94 void CFPreferencesRemoveSuitePreferencesFromApp(CFStringRef applicationID, CFStringRef suiteID);
  95
  96 /* Writes all changes in all sources of application defaults.
  97 Returns success or failure. */
  98 CF_EXPORT
  99 Boolean CFPreferencesAppSynchronize(CFStringRef applicationID);
 100
 101 /* The primitive get mechanism; all arguments must be non-NULL
 102 (use the constants above for common values).  Only the exact
 103 location specified by app-user-host is searched.  The returned
 104 CFType must be released by the caller when it is finished with it. */
 105 CF_EXPORT
 106 CFPropertyListRef CFPreferencesCopyValue(CFStringRef key, CFStringRef applicationID, CFStringRef userName, CFStringRef hostName);
 107
 108 /* Convenience to fetch multiple keys at once.  Keys in
 109 keysToFetch that are not present in the returned dictionary
 110 are not present in the domain.  If keysToFetch is NULL, all
 111 keys are fetched. */
 112 CF_EXPORT
 113 CFDictionaryRef CFPreferencesCopyMultiple(CFArrayRef keysToFetch, CFStringRef applicationID, CFStringRef userName, CFStringRef hostName);
 114
 115 /* The primitive set function; all arguments except value must be
 116 non-NULL.  If value is NULL, the given key is removed */
 117 CF_EXPORT
 118 void CFPreferencesSetValue(CFStringRef key, CFPropertyListRef value, CFStringRef applicationID, CFStringRef userName, CFStringRef hostName);
 119
 120 /* Convenience to set multiple values at once.  Behavior is undefined
 121 if a key is in both keysToSet and keysToRemove */
 122 CF_EXPORT
 123 void CFPreferencesSetMultiple(CFDictionaryRef keysToSet, CFArrayRef keysToRemove, CFStringRef applicationID, CFStringRef userName, CFStringRef hostName);
 124
 125 CF_EXPORT
 126 Boolean CFPreferencesSynchronize(CFStringRef applicationID, CFStringRef userName, CFStringRef hostName);
 127
 128 /* Constructs and returns the list of the name of all applications
 129 which have preferences in the scope of the given user and host.
 130 The returned value must be released by the caller; neither argument
 131 may be NULL. */
 132 CF_EXPORT
 133 CFArrayRef CFPreferencesCopyApplicationList(CFStringRef userName, CFStringRef hostName) CF_DEPRECATED(10_0, 10_9, 2_0, 7_0);
 134
 135 /* Constructs and returns the list of all keys set in the given
 136 location.  The returned value must be released by the caller;
 137 all arguments must be non-NULL */
 138 CF_EXPORT
 139 CFArrayRef CFPreferencesCopyKeyList(CFStringRef applicationID, CFStringRef userName, CFStringRef hostName);
 140
 141
 142 CF_EXTERN_C_END
 143 CF_IMPLICIT_BRIDGING_DISABLED
 144
 145 #endif /* ! __COREFOUNDATION_CFPREFERENCES__ */
 146