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 is locked. If a preference is
 283    * locked calling its Get method will always return the default value.
 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 default branch.
 290    *
 291    * @return boolean  true  The preference is locked.
 292    *                  false The preference is not locked.
 293    *
 294    * @see lockPref
 295    * @see unlockPref
 296    */
 297   boolean prefIsLocked(in string aPrefName);
 298
 299   /**
 300    * Called to unlock a specific preference. Unlocking a previously locked
 301    * preference allows the preference service to once again return the user set
 302    * value of the preference.
 303    *
 304    * @param aPrefName The preference to be unlocked.
 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    * @throws Error The preference does not exist or an error occurred.
 311    *
 312    * @see lockPref
 313    */
 314   void    unlockPref(in string aPrefName);
 315
 316
 317   /**
 318    * Called to remove all of the preferences referenced by this branch.
 319    *
 320    * @param aStartingAt The point on the branch at which to start the deleting
 321    *                    preferences. Pass in "" to remove all preferences
 322    *                    referenced by this branch.
 323    *
 324    * @note
 325    * This method can be called on either a default or user branch but, in
 326    * effect, always operates on both.
 327    *
 328    * @throws Error The preference(s) do not exist or an error occurred.
 329    */
 330   void deleteBranch(in string aStartingAt);
 331
 332   /**
 333    * Returns an array of strings representing the child preferences of the
 334    * root of this branch.
 335    *
 336    * @param aStartingAt The point on the branch at which to start enumerating
 337    *                    the child preferences. Pass in "" to enumerate all
 338    *                    preferences referenced by this branch.
 339    * @return            The array of child preferences.
 340    *
 341    * @note
 342    * This method can be called on either a default or user branch but, in
 343    * effect, always operates on both.
 344    *
 345    * @throws Error The preference(s) do not exist or an error occurred.
 346    */
 347   Array<ACString> getChildList(in string aStartingAt);
 348
 349   /**
 350    * Called to reset all of the preferences referenced by this branch to their
 351    * default values.
 352    *
 353    * @param aStartingAt The point on the branch at which to start the resetting
 354    *                    preferences to their default values. Pass in "" to
 355    *                    reset all preferences referenced by this branch.
 356    *
 357    * @note
 358    * This method can be called on either a default or user branch but, in
 359    * effect, always operates on the user branch.
 360    *
 361    * @throws Error The preference(s) do not exist or an error occurred.
 362    */
 363   void resetBranch(in string aStartingAt);
 364
 365   /**
 366    * Add a preference change observer. On preference changes, the following
 367    * arguments will be passed to the nsIObserver.observe() method:
 368    *   aSubject - The nsIPrefBranch object (this)
 369    *   aTopic   - The string defined by NS_PREFBRANCH_PREFCHANGE_TOPIC_ID
 370    *   aData    - The name of the preference which has changed, relative to
 371    *              the |root| of the aSubject branch.
 372    *
 373    * aSubject.get*Pref(aData) will get the new value of the modified
 374    * preference. For example, if your observer is registered with
 375    * addObserver("bar.", ...) on a branch with root "foo.", modifying
 376    * the preference "foo.bar.baz" will trigger the observer, and aData
 377    * parameter will be "bar.baz".
 378    *
 379    * @param aDomain   The preference on which to listen for changes. This can
 380    *                  be the name of an entire branch to observe.
 381    *                  e.g. Holding the "root" prefbranch and calling
 382    *                  addObserver("foo.bar.", ...) will observe changes to
 383    *                  foo.bar.baz and foo.bar.bzip
 384    * @param aObserver The object to be notified if the preference changes.
 385    * @param aHoldWeak true  Hold a weak reference to |aObserver|. The object
 386    *                        must implement the nsISupportsWeakReference
 387    *                        interface or this will fail.
 388    *                  false Hold a strong reference to |aObserver|.
 389    *
 390    * @note
 391    * Registering as a preference observer can open an object to potential
 392    * cyclical references which will cause memory leaks. These cycles generally
 393    * occur because an object both registers itself as an observer (causing the
 394    * branch to hold a reference to the observer) and holds a reference to the
 395    * branch object for the purpose of getting/setting preference values. There
 396    * are 3 approaches which have been implemented in an attempt to avoid these
 397    * situations.
 398    * 1) The nsPrefBranch object supports nsISupportsWeakReference. Any consumer
 399    *    may hold a weak reference to it instead of a strong one.
 400    * 2) The nsPrefBranch object listens for xpcom-shutdown and frees all of the
 401    *    objects currently in its observer list. This ensures that long lived
 402    *    objects (services for example) will be freed correctly.
 403    * 3) The observer can request to be held as a weak reference when it is
 404    *    registered. This insures that shorter lived objects (say one tied to an
 405    *    open window) will not fall into the cyclical reference trap.
 406    *
 407    * @note
 408    * The list of registered observers may be changed during the dispatch of
 409    * nsPref:changed notification. However, the observers are not guaranteed
 410    * to be notified in any particular order, so you can't be sure whether the
 411    * added/removed observer will be called during the notification when it
 412    * is added/removed.
 413    *
 414    * @note
 415    * It is possible to change preferences during the notification.
 416    *
 417    * @note
 418    * It is not safe to change observers during this callback in Gecko
 419    * releases before 1.9. If you want a safe way to remove a pref observer,
 420    * please use an nsITimer.
 421    *
 422    * @see nsIObserver
 423    * @see removeObserver
 424    */
 425   [binaryname(AddObserverImpl)]
 426   void addObserver(in ACString aDomain, in nsIObserver aObserver,
 427                    [optional] in boolean aHoldWeak);
 428
 429   /**
 430    * Remove a preference change observer.
 431    *
 432    * @param aDomain   The preference which is being observed for changes.
 433    * @param aObserver An observer previously registered with addObserver().
 434    *
 435    * @note
 436    * Note that you must call removeObserver() on the same nsIPrefBranch
 437    * instance on which you called addObserver() in order to remove aObserver;
 438    * otherwise, the observer will not be removed.
 439    *
 440    * @see nsIObserver
 441    * @see addObserver
 442    */
 443   [binaryname(RemoveObserverImpl)]
 444   void removeObserver(in ACString aDomain, in nsIObserver aObserver);
 445
 446   %{C++
 447   nsresult AddObserver(const nsACString& aDomain, nsIObserver* aObserver,
 448                        bool aHoldWeak = false)
 449   {
 450     return AddObserverImpl(aDomain, aObserver, aHoldWeak);
 451   }
 452
 453   template <int N>
 454   nsresult AddObserver(const char (&aDomain)[N], nsIObserver* aObserver,
 455                        bool aHoldWeak = false)
 456   {
 457     return AddObserverImpl(nsLiteralCString(aDomain), aObserver, aHoldWeak);
 458   }
 459
 460   nsresult RemoveObserver(const nsACString& aDomain, nsIObserver* aObserver)
 461   {
 462     return RemoveObserverImpl(aDomain, aObserver);
 463   }
 464
 465   template <int N>
 466   nsresult RemoveObserver(const char (&aDomain)[N], nsIObserver* aObserver)
 467   {
 468     return RemoveObserverImpl(nsLiteralCString(aDomain), aObserver);
 469   }
 470   %}
 471 };
 472
 473
 474 %{C++
 475
 476 #define NS_PREFBRANCH_CONTRACTID "@mozilla.org/preferencesbranch;1"
 477 /**
 478  * Notification sent when a preference changes.
 479  */
 480 #define NS_PREFBRANCH_PREFCHANGE_TOPIC_ID "nsPref:changed"
 481
 482 %}