modules/libpref/nsIPrefBranch.idl

   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/. */
   5
   6 #include "nsISupports.idl"
   7
   8 %{C++
   9 #include "nsLiteralString.h"
  10 %}
  11
  12 interface nsIObserver;
  13
  14 /**
  15  * The nsIPrefBranch interface is used to manipulate the preferences data. This
  16  * object may be obtained from the preferences service (nsIPrefService) and
  17  * used to get and set default and/or user preferences across the application.
  18  *
  19  * This object is created with a "root" value which describes the base point in
  20  * the preferences "tree" from which this "branch" stems. Preferences are
  21  * accessed off of this root by using just the final portion of the preference.
  22  * For example, if this object is created with the root "browser.startup.",
  23  * the preferences "browser.startup.page", "browser.startup.homepage",
  24  * and "browser.startup.homepage_override" can be accessed by simply passing
  25  * "page", "homepage", or "homepage_override" to the various Get/Set methods.
  26  *
  27  * @see nsIPrefService
  28  */
  29
  30 [scriptable, builtinclass, uuid(55d25e49-793f-4727-a69f-de8b15f4b985)]
  31 interface nsIPrefBranch : nsISupports
  32 {
  33
  34   /**
  35    * Values describing the basic preference types.
  36    *
  37    * @see getPrefType
  38    */
  39   const long PREF_INVALID = 0;
  40   const long PREF_STRING = 32;
  41   const long PREF_INT = 64;
  42   const long PREF_BOOL = 128;
  43
  44   /**
  45    * Called to get the root on which this branch is based, such as
  46    * "browser.startup."
  47    */
  48   readonly attribute ACString root;
  49
  50   /**
  51    * Called to determine the type of a specific preference.
  52    *
  53    * @param aPrefName The preference to get the type of.
  54    *
  55    * @return long     A value representing the type of the preference. This
  56    *                  value will be PREF_STRING, PREF_INT, or PREF_BOOL.
  57    */
  58   long getPrefType(in string aPrefName);
  59
  60   /**
  61    * Called to get the state of an individual boolean preference.
  62    *
  63    * @param aPrefName The boolean preference to get the state of.
  64    * @param aDefaultValue The value to return if the preference is not set.
  65    *
  66    * @return boolean  The value of the requested boolean preference.
  67    *
  68    * @see setBoolPref
  69    */
  70   [optional_argc,binaryname(GetBoolPrefWithDefault)]
  71   boolean getBoolPref(in string aPrefName, [optional] in boolean aDefaultValue);
  72   [noscript,binaryname(GetBoolPref)]
  73   boolean getBoolPrefXPCOM(in string aPrefName);
  74
  75   /**
  76    * Called to set the state of an individual boolean preference.
  77    *
  78    * @param aPrefName The boolean preference to set the state of.
  79    * @param aValue    The boolean value to set the preference to.
  80    *
  81    * @throws Error if setting failed or the preference has a default
  82              value of a type other than boolean.
  83    *
  84    * @see getBoolPref
  85    */
  86   void setBoolPref(in string aPrefName, in boolean aValue);
  87
  88   /**
  89    * Called to get the state of an individual floating-point preference.
  90    * "Floating point" preferences are really string preferences that
  91    * are converted to floating point numbers.
  92    *
  93    * @param aPrefName The floating point preference to get the state of.
  94    * @param aDefaultValue The value to return if the preference is not set.
  95    *
  96    * @return float  The value of the requested floating point preference.
  97    *
  98    * @see setCharPref
  99    */
 100   [optional_argc,binaryname(GetFloatPrefWithDefault)]
 101   float getFloatPref(in string aPrefName, [optional] in float aDefaultValue);
 102   [noscript,binaryname(GetFloatPref)]
 103   float getFloatPrefXPCOM(in string aPrefName);
 104
 105   /**
 106    * Called to get the state of an individual ascii string preference.
 107    *
 108    * @param aPrefName The string preference to retrieve.
 109    * @param aDefaultValue The string to return if the preference is not set.
 110    *
 111    * @return ACString   The value of the requested string preference.
 112    *
 113    * @see setCharPref
 114    */
 115   [optional_argc,binaryname(GetCharPrefWithDefault)]
 116   ACString getCharPref(in string aPrefName,
 117                        [optional] in ACString aDefaultValue);
 118   [noscript,binaryname(GetCharPref)]
 119   ACString getCharPrefXPCOM(in string aPrefName);
 120
 121   /**
 122    * Called to set the state of an individual ascii string preference.
 123    *
 124    * @param aPrefName The string preference to set.
 125    * @param aValue    The string value to set the preference to.
 126    *
 127    * @throws Error if setting failed or the preference has a default
 128              value of a type other than string.
 129    *
 130    * @see getCharPref
 131    */
 132   void setCharPref(in string aPrefName, in ACString aValue);
 133
 134   /**
 135    * Called to get the state of an individual unicode string preference.
 136    *
 137    * @param aPrefName The string preference to retrieve.
 138    * @param aDefaultValue The string to return if the preference is not set.
 139    *
 140    * @return AUTF8String   The value of the requested string preference.
 141    *
 142    * @see setStringPref
 143    */
 144   [optional_argc]
 145   AUTF8String getStringPref(in string aPrefName,
 146                             [optional] in AUTF8String aDefaultValue);
 147
 148   /**
 149    * Called to set the state of an individual unicode string preference.
 150    *
 151    * @param aPrefName The string preference to set.
 152    * @param aValue    The string value to set the preference to.
 153    *
 154    * @throws Error if setting failed or the preference has a default
 155              value of a type other than string.
 156    *
 157    * @see getStringPref
 158    */
 159   void setStringPref(in string aPrefName, in AUTF8String aValue);
 160
 161   /**
 162    * Called to get the state of an individual integer preference.
 163    *
 164    * @param aPrefName The integer preference to get the value of.
 165    * @param aDefaultValue The value to return if the preference is not set.
 166    *
 167    * @return long     The value of the requested integer preference.
 168    *
 169    * @see setIntPref
 170    */
 171   [optional_argc,binaryname(GetIntPrefWithDefault)]
 172   long getIntPref(in string aPrefName, [optional] in long aDefaultValue);
 173   [noscript,binaryname(GetIntPref)]
 174   long getIntPrefXPCOM(in string aPrefName);
 175
 176   /**
 177    * Called to set the state of an individual integer preference.
 178    *
 179    * @param aPrefName The integer preference to set the value of.
 180    * @param aValue    The integer value to set the preference to.
 181    *
 182    * @throws Error if setting failed or the preference has a default
 183              value of a type other than integer.
 184    *
 185    * @see getIntPref
 186    */
 187   void setIntPref(in string aPrefName, in long aValue);
 188
 189   /**
 190    * Called to get the state of an individual complex preference. A complex
 191    * preference is a preference which represents an XPCOM object that can not
 192    * be easily represented using a standard boolean, integer or string value.
 193    *
 194    * @param aPrefName The complex preference to get the value of.
 195    * @param aType     The XPCOM interface that this complex preference
 196    *                  represents. Interfaces currently supported are:
 197    *                    - nsIFile
 198    *                    - nsIPrefLocalizedString (Localized UniChar)
 199    * @param aValue    The XPCOM object into which to the complex preference
 200    *                  value should be retrieved.
 201    *
 202    * @throws Error The value does not exist or is the wrong type.
 203    *
 204    * @see setComplexValue
 205    */
 206   void getComplexValue(in string aPrefName, in nsIIDRef aType,
 207                        [iid_is(aType), retval] out nsQIResult aValue);
 208
 209   /**
 210    * Called to set the state of an individual complex preference. A complex
 211    * preference is a preference which represents an XPCOM object that can not
 212    * be easily represented using a standard boolean, integer or string value.
 213    *
 214    * @param aPrefName The complex preference to set the value of.
 215    * @param aType     The XPCOM interface that this complex preference
 216    *                  represents. Interfaces currently supported are:
 217    *                    - nsIFile
 218    *                    - nsISupportsString (UniChar)
 219    *                      (deprecated; see setStringPref)
 220    *                    - nsIPrefLocalizedString (Localized UniChar)
 221    * @param aValue    The XPCOM object from which to set the complex preference
 222    *                  value.
 223    *
 224    * @throws Error if setting failed or the value is the wrong type.
 225    *
 226    * @see getComplexValue
 227    */
 228   void setComplexValue(in string aPrefName, in nsIIDRef aType, in nsISupports aValue);
 229
 230   /**
 231    * Called to clear a user set value from a specific preference. This will, in
 232    * effect, reset the value to the default value. If no default value exists
 233    * the preference will cease to exist.
 234    *
 235    * @param aPrefName The preference to be cleared.
 236    *
 237    * @note
 238    * This method does nothing if this object is a default branch.
 239    */
 240   void clearUserPref(in string aPrefName);
 241
 242   /**
 243    * Called to lock a specific preference. Locking a preference will cause the
 244    * preference service to always return the default value regardless of
 245    * whether there is a user set value or not.
 246    *
 247    * @param aPrefName The preference to be locked.
 248    *
 249    * @note
 250    * This method can be called on either a default or user branch but, in
 251    * effect, always operates on the default branch.
 252    *
 253    * @throws Error The preference does not exist or an error occurred.
 254    *
 255    * @see unlockPref
 256    */
 257   void lockPref(in string aPrefName);
 258
 259   /**
 260    * Called to check if a specific preference has a user value associated to
 261    * it.
 262    *
 263    * @param aPrefName The preference to be tested.
 264    *
 265    * @note
 266    * This method can be called on either a default or user branch but, in
 267    * effect, always operates on the user branch.
 268    *
 269    * @note
 270    * If a preference was manually set to a value that equals the default value,
 271    * then the preference no longer has a user set value, i.e. it is
 272    * considered reset to its default value.
 273    * In particular, this method will return false for such a preference and
 274    * the preference will not be saved to a file by nsIPrefService.savePrefFile.
 275    *
 276    * @return boolean  true  The preference has a user set value.
 277    *                  false The preference only has a default value.
 278    */
 279   boolean prefHasUserValue(in string aPrefName);
 280
 281   /**
 282    * Called to check if a specific preference has a default value associated to
 283    * it.
 284    *
 285    * @param aPrefName The preference to be tested.
 286    *
 287    * @note
 288    * This method can be called on either a default or user branch but, in
 289    * effect, always operates on the user branch.
 290    *
 291    * @note
 292    * This method can be used to distinguish between a built-in preference and a
 293    * user-added preference.
 294    *
 295    * @return boolean  true  The preference has a default value.
 296    *                  false The preference only has a user value.
 297    */
 298   boolean prefHasDefaultValue(in string aPrefName);
 299
 300   /**
 301    * Called to check if a specific preference is locked. If a preference is
 302    * locked calling its Get method will always return the default value.
 303    *
 304    * @param aPrefName The preference to be tested.
 305    *
 306    * @note
 307    * This method can be called on either a default or user branch but, in
 308    * effect, always operates on the default branch.
 309    *
 310    * @return boolean  true  The preference is locked.
 311    *                  false The preference is not locked.
 312    *
 313    * @see lockPref
 314    * @see unlockPref
 315    */
 316   boolean prefIsLocked(in string aPrefName);
 317
 318   /**
 319    * Called to check if a specific preference has been sanitized. If a
 320    * preference is sanitized, any user value the preference may have will not
 321    * be present in a sub-process.  A preference is never sanitized in the
 322    * parent process; it is only marked as sanitized when it is converted
 323    * to a dom::Pref for serialization to a child process.
 324    *
 325    * @param aPrefName The preference to be tested.
 326    *
 327    * @note
 328    * This method can be called on either a default or user branch but it
 329    * makes no difference.
 330    *
 331    * @return boolean  true  The preference is sanitized.
 332    *                  false The preference is not sanitized.
 333    */
 334   boolean prefIsSanitized(in string aPrefName);
 335
 336   /**
 337    * Called to unlock a specific preference. Unlocking a previously locked
 338    * preference allows the preference service to once again return the user set
 339    * value of the preference.
 340    *
 341    * @param aPrefName The preference to be unlocked.
 342    *
 343    * @note
 344    * This method can be called on either a default or user branch but, in
 345    * effect, always operates on the default branch.
 346    *
 347    * @throws Error The preference does not exist or an error occurred.
 348    *
 349    * @see lockPref
 350    */
 351   void    unlockPref(in string aPrefName);
 352
 353
 354   /**
 355    * Called to remove all of the preferences referenced by this branch.
 356    *
 357    * @param aStartingAt The point on the branch at which to start the deleting
 358    *                    preferences. Pass in "" to remove all preferences
 359    *                    referenced by this branch.
 360    *
 361    * @note
 362    * This method can be called on either a default or user branch but, in
 363    * effect, always operates on both.
 364    *
 365    * @throws Error The preference(s) do not exist or an error occurred.
 366    */
 367   void deleteBranch(in string aStartingAt);
 368
 369   /**
 370    * Returns an array of strings representing the child preferences of the
 371    * root of this branch.
 372    *
 373    * @param aStartingAt The point on the branch at which to start enumerating
 374    *                    the child preferences. Pass in "" to enumerate all
 375    *                    preferences referenced by this branch.
 376    * @return            The array of child preferences.
 377    *
 378    * @note
 379    * This method can be called on either a default or user branch but, in
 380    * effect, always operates on both.
 381    *
 382    * @throws Error The preference(s) do not exist or an error occurred.
 383    */
 384   Array<ACString> getChildList(in string aStartingAt);
 385
 386   /**
 387    * Add a preference change observer. On preference changes, the following
 388    * arguments will be passed to the nsIObserver.observe() method:
 389    *   aSubject - The nsIPrefBranch object (this)
 390    *   aTopic   - The string defined by NS_PREFBRANCH_PREFCHANGE_TOPIC_ID
 391    *   aData    - The name of the preference which has changed, relative to
 392    *              the |root| of the aSubject branch.
 393    *
 394    * aSubject.get*Pref(aData) will get the new value of the modified
 395    * preference. For example, if your observer is registered with
 396    * addObserver("bar.", ...) on a branch with root "foo.", modifying
 397    * the preference "foo.bar.baz" will trigger the observer, and aData
 398    * parameter will be "bar.baz".
 399    *
 400    * @param aDomain   The preference on which to listen for changes. This can
 401    *                  be the name of an entire branch to observe.
 402    *                  e.g. Holding the "root" prefbranch and calling
 403    *                  addObserver("foo.bar.", ...) will observe changes to
 404    *                  foo.bar.baz and foo.bar.bzip
 405    * @param aObserver The object to be notified if the preference changes.
 406    * @param aHoldWeak true  Hold a weak reference to |aObserver|. The object
 407    *                        must implement the nsISupportsWeakReference
 408    *                        interface or this will fail.
 409    *                  false Hold a strong reference to |aObserver|.
 410    *
 411    * @note
 412    * Registering as a preference observer can open an object to potential
 413    * cyclical references which will cause memory leaks. These cycles generally
 414    * occur because an object both registers itself as an observer (causing the
 415    * branch to hold a reference to the observer) and holds a reference to the
 416    * branch object for the purpose of getting/setting preference values. There
 417    * are 3 approaches which have been implemented in an attempt to avoid these
 418    * situations.
 419    * 1) The nsPrefBranch object supports nsISupportsWeakReference. Any consumer
 420    *    may hold a weak reference to it instead of a strong one.
 421    * 2) The nsPrefBranch object listens for xpcom-shutdown and frees all of the
 422    *    objects currently in its observer list. This ensures that long lived
 423    *    objects (services for example) will be freed correctly.
 424    * 3) The observer can request to be held as a weak reference when it is
 425    *    registered. This insures that shorter lived objects (say one tied to an
 426    *    open window) will not fall into the cyclical reference trap.
 427    *
 428    * @note
 429    * The list of registered observers may be changed during the dispatch of
 430    * nsPref:changed notification. However, the observers are not guaranteed
 431    * to be notified in any particular order, so you can't be sure whether the
 432    * added/removed observer will be called during the notification when it
 433    * is added/removed.
 434    *
 435    * @note
 436    * It is possible to change preferences during the notification.
 437    *
 438    * @note
 439    * It is not safe to change observers during this callback in Gecko
 440    * releases before 1.9. If you want a safe way to remove a pref observer,
 441    * please use an nsITimer.
 442    *
 443    * @see nsIObserver
 444    * @see removeObserver
 445    */
 446   [binaryname(AddObserverImpl)]
 447   void addObserver(in ACString aDomain, in nsIObserver aObserver,
 448                    [optional] in boolean aHoldWeak);
 449
 450   /**
 451    * Remove a preference change observer.
 452    *
 453    * @param aDomain   The preference which is being observed for changes.
 454    * @param aObserver An observer previously registered with addObserver().
 455    *
 456    * @note
 457    * Note that you must call removeObserver() on the same nsIPrefBranch
 458    * instance on which you called addObserver() in order to remove aObserver;
 459    * otherwise, the observer will not be removed.
 460    *
 461    * @see nsIObserver
 462    * @see addObserver
 463    */
 464   [binaryname(RemoveObserverImpl)]
 465   void removeObserver(in ACString aDomain, in nsIObserver aObserver);
 466
 467   %{C++
 468   nsresult AddObserver(const nsACString& aDomain, nsIObserver* aObserver,
 469                        bool aHoldWeak = false)
 470   {
 471     return AddObserverImpl(aDomain, aObserver, aHoldWeak);
 472   }
 473
 474   template <int N>
 475   nsresult AddObserver(const char (&aDomain)[N], nsIObserver* aObserver,
 476                        bool aHoldWeak = false)
 477   {
 478     return AddObserverImpl(nsLiteralCString(aDomain), aObserver, aHoldWeak);
 479   }
 480
 481   nsresult RemoveObserver(const nsACString& aDomain, nsIObserver* aObserver)
 482   {
 483     return RemoveObserverImpl(aDomain, aObserver);
 484   }
 485
 486   template <int N>
 487   nsresult RemoveObserver(const char (&aDomain)[N], nsIObserver* aObserver)
 488   {
 489     return RemoveObserverImpl(nsLiteralCString(aDomain), aObserver);
 490   }
 491   %}
 492 };
 493
 494
 495 %{C++
 496
 497 /**
 498  * Notification sent when a preference changes.
 499  */
 500 #define NS_PREFBRANCH_PREFCHANGE_TOPIC_ID "nsPref:changed"
 501
 502 %}