1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* ***** BEGIN LICENSE BLOCK *****
3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
4 *
5 * The contents of this file are subject to the Mozilla Public License Version
6 * 1.1 (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 * http://www.mozilla.org/MPL/
9 *
10 * Software distributed under the License is distributed on an "AS IS" basis,
11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 * for the specific language governing rights and limitations under the
13 * License.
14 *
15 * The Original Code is mozilla.org code.
16 *
17 * The Initial Developer of the Original Code is
18 * Netscape Communications Corporation.
19 * Portions created by the Initial Developer are Copyright (C) 1998
20 * the Initial Developer. All Rights Reserved.
21 *
22 * Contributor(s):
23 *
24 * Alternatively, the contents of this file may be used under the terms of
25 * either the GNU General Public License Version 2 or later (the "GPL"), or
26 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
27 * in which case the provisions of the GPL or the LGPL are applicable instead
28 * of those above. If you wish to allow use of your version of this file only
29 * under the terms of either the GPL or the LGPL, and not to allow others to
30 * use your version of this file under the terms of the MPL, indicate your
31 * decision by deleting the provisions above and replace them with the notice
32 * and other provisions required by the GPL or the LGPL. If you do not delete
33 * the provisions above, a recipient may use your version of this file under
34 * the terms of any one of the MPL, the GPL or the LGPL.
35 *
36 * ***** END LICENSE BLOCK ***** */
37
38 #include "nsISupports.idl"
39
40 interface nsILocalFile;
41 interface nsIObserver;
42 interface nsIFileSpec;
43
44 #include "nsIPrefService.idl"
45 #include "nsIPrefBranch.idl"
46
47 %{C++
48
49 #ifndef have_PrefChangedFunc_typedef
50 typedef int (*PR_CALLBACK PrefChangedFunc)(const char *, void *);
51 #define have_PrefChangedFunc_typedef
52 #endif
53 typedef void (*PrefEnumerationFunc)(const char *, void *);
54
55 #define NS_PREF_CID \
56 { /* {dc26e0e0-ca94-11d1-a9a4-00805f8a7ac4} */ \
57 0xdc26e0e0, \
58 0xca94, \
59 0x11d1, \
60 { 0xa9, 0xa4, 0x00, 0x80, 0x5f, 0x8a, 0x7a, 0xc4 } \
61 }
62
63 #define NS_PREF_CONTRACTID \
64 "@mozilla.org/preferences;1"
65
66 #define NS_PREF_CLASSNAME "Preferences Service"
67
68 #define NS_PREF_VALUE_CHANGED 1
69 %}
70 native PrefChangedFunc(PrefChangedFunc);
71 native PrefEnumerationFunc(PrefEnumerationFunc);
72
73 /**
74 * This entire interface is deprecated and should not be used.
75 * See nsIPrefService and nsIPrefBranch for the new implementations.
76 *
77 * @status DEPRECATED Replaced by nsIPrefService and nsIPrefBranch
78 */
79 [scriptable, uuid(a22ad7b0-ca86-11d1-a9a4-00805f8a7ac4)]
80 interface nsIPref : nsISupports {
81
82 /*
83 * These are the the Prefs Service methods we will support for now
84 */
85
86 /*
87 * readUserPrefs
88 *
89 * read a user preference file, pass in null for default file
90 */
91 void readUserPrefs(in nsIFile aFile);
92
93 /*
94 * resetPrefs
95 *
96 * completely flush and reload the preferences system
97 */
98 void ResetPrefs();
99
100 /*
101 * resetUserPrefs
102 *
103 * flush all current user prefrences (reset all preferences to the default values)
104 */
105 void ResetUserPrefs();
106
107 /*
108 * savePrefFile
109 *
110 * write current preferences state to a file, pass in null for default file
111 */
112 void savePrefFile(in nsIFile aFile);
113
114 /*
115 * branch operations
116 */
117
118 nsIPrefBranch getBranch(in string aPrefRoot);
119 nsIPrefBranch getDefaultBranch(in string aPrefRoot);
120
121
122 /*
123 * These are the the Prefs Branch methods we will support for now
124 */
125
126 const long ePrefInvalid = 0;
127 const long ePrefLocked = 1;
128 const long ePrefUserset = 2;
129 const long ePrefConfig = 4;
130 const long ePrefRemote = 8;
131 const long ePrefLilocal = 16;
132 const long ePrefString = 32;
133 const long ePrefInt = 64;
134 const long ePrefBool = 128;
135 const long ePrefValuetypeMask = (ePrefString | ePrefInt | ePrefBool);
136
137 /*
138 * the root of this branch, such as "browser."
139 */
140 readonly attribute string root;
141
142 /*
143 * standard methods for accessing preferences
144 */
145 long GetPrefType(in string aPrefName);
146
147 boolean GetBoolPref(in string aPrefName);
148 void SetBoolPref(in string aPrefName, in long aValue);
149
150 string GetCharPref(in string aPrefName);
151 void SetCharPref(in string aPrefName, in string aValue);
152
153 long GetIntPref(in string aPrefName);
154 void SetIntPref(in string aPrefName, in long aValue);
155
156 /*
157 * methods for accessing complex preferences (i.e. items beyond the simple bool, char, and int)
158 */
159 void getComplexValue(in string aPrefName, in nsIIDRef aType, [iid_is(aType), retval] out nsQIResult aValue);
160 void setComplexValue(in string aPrefName, in nsIIDRef aType, in nsISupports aValue);
161
162 /*
163 * methods for preference state manipulation
164 */
165 void ClearUserPref(in string aPrefName);
166 boolean PrefIsLocked(in string aPrefName);
167 void lockPref(in string aPrefName);
168 void unlockPref(in string aPrefName);
169
170
171 /*
172 * branch-level operations
173 */
174
175 /*
176 * resetBranch
177 *
178 * clears all user preferences starting at the given preference prefix
179 * pass in null or "" to clear this branch
180 */
181 void resetBranch(in string aStartingAt);
182
183 /*
184 * deleteBranch
185 *
186 * removes all preferences starting at the given preference prefix
187 * pass in null or "" to remove this branch
188 */
189 void DeleteBranch(in string aStartingAt);
190
191 /*
192 * getChildList
193 *
194 * Returns an array of strings representing the child preferences of the branch root
195 *
196 * @param startingAt pass in null or "" to enumerate the entire branch
197 * @param count Receives the number of elements in the array.
198 * @param childArray Receives the array of child preferences.
199 */
200 void getChildList(in string aStartingAt,
201 out unsigned long aCount,
202 [array, size_is(aCount), retval] out string aChildArray);
203
204
205 /*
206 * Listeners
207 */
208
209 /*
210 * The observers have their |Observe| methods called with
211 * ([the observer], "nsPref:changed", [pref name]).
212 */
213 void addObserver(in string aDomain, in nsIObserver aObserver, in boolean aHoldWeak);
214 void removeObserver(in string aDomain, in nsIObserver aObserver);
215
216
217 /*
218 * Finally some deprecated methods
219 */
220
221
222 // these are changing from Copy->get
223 string CopyCharPref(in string pref);
224 string CopyDefaultCharPref(in string pref);
225
226 /* get & set defaults */
227 boolean GetDefaultBoolPref(in string pref);
228 long GetDefaultIntPref(in string pref);
229
230 void SetDefaultBoolPref(in string pref, in boolean value);
231 void SetDefaultCharPref(in string pref, in string value);
232 void SetDefaultIntPref(in string pref, in long value);
233
234 /* unichar & localized unichar prefs */
235 wstring CopyUnicharPref(in string pref);
236 wstring CopyDefaultUnicharPref(in string pref);
237 void SetUnicharPref(in string pref, in wstring value);
238 void SetDefaultUnicharPref(in string pref, in wstring value);
239 wstring getLocalizedUnicharPref(in string pref);
240 wstring getDefaultLocalizedUnicharPref(in string pref);
241
242 /* file & filespec prefs */
243 nsIFileSpec GetFilePref(in string pref);
244 void SetFilePref(in string pref, in nsIFileSpec value, in boolean setDefault);
245 nsILocalFile getFileXPref(in string pref);
246 void setFileXPref(in string pref, in nsILocalFile value);
247
248 /* callbacks */
249 [noscript] void RegisterCallback(in string domain, in PrefChangedFunc callback, in voidPtr closure);
250 [noscript] void UnregisterCallback(in string domain, in PrefChangedFunc callback, in voidPtr closure);
251
252 /**
253 * EnumerateChildren
254 *
255 * Call back function "callback" with every preference string
256 * having prefix "parent". Pass "data" to "callback" when calling.
257 *
258 * @param parent A string representation of a prefix of preferences
259 * @param callback A function to call back for each matching preference
260 * @param data A piece of data to pass on to the callback
261 */
262 [noscript] void EnumerateChildren(in string parent, in PrefEnumerationFunc callback, in voidPtr data);
263 };