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