The Tor Browser: modules/libpref/public/nsIPrefBranch.idl@b8a032363ba2 (annotated)

modules/libpref/public/nsIPrefBranch.idl@b8a032363ba2 (annotated)

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

 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 #include "nsISupports.idl"
 interface nsIObserver;
 /**
  * The nsIPrefBranch interface is used to manipulate the preferences data. This
  * object may be obtained from the preferences service (nsIPrefService) and
  * used to get and set default and/or user preferences across the application.
  *
  * This object is created with a "root" value which describes the base point in
  * the preferences "tree" from which this "branch" stems. Preferences are
  * accessed off of this root by using just the final portion of the preference.
  * For example, if this object is created with the root "browser.startup.",
  * the preferences "browser.startup.page", "browser.startup.homepage",
  * and "browser.startup.homepage_override" can be accessed by simply passing
  * "page", "homepage", or "homepage_override" to the various Get/Set methods.
  *
  * @see nsIPrefService
  */
 [scriptable, uuid(55d25e49-793f-4727-a69f-de8b15f4b985)]
 interface nsIPrefBranch : nsISupports
 {
   /**
    * Values describing the basic preference types.
    *
    * @see getPrefType
    */
   const long PREF_INVALID = 0;
   const long PREF_STRING = 32;
   const long PREF_INT = 64;
   const long PREF_BOOL = 128;
   /**
    * Called to get the root on which this branch is based, such as
    * "browser.startup."
    */
   readonly attribute string root;
   /**
    * Called to determine the type of a specific preference.
    *
    * @param aPrefName The preference to get the type of.
    *
    * @return long     A value representing the type of the preference. This
    *                  value will be PREF_STRING, PREF_INT, or PREF_BOOL.
    */
   long getPrefType(in string aPrefName);
   /**
    * Called to get the state of an individual boolean preference.
    *
    * @param aPrefName The boolean preference to get the state of.
    *
    * @return boolean  The value of the requested boolean preference.
    *
    * @see setBoolPref
    */
   boolean getBoolPref(in string aPrefName);
   /**
    * Called to set the state of an individual boolean preference.
    *
    * @param aPrefName The boolean preference to set the state of.
    * @param aValue    The boolean value to set the preference to.
    *
    * @throws Error if setting failed or the preference has a default
              value of a type other than boolean.
    *
    * @see getBoolPref
    */
   void setBoolPref(in string aPrefName, in boolean aValue);
   /**
    * Called to get the state of an individual floating-point preference.
    * "Floating point" preferences are really string preferences that
    * are converted to floating point numbers.
    *
    * @param aPrefName The floating point preference to get the state of.
    *
    * @return float  The value of the requested floating point preference.
    *
    * @see setCharPref
    */
   float getFloatPref(in string aPrefName);
   /**
    * Called to get the state of an individual string preference.
    *
    * @param aPrefName The string preference to retrieve.
    *
    * @return string   The value of the requested string preference.
    *
    * @see setCharPref
    */
   string getCharPref(in string aPrefName);
   /**
    * Called to set the state of an individual string preference.
    *
    * @param aPrefName The string preference to set.
    * @param aValue    The string value to set the preference to.
    *
    * @throws Error if setting failed or the preference has a default
              value of a type other than string.
    *
    * @see getCharPref
    */
   void setCharPref(in string aPrefName, in string aValue);
   /**
    * Called to get the state of an individual integer preference.
    *
    * @param aPrefName The integer preference to get the value of.
    *
    * @return long     The value of the requested integer preference.
    *
    * @see setIntPref
    */
   long getIntPref(in string aPrefName);
   /**
    * Called to set the state of an individual integer preference.
    *
    * @param aPrefName The integer preference to set the value of.
    * @param aValue    The integer value to set the preference to.
    *
    * @throws Error if setting failed or the preference has a default
              value of a type other than integer.
    *
    * @see getIntPref
    */
   void setIntPref(in string aPrefName, in long aValue);
   /**
    * Called to get the state of an individual complex preference. A complex
    * preference is a preference which represents an XPCOM object that can not
    * be easily represented using a standard boolean, integer or string value.
    *
    * @param aPrefName The complex preference to get the value of.
    * @param aType     The XPCOM interface that this complex preference
    *                  represents. Interfaces currently supported are:
    *                    - nsIFile
    *                    - nsISupportsString (UniChar)
    *                    - nsIPrefLocalizedString (Localized UniChar)
    * @param aValue    The XPCOM object into which to the complex preference
    *                  value should be retrieved.
    *
    * @throws Error The value does not exist or is the wrong type.
    *
    * @see setComplexValue
    */
   void getComplexValue(in string aPrefName, in nsIIDRef aType,
                        [iid_is(aType), retval] out nsQIResult aValue);
   /**
    * Called to set the state of an individual complex preference. A complex
    * preference is a preference which represents an XPCOM object that can not
    * be easily represented using a standard boolean, integer or string value.
    *
    * @param aPrefName The complex preference to set the value of.
    * @param aType     The XPCOM interface that this complex preference
    *                  represents. Interfaces currently supported are:
    *                    - nsIFile
    *                    - nsISupportsString (UniChar)
    *                    - nsIPrefLocalizedString (Localized UniChar)
    * @param aValue    The XPCOM object from which to set the complex preference
    *                  value.
    *
    * @throws Error if setting failed or the value is the wrong type.
    *
    * @see getComplexValue
    */
   void setComplexValue(in string aPrefName, in nsIIDRef aType, in nsISupports aValue);
   /**
    * Called to clear a user set value from a specific preference. This will, in
    * effect, reset the value to the default value. If no default value exists
    * the preference will cease to exist.
    *
    * @param aPrefName The preference to be cleared.
    *
    * @note
    * This method does nothing if this object is a default branch.
    */
   void clearUserPref(in string aPrefName);
   /**
    * Called to lock a specific preference. Locking a preference will cause the
    * preference service to always return the default value regardless of
    * whether there is a user set value or not.
    *
    * @param aPrefName The preference to be locked.
    *
    * @note
    * This method can be called on either a default or user branch but, in
    * effect, always operates on the default branch.
    *
    * @throws Error The preference does not exist or an error occurred.
    *
    * @see unlockPref
    */
   void lockPref(in string aPrefName);
   /**
    * Called to check if a specific preference has a user value associated to
    * it.
    *
    * @param aPrefName The preference to be tested.
    *
    * @note
    * This method can be called on either a default or user branch but, in
    * effect, always operates on the user branch.
    *
    * @note
    * If a preference was manually set to a value that equals the default value,
    * then the preference no longer has a user set value, i.e. it is
    * considered reset to its default value.
    * In particular, this method will return false for such a preference and
    * the preference will not be saved to a file by nsIPrefService.savePrefFile.
    *
    * @return boolean  true  The preference has a user set value.
    *                  false The preference only has a default value.
    */
   boolean prefHasUserValue(in string aPrefName);
   /**
    * Called to check if a specific preference is locked. If a preference is
    * locked calling its Get method will always return the default value.
    *
    * @param aPrefName The preference to be tested.
    *
    * @note
    * This method can be called on either a default or user branch but, in
    * effect, always operates on the default branch.
    *
    * @return boolean  true  The preference is locked.
    *                  false The preference is not locked.
    *
    * @see lockPref
    * @see unlockPref
    */
   boolean prefIsLocked(in string aPrefName);
   /**
    * Called to unlock a specific preference. Unlocking a previously locked
    * preference allows the preference service to once again return the user set
    * value of the preference.
    *
    * @param aPrefName The preference to be unlocked.
    *
    * @note
    * This method can be called on either a default or user branch but, in
    * effect, always operates on the default branch.
    *
    * @throws Error The preference does not exist or an error occurred.
    *
    * @see lockPref
    */
   void    unlockPref(in string aPrefName);
   /**
    * Called to remove all of the preferences referenced by this branch.
    *
    * @param aStartingAt The point on the branch at which to start the deleting
    *                    preferences. Pass in "" to remove all preferences
    *                    referenced by this branch.
    *
    * @note
    * This method can be called on either a default or user branch but, in
    * effect, always operates on both.
    *
    * @throws Error The preference(s) do not exist or an error occurred.
    */
   void deleteBranch(in string aStartingAt);
   /**
    * Returns an array of strings representing the child preferences of the
    * root of this branch.
    *
    * @param aStartingAt The point on the branch at which to start enumerating
    *                    the child preferences. Pass in "" to enumerate all
    *                    preferences referenced by this branch.
    * @param aCount      Receives the number of elements in the array.
    * @param aChildArray Receives the array of child preferences.
    *
    * @note
    * This method can be called on either a default or user branch but, in
    * effect, always operates on both.
    *
    * @throws Error The preference(s) do not exist or an error occurred.
    */
   void getChildList(in string aStartingAt,
                     [optional] out unsigned long aCount,
                     [array, size_is(aCount), retval] out string aChildArray);
   /**
    * Called to reset all of the preferences referenced by this branch to their
    * default values.
    *
    * @param aStartingAt The point on the branch at which to start the resetting
    *                    preferences to their default values. Pass in "" to
    *                    reset all preferences referenced by this branch.
    *
    * @note
    * This method can be called on either a default or user branch but, in
    * effect, always operates on the user branch.
    *
    * @throws Error The preference(s) do not exist or an error occurred.
    */
   void resetBranch(in string aStartingAt);
   /**
    * Add a preference change observer. On preference changes, the following
    * arguments will be passed to the nsIObserver.observe() method:
    *   aSubject - The nsIPrefBranch object (this)
    *   aTopic   - The string defined by NS_PREFBRANCH_PREFCHANGE_TOPIC_ID
    *   aData    - The name of the preference which has changed, relative to
    *              the |root| of the aSubject branch.
    *
    * aSubject.get*Pref(aData) will get the new value of the modified
    * preference. For example, if your observer is registered with
    * addObserver("bar.", ...) on a branch with root "foo.", modifying
    * the preference "foo.bar.baz" will trigger the observer, and aData
    * parameter will be "bar.baz".
    *
    * @param aDomain   The preference on which to listen for changes. This can
    *                  be the name of an entire branch to observe.
    *                  e.g. Holding the "root" prefbranch and calling
    *                  addObserver("foo.bar.", ...) will observe changes to
    *                  foo.bar.baz and foo.bar.bzip
    * @param aObserver The object to be notified if the preference changes.
    * @param aHoldWeak true  Hold a weak reference to |aObserver|. The object
    *                        must implement the nsISupportsWeakReference
    *                        interface or this will fail.
    *                  false Hold a strong reference to |aObserver|.
    *
    * @note
    * Registering as a preference observer can open an object to potential
    * cyclical references which will cause memory leaks. These cycles generally
    * occur because an object both registers itself as an observer (causing the
    * branch to hold a reference to the observer) and holds a reference to the
    * branch object for the purpose of getting/setting preference values. There
    * are 3 approaches which have been implemented in an attempt to avoid these
    * situations.
    * 1) The nsPrefBranch object supports nsISupportsWeakReference. Any consumer
    *    may hold a weak reference to it instead of a strong one.
    * 2) The nsPrefBranch object listens for xpcom-shutdown and frees all of the
    *    objects currently in its observer list. This ensures that long lived
    *    objects (services for example) will be freed correctly.
    * 3) The observer can request to be held as a weak reference when it is
    *    registered. This insures that shorter lived objects (say one tied to an
    *    open window) will not fall into the cyclical reference trap.
    *
    * @note
    * The list of registered observers may be changed during the dispatch of
    * nsPref:changed notification. However, the observers are not guaranteed
    * to be notified in any particular order, so you can't be sure whether the
    * added/removed observer will be called during the notification when it
    * is added/removed.
    *
    * @note
    * It is possible to change preferences during the notification.
    *
    * @note
    * It is not safe to change observers during this callback in Gecko
    * releases before 1.9. If you want a safe way to remove a pref observer,
    * please use an nsITimer.
    *
    * @see nsIObserver
    * @see removeObserver
    */
   void addObserver(in string aDomain, in nsIObserver aObserver,
                    in boolean aHoldWeak);
   /**
    * Remove a preference change observer.
    *
    * @param aDomain   The preference which is being observed for changes.
    * @param aObserver An observer previously registered with addObserver().
    *
    * @note
    * Note that you must call removeObserver() on the same nsIPrefBranch
    * instance on which you called addObserver() in order to remove aObserver;
    * otherwise, the observer will not be removed.
    *
    * @see nsIObserver
    * @see addObserver
    */
   void removeObserver(in string aDomain, in nsIObserver aObserver);
 };
 %{C++
 #define NS_PREFBRANCH_CONTRACTID "@mozilla.org/preferencesbranch;1"
 /**
  * Notification sent when a preference changes.
  */
 #define NS_PREFBRANCH_PREFCHANGE_TOPIC_ID "nsPref:changed"
 %}

The Tor Browser / annotate

modules/libpref/public/nsIPrefBranch.idl@b8a032363ba2 (annotated)

modules/libpref/public/nsIPrefBranch.idl