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