1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/modules/libpref/public/nsIPrefBranch.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,409 @@
1.4 +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIObserver;
1.12 +
1.13 +/**
1.14 + * The nsIPrefBranch interface is used to manipulate the preferences data. This
1.15 + * object may be obtained from the preferences service (nsIPrefService) and
1.16 + * used to get and set default and/or user preferences across the application.
1.17 + *
1.18 + * This object is created with a "root" value which describes the base point in
1.19 + * the preferences "tree" from which this "branch" stems. Preferences are
1.20 + * accessed off of this root by using just the final portion of the preference.
1.21 + * For example, if this object is created with the root "browser.startup.",
1.22 + * the preferences "browser.startup.page", "browser.startup.homepage",
1.23 + * and "browser.startup.homepage_override" can be accessed by simply passing
1.24 + * "page", "homepage", or "homepage_override" to the various Get/Set methods.
1.25 + *
1.26 + * @see nsIPrefService
1.27 + */
1.28 +
1.29 +[scriptable, uuid(55d25e49-793f-4727-a69f-de8b15f4b985)]
1.30 +interface nsIPrefBranch : nsISupports
1.31 +{
1.32 +
1.33 + /**
1.34 + * Values describing the basic preference types.
1.35 + *
1.36 + * @see getPrefType
1.37 + */
1.38 + const long PREF_INVALID = 0;
1.39 + const long PREF_STRING = 32;
1.40 + const long PREF_INT = 64;
1.41 + const long PREF_BOOL = 128;
1.42 +
1.43 + /**
1.44 + * Called to get the root on which this branch is based, such as
1.45 + * "browser.startup."
1.46 + */
1.47 + readonly attribute string root;
1.48 +
1.49 + /**
1.50 + * Called to determine the type of a specific preference.
1.51 + *
1.52 + * @param aPrefName The preference to get the type of.
1.53 + *
1.54 + * @return long A value representing the type of the preference. This
1.55 + * value will be PREF_STRING, PREF_INT, or PREF_BOOL.
1.56 + */
1.57 + long getPrefType(in string aPrefName);
1.58 +
1.59 + /**
1.60 + * Called to get the state of an individual boolean preference.
1.61 + *
1.62 + * @param aPrefName The boolean preference to get the state of.
1.63 + *
1.64 + * @return boolean The value of the requested boolean preference.
1.65 + *
1.66 + * @see setBoolPref
1.67 + */
1.68 + boolean getBoolPref(in string aPrefName);
1.69 +
1.70 + /**
1.71 + * Called to set the state of an individual boolean preference.
1.72 + *
1.73 + * @param aPrefName The boolean preference to set the state of.
1.74 + * @param aValue The boolean value to set the preference to.
1.75 + *
1.76 + * @throws Error if setting failed or the preference has a default
1.77 + value of a type other than boolean.
1.78 + *
1.79 + * @see getBoolPref
1.80 + */
1.81 + void setBoolPref(in string aPrefName, in boolean aValue);
1.82 +
1.83 + /**
1.84 + * Called to get the state of an individual floating-point preference.
1.85 + * "Floating point" preferences are really string preferences that
1.86 + * are converted to floating point numbers.
1.87 + *
1.88 + * @param aPrefName The floating point preference to get the state of.
1.89 + *
1.90 + * @return float The value of the requested floating point preference.
1.91 + *
1.92 + * @see setCharPref
1.93 + */
1.94 + float getFloatPref(in string aPrefName);
1.95 +
1.96 + /**
1.97 + * Called to get the state of an individual string preference.
1.98 + *
1.99 + * @param aPrefName The string preference to retrieve.
1.100 + *
1.101 + * @return string The value of the requested string preference.
1.102 + *
1.103 + * @see setCharPref
1.104 + */
1.105 + string getCharPref(in string aPrefName);
1.106 +
1.107 + /**
1.108 + * Called to set the state of an individual string preference.
1.109 + *
1.110 + * @param aPrefName The string preference to set.
1.111 + * @param aValue The string value to set the preference to.
1.112 + *
1.113 + * @throws Error if setting failed or the preference has a default
1.114 + value of a type other than string.
1.115 + *
1.116 + * @see getCharPref
1.117 + */
1.118 + void setCharPref(in string aPrefName, in string aValue);
1.119 +
1.120 + /**
1.121 + * Called to get the state of an individual integer preference.
1.122 + *
1.123 + * @param aPrefName The integer preference to get the value of.
1.124 + *
1.125 + * @return long The value of the requested integer preference.
1.126 + *
1.127 + * @see setIntPref
1.128 + */
1.129 + long getIntPref(in string aPrefName);
1.130 +
1.131 + /**
1.132 + * Called to set the state of an individual integer preference.
1.133 + *
1.134 + * @param aPrefName The integer preference to set the value of.
1.135 + * @param aValue The integer value to set the preference to.
1.136 + *
1.137 + * @throws Error if setting failed or the preference has a default
1.138 + value of a type other than integer.
1.139 + *
1.140 + * @see getIntPref
1.141 + */
1.142 + void setIntPref(in string aPrefName, in long aValue);
1.143 +
1.144 + /**
1.145 + * Called to get the state of an individual complex preference. A complex
1.146 + * preference is a preference which represents an XPCOM object that can not
1.147 + * be easily represented using a standard boolean, integer or string value.
1.148 + *
1.149 + * @param aPrefName The complex preference to get the value of.
1.150 + * @param aType The XPCOM interface that this complex preference
1.151 + * represents. Interfaces currently supported are:
1.152 + * - nsIFile
1.153 + * - nsISupportsString (UniChar)
1.154 + * - nsIPrefLocalizedString (Localized UniChar)
1.155 + * @param aValue The XPCOM object into which to the complex preference
1.156 + * value should be retrieved.
1.157 + *
1.158 + * @throws Error The value does not exist or is the wrong type.
1.159 + *
1.160 + * @see setComplexValue
1.161 + */
1.162 + void getComplexValue(in string aPrefName, in nsIIDRef aType,
1.163 + [iid_is(aType), retval] out nsQIResult aValue);
1.164 +
1.165 + /**
1.166 + * Called to set the state of an individual complex preference. A complex
1.167 + * preference is a preference which represents an XPCOM object that can not
1.168 + * be easily represented using a standard boolean, integer or string value.
1.169 + *
1.170 + * @param aPrefName The complex preference to set the value of.
1.171 + * @param aType The XPCOM interface that this complex preference
1.172 + * represents. Interfaces currently supported are:
1.173 + * - nsIFile
1.174 + * - nsISupportsString (UniChar)
1.175 + * - nsIPrefLocalizedString (Localized UniChar)
1.176 + * @param aValue The XPCOM object from which to set the complex preference
1.177 + * value.
1.178 + *
1.179 + * @throws Error if setting failed or the value is the wrong type.
1.180 + *
1.181 + * @see getComplexValue
1.182 + */
1.183 + void setComplexValue(in string aPrefName, in nsIIDRef aType, in nsISupports aValue);
1.184 +
1.185 + /**
1.186 + * Called to clear a user set value from a specific preference. This will, in
1.187 + * effect, reset the value to the default value. If no default value exists
1.188 + * the preference will cease to exist.
1.189 + *
1.190 + * @param aPrefName The preference to be cleared.
1.191 + *
1.192 + * @note
1.193 + * This method does nothing if this object is a default branch.
1.194 + */
1.195 + void clearUserPref(in string aPrefName);
1.196 +
1.197 + /**
1.198 + * Called to lock a specific preference. Locking a preference will cause the
1.199 + * preference service to always return the default value regardless of
1.200 + * whether there is a user set value or not.
1.201 + *
1.202 + * @param aPrefName The preference to be locked.
1.203 + *
1.204 + * @note
1.205 + * This method can be called on either a default or user branch but, in
1.206 + * effect, always operates on the default branch.
1.207 + *
1.208 + * @throws Error The preference does not exist or an error occurred.
1.209 + *
1.210 + * @see unlockPref
1.211 + */
1.212 + void lockPref(in string aPrefName);
1.213 +
1.214 + /**
1.215 + * Called to check if a specific preference has a user value associated to
1.216 + * it.
1.217 + *
1.218 + * @param aPrefName The preference to be tested.
1.219 + *
1.220 + * @note
1.221 + * This method can be called on either a default or user branch but, in
1.222 + * effect, always operates on the user branch.
1.223 + *
1.224 + * @note
1.225 + * If a preference was manually set to a value that equals the default value,
1.226 + * then the preference no longer has a user set value, i.e. it is
1.227 + * considered reset to its default value.
1.228 + * In particular, this method will return false for such a preference and
1.229 + * the preference will not be saved to a file by nsIPrefService.savePrefFile.
1.230 + *
1.231 + * @return boolean true The preference has a user set value.
1.232 + * false The preference only has a default value.
1.233 + */
1.234 + boolean prefHasUserValue(in string aPrefName);
1.235 +
1.236 + /**
1.237 + * Called to check if a specific preference is locked. If a preference is
1.238 + * locked calling its Get method will always return the default value.
1.239 + *
1.240 + * @param aPrefName The preference to be tested.
1.241 + *
1.242 + * @note
1.243 + * This method can be called on either a default or user branch but, in
1.244 + * effect, always operates on the default branch.
1.245 + *
1.246 + * @return boolean true The preference is locked.
1.247 + * false The preference is not locked.
1.248 + *
1.249 + * @see lockPref
1.250 + * @see unlockPref
1.251 + */
1.252 + boolean prefIsLocked(in string aPrefName);
1.253 +
1.254 + /**
1.255 + * Called to unlock a specific preference. Unlocking a previously locked
1.256 + * preference allows the preference service to once again return the user set
1.257 + * value of the preference.
1.258 + *
1.259 + * @param aPrefName The preference to be unlocked.
1.260 + *
1.261 + * @note
1.262 + * This method can be called on either a default or user branch but, in
1.263 + * effect, always operates on the default branch.
1.264 + *
1.265 + * @throws Error The preference does not exist or an error occurred.
1.266 + *
1.267 + * @see lockPref
1.268 + */
1.269 + void unlockPref(in string aPrefName);
1.270 +
1.271 +
1.272 + /**
1.273 + * Called to remove all of the preferences referenced by this branch.
1.274 + *
1.275 + * @param aStartingAt The point on the branch at which to start the deleting
1.276 + * preferences. Pass in "" to remove all preferences
1.277 + * referenced by this branch.
1.278 + *
1.279 + * @note
1.280 + * This method can be called on either a default or user branch but, in
1.281 + * effect, always operates on both.
1.282 + *
1.283 + * @throws Error The preference(s) do not exist or an error occurred.
1.284 + */
1.285 + void deleteBranch(in string aStartingAt);
1.286 +
1.287 + /**
1.288 + * Returns an array of strings representing the child preferences of the
1.289 + * root of this branch.
1.290 + *
1.291 + * @param aStartingAt The point on the branch at which to start enumerating
1.292 + * the child preferences. Pass in "" to enumerate all
1.293 + * preferences referenced by this branch.
1.294 + * @param aCount Receives the number of elements in the array.
1.295 + * @param aChildArray Receives the array of child preferences.
1.296 + *
1.297 + * @note
1.298 + * This method can be called on either a default or user branch but, in
1.299 + * effect, always operates on both.
1.300 + *
1.301 + * @throws Error The preference(s) do not exist or an error occurred.
1.302 + */
1.303 + void getChildList(in string aStartingAt,
1.304 + [optional] out unsigned long aCount,
1.305 + [array, size_is(aCount), retval] out string aChildArray);
1.306 +
1.307 + /**
1.308 + * Called to reset all of the preferences referenced by this branch to their
1.309 + * default values.
1.310 + *
1.311 + * @param aStartingAt The point on the branch at which to start the resetting
1.312 + * preferences to their default values. Pass in "" to
1.313 + * reset all preferences referenced by this branch.
1.314 + *
1.315 + * @note
1.316 + * This method can be called on either a default or user branch but, in
1.317 + * effect, always operates on the user branch.
1.318 + *
1.319 + * @throws Error The preference(s) do not exist or an error occurred.
1.320 + */
1.321 + void resetBranch(in string aStartingAt);
1.322 +
1.323 + /**
1.324 + * Add a preference change observer. On preference changes, the following
1.325 + * arguments will be passed to the nsIObserver.observe() method:
1.326 + * aSubject - The nsIPrefBranch object (this)
1.327 + * aTopic - The string defined by NS_PREFBRANCH_PREFCHANGE_TOPIC_ID
1.328 + * aData - The name of the preference which has changed, relative to
1.329 + * the |root| of the aSubject branch.
1.330 + *
1.331 + * aSubject.get*Pref(aData) will get the new value of the modified
1.332 + * preference. For example, if your observer is registered with
1.333 + * addObserver("bar.", ...) on a branch with root "foo.", modifying
1.334 + * the preference "foo.bar.baz" will trigger the observer, and aData
1.335 + * parameter will be "bar.baz".
1.336 + *
1.337 + * @param aDomain The preference on which to listen for changes. This can
1.338 + * be the name of an entire branch to observe.
1.339 + * e.g. Holding the "root" prefbranch and calling
1.340 + * addObserver("foo.bar.", ...) will observe changes to
1.341 + * foo.bar.baz and foo.bar.bzip
1.342 + * @param aObserver The object to be notified if the preference changes.
1.343 + * @param aHoldWeak true Hold a weak reference to |aObserver|. The object
1.344 + * must implement the nsISupportsWeakReference
1.345 + * interface or this will fail.
1.346 + * false Hold a strong reference to |aObserver|.
1.347 + *
1.348 + * @note
1.349 + * Registering as a preference observer can open an object to potential
1.350 + * cyclical references which will cause memory leaks. These cycles generally
1.351 + * occur because an object both registers itself as an observer (causing the
1.352 + * branch to hold a reference to the observer) and holds a reference to the
1.353 + * branch object for the purpose of getting/setting preference values. There
1.354 + * are 3 approaches which have been implemented in an attempt to avoid these
1.355 + * situations.
1.356 + * 1) The nsPrefBranch object supports nsISupportsWeakReference. Any consumer
1.357 + * may hold a weak reference to it instead of a strong one.
1.358 + * 2) The nsPrefBranch object listens for xpcom-shutdown and frees all of the
1.359 + * objects currently in its observer list. This ensures that long lived
1.360 + * objects (services for example) will be freed correctly.
1.361 + * 3) The observer can request to be held as a weak reference when it is
1.362 + * registered. This insures that shorter lived objects (say one tied to an
1.363 + * open window) will not fall into the cyclical reference trap.
1.364 + *
1.365 + * @note
1.366 + * The list of registered observers may be changed during the dispatch of
1.367 + * nsPref:changed notification. However, the observers are not guaranteed
1.368 + * to be notified in any particular order, so you can't be sure whether the
1.369 + * added/removed observer will be called during the notification when it
1.370 + * is added/removed.
1.371 + *
1.372 + * @note
1.373 + * It is possible to change preferences during the notification.
1.374 + *
1.375 + * @note
1.376 + * It is not safe to change observers during this callback in Gecko
1.377 + * releases before 1.9. If you want a safe way to remove a pref observer,
1.378 + * please use an nsITimer.
1.379 + *
1.380 + * @see nsIObserver
1.381 + * @see removeObserver
1.382 + */
1.383 + void addObserver(in string aDomain, in nsIObserver aObserver,
1.384 + in boolean aHoldWeak);
1.385 +
1.386 + /**
1.387 + * Remove a preference change observer.
1.388 + *
1.389 + * @param aDomain The preference which is being observed for changes.
1.390 + * @param aObserver An observer previously registered with addObserver().
1.391 + *
1.392 + * @note
1.393 + * Note that you must call removeObserver() on the same nsIPrefBranch
1.394 + * instance on which you called addObserver() in order to remove aObserver;
1.395 + * otherwise, the observer will not be removed.
1.396 + *
1.397 + * @see nsIObserver
1.398 + * @see addObserver
1.399 + */
1.400 + void removeObserver(in string aDomain, in nsIObserver aObserver);
1.401 +};
1.402 +
1.403 +
1.404 +%{C++
1.405 +
1.406 +#define NS_PREFBRANCH_CONTRACTID "@mozilla.org/preferencesbranch;1"
1.407 +/**
1.408 + * Notification sent when a preference changes.
1.409 + */
1.410 +#define NS_PREFBRANCH_PREFCHANGE_TOPIC_ID "nsPref:changed"
1.411 +
1.412 +%}
