modules/libpref/public/nsIPrefBranch.idl@b8a032363ba2
modules/libpref/public/nsIPrefBranch.idl
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #include "nsISupports.idl"
8 interface nsIObserver;
10 /**
11 * The nsIPrefBranch interface is used to manipulate the preferences data. This
12 * object may be obtained from the preferences service (nsIPrefService) and
13 * used to get and set default and/or user preferences across the application.
14 *
15 * This object is created with a "root" value which describes the base point in
16 * the preferences "tree" from which this "branch" stems. Preferences are
17 * accessed off of this root by using just the final portion of the preference.
18 * For example, if this object is created with the root "browser.startup.",
19 * the preferences "browser.startup.page", "browser.startup.homepage",
20 * and "browser.startup.homepage_override" can be accessed by simply passing
21 * "page", "homepage", or "homepage_override" to the various Get/Set methods.
22 *
23 * @see nsIPrefService
24 */
26 [scriptable, uuid(55d25e49-793f-4727-a69f-de8b15f4b985)]
27 interface nsIPrefBranch : nsISupports
28 {
30 /**
31 * Values describing the basic preference types.
32 *
33 * @see getPrefType
34 */
35 const long PREF_INVALID = 0;
36 const long PREF_STRING = 32;
37 const long PREF_INT = 64;
38 const long PREF_BOOL = 128;
40 /**
41 * Called to get the root on which this branch is based, such as
42 * "browser.startup."
43 */
44 readonly attribute string root;
46 /**
47 * Called to determine the type of a specific preference.
48 *
49 * @param aPrefName The preference to get the type of.
50 *
51 * @return long A value representing the type of the preference. This
52 * value will be PREF_STRING, PREF_INT, or PREF_BOOL.
53 */
54 long getPrefType(in string aPrefName);
56 /**
57 * Called to get the state of an individual boolean preference.
58 *
59 * @param aPrefName The boolean preference to get the state of.
60 *
61 * @return boolean The value of the requested boolean preference.
62 *
63 * @see setBoolPref
64 */
65 boolean getBoolPref(in string aPrefName);
67 /**
68 * Called to set the state of an individual boolean preference.
69 *
70 * @param aPrefName The boolean preference to set the state of.
71 * @param aValue The boolean value to set the preference to.
72 *
73 * @throws Error if setting failed or the preference has a default
74 value of a type other than boolean.
75 *
76 * @see getBoolPref
77 */
78 void setBoolPref(in string aPrefName, in boolean aValue);
80 /**
81 * Called to get the state of an individual floating-point preference.
82 * "Floating point" preferences are really string preferences that
83 * are converted to floating point numbers.
84 *
85 * @param aPrefName The floating point preference to get the state of.
86 *
87 * @return float The value of the requested floating point preference.
88 *
89 * @see setCharPref
90 */
91 float getFloatPref(in string aPrefName);
93 /**
94 * Called to get the state of an individual string preference.
95 *
96 * @param aPrefName The string preference to retrieve.
97 *
98 * @return string The value of the requested string preference.
99 *
100 * @see setCharPref
101 */
102 string getCharPref(in string aPrefName);
104 /**
105 * Called to set the state of an individual string preference.
106 *
107 * @param aPrefName The string preference to set.
108 * @param aValue The string value to set the preference to.
109 *
110 * @throws Error if setting failed or the preference has a default
111 value of a type other than string.
112 *
113 * @see getCharPref
114 */
115 void setCharPref(in string aPrefName, in string aValue);
117 /**
118 * Called to get the state of an individual integer preference.
119 *
120 * @param aPrefName The integer preference to get the value of.
121 *
122 * @return long The value of the requested integer preference.
123 *
124 * @see setIntPref
125 */
126 long getIntPref(in string aPrefName);
128 /**
129 * Called to set the state of an individual integer preference.
130 *
131 * @param aPrefName The integer preference to set the value of.
132 * @param aValue The integer value to set the preference to.
133 *
134 * @throws Error if setting failed or the preference has a default
135 value of a type other than integer.
136 *
137 * @see getIntPref
138 */
139 void setIntPref(in string aPrefName, in long aValue);
141 /**
142 * Called to get the state of an individual complex preference. A complex
143 * preference is a preference which represents an XPCOM object that can not
144 * be easily represented using a standard boolean, integer or string value.
145 *
146 * @param aPrefName The complex preference to get the value of.
147 * @param aType The XPCOM interface that this complex preference
148 * represents. Interfaces currently supported are:
149 * - nsIFile
150 * - nsISupportsString (UniChar)
151 * - nsIPrefLocalizedString (Localized UniChar)
152 * @param aValue The XPCOM object into which to the complex preference
153 * value should be retrieved.
154 *
155 * @throws Error The value does not exist or is the wrong type.
156 *
157 * @see setComplexValue
158 */
159 void getComplexValue(in string aPrefName, in nsIIDRef aType,
160 [iid_is(aType), retval] out nsQIResult aValue);
162 /**
163 * Called to set the state of an individual complex preference. A complex
164 * preference is a preference which represents an XPCOM object that can not
165 * be easily represented using a standard boolean, integer or string value.
166 *
167 * @param aPrefName The complex preference to set the value of.
168 * @param aType The XPCOM interface that this complex preference
169 * represents. Interfaces currently supported are:
170 * - nsIFile
171 * - nsISupportsString (UniChar)
172 * - nsIPrefLocalizedString (Localized UniChar)
173 * @param aValue The XPCOM object from which to set the complex preference
174 * value.
175 *
176 * @throws Error if setting failed or the value is the wrong type.
177 *
178 * @see getComplexValue
179 */
180 void setComplexValue(in string aPrefName, in nsIIDRef aType, in nsISupports aValue);
182 /**
183 * Called to clear a user set value from a specific preference. This will, in
184 * effect, reset the value to the default value. If no default value exists
185 * the preference will cease to exist.
186 *
187 * @param aPrefName The preference to be cleared.
188 *
189 * @note
190 * This method does nothing if this object is a default branch.
191 */
192 void clearUserPref(in string aPrefName);
194 /**
195 * Called to lock a specific preference. Locking a preference will cause the
196 * preference service to always return the default value regardless of
197 * whether there is a user set value or not.
198 *
199 * @param aPrefName The preference to be locked.
200 *
201 * @note
202 * This method can be called on either a default or user branch but, in
203 * effect, always operates on the default branch.
204 *
205 * @throws Error The preference does not exist or an error occurred.
206 *
207 * @see unlockPref
208 */
209 void lockPref(in string aPrefName);
211 /**
212 * Called to check if a specific preference has a user value associated to
213 * it.
214 *
215 * @param aPrefName The preference to be tested.
216 *
217 * @note
218 * This method can be called on either a default or user branch but, in
219 * effect, always operates on the user branch.
220 *
221 * @note
222 * If a preference was manually set to a value that equals the default value,
223 * then the preference no longer has a user set value, i.e. it is
224 * considered reset to its default value.
225 * In particular, this method will return false for such a preference and
226 * the preference will not be saved to a file by nsIPrefService.savePrefFile.
227 *
228 * @return boolean true The preference has a user set value.
229 * false The preference only has a default value.
230 */
231 boolean prefHasUserValue(in string aPrefName);
233 /**
234 * Called to check if a specific preference is locked. If a preference is
235 * locked calling its Get method will always return the default value.
236 *
237 * @param aPrefName The preference to be tested.
238 *
239 * @note
240 * This method can be called on either a default or user branch but, in
241 * effect, always operates on the default branch.
242 *
243 * @return boolean true The preference is locked.
244 * false The preference is not locked.
245 *
246 * @see lockPref
247 * @see unlockPref
248 */
249 boolean prefIsLocked(in string aPrefName);
251 /**
252 * Called to unlock a specific preference. Unlocking a previously locked
253 * preference allows the preference service to once again return the user set
254 * value of the preference.
255 *
256 * @param aPrefName The preference to be unlocked.
257 *
258 * @note
259 * This method can be called on either a default or user branch but, in
260 * effect, always operates on the default branch.
261 *
262 * @throws Error The preference does not exist or an error occurred.
263 *
264 * @see lockPref
265 */
266 void unlockPref(in string aPrefName);
269 /**
270 * Called to remove all of the preferences referenced by this branch.
271 *
272 * @param aStartingAt The point on the branch at which to start the deleting
273 * preferences. Pass in "" to remove all preferences
274 * referenced by this branch.
275 *
276 * @note
277 * This method can be called on either a default or user branch but, in
278 * effect, always operates on both.
279 *
280 * @throws Error The preference(s) do not exist or an error occurred.
281 */
282 void deleteBranch(in string aStartingAt);
284 /**
285 * Returns an array of strings representing the child preferences of the
286 * root of this branch.
287 *
288 * @param aStartingAt The point on the branch at which to start enumerating
289 * the child preferences. Pass in "" to enumerate all
290 * preferences referenced by this branch.
291 * @param aCount Receives the number of elements in the array.
292 * @param aChildArray Receives the array of child preferences.
293 *
294 * @note
295 * This method can be called on either a default or user branch but, in
296 * effect, always operates on both.
297 *
298 * @throws Error The preference(s) do not exist or an error occurred.
299 */
300 void getChildList(in string aStartingAt,
301 [optional] out unsigned long aCount,
302 [array, size_is(aCount), retval] out string aChildArray);
304 /**
305 * Called to reset all of the preferences referenced by this branch to their
306 * default values.
307 *
308 * @param aStartingAt The point on the branch at which to start the resetting
309 * preferences to their default values. Pass in "" to
310 * reset all preferences referenced by this branch.
311 *
312 * @note
313 * This method can be called on either a default or user branch but, in
314 * effect, always operates on the user branch.
315 *
316 * @throws Error The preference(s) do not exist or an error occurred.
317 */
318 void resetBranch(in string aStartingAt);
320 /**
321 * Add a preference change observer. On preference changes, the following
322 * arguments will be passed to the nsIObserver.observe() method:
323 * aSubject - The nsIPrefBranch object (this)
324 * aTopic - The string defined by NS_PREFBRANCH_PREFCHANGE_TOPIC_ID
325 * aData - The name of the preference which has changed, relative to
326 * the |root| of the aSubject branch.
327 *
328 * aSubject.get*Pref(aData) will get the new value of the modified
329 * preference. For example, if your observer is registered with
330 * addObserver("bar.", ...) on a branch with root "foo.", modifying
331 * the preference "foo.bar.baz" will trigger the observer, and aData
332 * parameter will be "bar.baz".
333 *
334 * @param aDomain The preference on which to listen for changes. This can
335 * be the name of an entire branch to observe.
336 * e.g. Holding the "root" prefbranch and calling
337 * addObserver("foo.bar.", ...) will observe changes to
338 * foo.bar.baz and foo.bar.bzip
339 * @param aObserver The object to be notified if the preference changes.
340 * @param aHoldWeak true Hold a weak reference to |aObserver|. The object
341 * must implement the nsISupportsWeakReference
342 * interface or this will fail.
343 * false Hold a strong reference to |aObserver|.
344 *
345 * @note
346 * Registering as a preference observer can open an object to potential
347 * cyclical references which will cause memory leaks. These cycles generally
348 * occur because an object both registers itself as an observer (causing the
349 * branch to hold a reference to the observer) and holds a reference to the
350 * branch object for the purpose of getting/setting preference values. There
351 * are 3 approaches which have been implemented in an attempt to avoid these
352 * situations.
353 * 1) The nsPrefBranch object supports nsISupportsWeakReference. Any consumer
354 * may hold a weak reference to it instead of a strong one.
355 * 2) The nsPrefBranch object listens for xpcom-shutdown and frees all of the
356 * objects currently in its observer list. This ensures that long lived
357 * objects (services for example) will be freed correctly.
358 * 3) The observer can request to be held as a weak reference when it is
359 * registered. This insures that shorter lived objects (say one tied to an
360 * open window) will not fall into the cyclical reference trap.
361 *
362 * @note
363 * The list of registered observers may be changed during the dispatch of
364 * nsPref:changed notification. However, the observers are not guaranteed
365 * to be notified in any particular order, so you can't be sure whether the
366 * added/removed observer will be called during the notification when it
367 * is added/removed.
368 *
369 * @note
370 * It is possible to change preferences during the notification.
371 *
372 * @note
373 * It is not safe to change observers during this callback in Gecko
374 * releases before 1.9. If you want a safe way to remove a pref observer,
375 * please use an nsITimer.
376 *
377 * @see nsIObserver
378 * @see removeObserver
379 */
380 void addObserver(in string aDomain, in nsIObserver aObserver,
381 in boolean aHoldWeak);
383 /**
384 * Remove a preference change observer.
385 *
386 * @param aDomain The preference which is being observed for changes.
387 * @param aObserver An observer previously registered with addObserver().
388 *
389 * @note
390 * Note that you must call removeObserver() on the same nsIPrefBranch
391 * instance on which you called addObserver() in order to remove aObserver;
392 * otherwise, the observer will not be removed.
393 *
394 * @see nsIObserver
395 * @see addObserver
396 */
397 void removeObserver(in string aDomain, in nsIObserver aObserver);
398 };
401 %{C++
403 #define NS_PREFBRANCH_CONTRACTID "@mozilla.org/preferencesbranch;1"
404 /**
405 * Notification sent when a preference changes.
406 */
407 #define NS_PREFBRANCH_PREFCHANGE_TOPIC_ID "nsPref:changed"
409 %}
