The Tor Browser: dom/interfaces/base/nsIContentPrefService.idl@b8a032363ba2 (annotated)

dom/interfaces/base/nsIContentPrefService.idl@b8a032363ba2 (annotated)

dom/interfaces/base/nsIContentPrefService.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

 /* 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 nsIVariant;
 interface nsIPropertyBag2;
 interface nsIContentURIGrouper;
 interface nsILoadContext;
 interface mozIStorageConnection;
 [scriptable, uuid(746c7a02-f6c1-4869-b434-7c8b86e60e61)]
 interface nsIContentPrefObserver : nsISupports
 {
   /**
    * Called when a content pref is set to a different value.
    *
    * @param    aGroup      the group to which the pref belongs, or null
    *                       if it's a global pref (applies to all sites)
    * @param    aName       the name of the pref that was set
    * @param    aValue      the new value of the pref
    */
   void onContentPrefSet(in AString aGroup, in AString aName, in nsIVariant aValue);
   /**
    * Called when a content pref is removed.
    *
    * @param    aGroup      the group to which the pref belongs, or null
    *                       if it's a global pref (applies to all sites)
    * @param    aName       the name of the pref that was removed
    */
   void onContentPrefRemoved(in AString aGroup, in AString aName);
 };
 [scriptable, function, uuid(c1b3d6df-5373-4606-8494-8bcf14a7fc62)]
 interface nsIContentPrefCallback : nsISupports
 {
   void onResult(in nsIVariant aResult);
 };
 /**
  * @deprecated Please use nsIContentPrefService2 instead.
  */
 [scriptable, uuid(e3f772f3-023f-4b32-b074-36cf0fd5d414)]
 interface nsIContentPrefService : nsISupports
 {
   /**
    * Get a pref.
    *
    * Besides the regular string, integer, boolean, etc. values, this method
    * may return null (nsIDataType::VTYPE_EMPTY), which means the pref is set
    * to NULL in the database, as well as undefined (nsIDataType::VTYPE_VOID),
    * which means there is no record for this pref in the database.
    *
    * This method can be called from content processes in electrolysis builds.
    * We have a whitelist of values that can be read in such a way.
    *
    * @param    aGroup      the group for which to get the pref, as an nsIURI
    *                       from which the hostname will be used, a string
    *                       (typically in the format of a hostname), or null
    *                       to get the global pref (applies to all sites)
    * @param    aName       the name of the pref to get
    * @param    aPrivacyContext
    *                       a context from which to determine the privacy status
    *                       of the pref (ie. whether to search in memory or in
    *                       permanent storage for it), obtained from a relevant
    *                       window or channel.
    * @param    aCallback   an optional nsIContentPrefCallback to receive the
    *                       result. If desired, JavaScript callers can instead
    *                       provide a function to call upon completion
    *
    * @returns  the value of the pref
    * @throws   NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null
    * @throws   NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
    */
   nsIVariant getPref(in nsIVariant aGroup, in AString aName,
                      in nsILoadContext aPrivacyContext,
                      [optional] in nsIContentPrefCallback aCallback);
   /**
    * Set a pref.
    *
    * This method can be called from content processes in electrolysis builds.
    * We have a whitelist of values that can be set in such a way.
    *
    * @param    aGroup      the group for which to set the pref, as an nsIURI
    *                       from which the hostname will be used, a string
    *                       (typically in the format of a hostname), or null
    *                       to set the global pref (applies to all sites)
    * @param    aName       the name of the pref to set
    * @param    aValue      the new value of the pref
    * @param    aPrivacyContext
    *                       a context from which to determine the privacy status
    *                       of the pref (ie. whether to store it in memory or in
    *                       permanent storage), obtained from a relevant
    *                       window or channel.
    * @throws   NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null
    * @throws   NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
    */
   void setPref(in nsIVariant aGroup, in AString aName, in nsIVariant aValue, in nsILoadContext aPrivacyContext);
   /**
    * Check whether or not a pref exists.
    *
    * @param    aGroup      the group for which to check for the pref, as an nsIURI
    *                       from which the hostname will be used, a string
    *                       (typically in the format of a hostname), or null
    *                       to check for the global pref (applies to all sites)
    * @param    aName       the name of the pref to check for
    * @param    aPrivacyContext
    *                       a context from which to determine the privacy status
    *                       of the pref (ie. whether to search in memory or in
    *                       permanent storage for it), obtained from a relevant
    *                       window or channel.
    * @throws   NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null
    * @throws   NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
    */
   boolean hasPref(in nsIVariant aGroup, in AString aName, in nsILoadContext aContext);
   /**
    * Check whether or not the value of a pref (or its non-existance) is cached.
    *
    * @param    aGroup      the group for which to check for the pref, as an nsIURI
    *                       from which the hostname will be used, a string
    *                       (typically in the format of a hostname), or null
    *                       to check for the global pref (applies to all sites)
    * @param    aName       the name of the pref to check for
    * @param    aPrivacyContext
    *                       a context from which to determine the privacy status
    *                       of the pref (ie. whether to search in memory or in
    *                       permanent storage for it), obtained from a relevant
    *                       window or channel.
    * @throws   NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null
    * @throws   NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
    */
   boolean hasCachedPref(in nsIVariant aGroup, in AString aName, in nsILoadContext aContext);
   /**
    * Remove a pref.
    *
    * @param    aGroup      the group for which to remove the pref, as an nsIURI
    *                       from which the hostname will be used, a string
    *                       (typically in the format of a hostname), or null
    *                       to remove the global pref (applies to all sites)
    * @param    aName       the name of the pref to remove
    * @param    aPrivacyContext
    *                       a context from which to determine the privacy status
    *                       of the pref (ie. whether to search in memory or in
    *                       permanent storage for it), obtained from a relevant
    *                       window or channel.
    * @throws   NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null
    * @throws   NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
    */
   void removePref(in nsIVariant aGroup, in AString aName, in nsILoadContext aContext);
   /**
    * Remove all grouped prefs.  Useful for removing references to the sites
    * the user has visited when the user clears their private data.
    *
    * @param    aPrivacyContext
    *                       a context from which to determine the privacy status
    *                       of the pref (ie. whether to remove prefs in memory or
    *                       in permanent storage), obtained from a relevant
    *                       window or channel.
    */
   void removeGroupedPrefs(in nsILoadContext aContext);
   /**
    * Remove all prefs with the given name.
    *
    * @param    aName        the setting name for which to remove prefs
    * @param    aPrivacyContext
    *                        a context from which to determine the privacy status
    *                        of the prefs (ie. whether to remove prefs in memory or
    *                        in permanent storage), obtained from a relevant
    *                        window or channel.
    * @throws   NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
    */
   void removePrefsByName(in AString aName, in nsILoadContext aContext);
   /**
    * Get the prefs that apply to the given site.
    *
    * @param    aGroup      the group for which to retrieve prefs, as an nsIURI
    *                       from which the hostname will be used, a string
    *                       (typically in the format of a hostname), or null
    *                       to get the global prefs (apply to all sites)
    * @param    aPrivacyContext
    *                       a context from which to determine the privacy status
    *                       of the pref (ie. whether to search for prefs in memory
    *                       or in permanent storage), obtained from a relevant
    *                       window or channel.
    *
    * @returns  a property bag of prefs
    * @throws   NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null
    */
   nsIPropertyBag2 getPrefs(in nsIVariant aGroup, in nsILoadContext aContext);
   /**
    * Get the prefs with the given name.
    *
    * @param    aName        the setting name for which to retrieve prefs
    * @param    aPrivacyContext
    *                        a context from which to determine the privacy status
    *                        of the pref (ie. whether to search for prefs in memory
    *                        or in permanent storage), obtained from a relevant
    *                        window or channel.
    *
    * @returns  a property bag of prefs
    * @throws   NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
    */
   nsIPropertyBag2 getPrefsByName(in AString aName, in nsILoadContext aContext);
   /**
    * Add an observer.
    *
    * @param    aName       the setting to observe, or null to add
    *                       a generic observer that observes all settings
    * @param    aObserver   the observer to add
    */
   void addObserver(in AString aName, in nsIContentPrefObserver aObserver);
   /**
    * Remove an observer.
    *
    * @param    aName       the setting being observed, or null to remove
    *                       a generic observer that observes all settings
    * @param    aObserver   the observer to remove
    */
   void removeObserver(in AString aName, in nsIContentPrefObserver aObserver);
   /**
    * The component that the service uses to determine the groups to which
    * URIs belong.  By default this is the "hostname grouper", which groups
    * URIs by full hostname (a.k.a. site).
    */
   readonly attribute nsIContentURIGrouper grouper;
   /**
    * The database connection to the content preferences database.
    * Useful for accessing and manipulating preferences in ways that are caller-
    * specific or for which there is not yet a generic method, although generic
    * functionality useful to multiple callers should generally be added to this
    * unfrozen interface.  Also useful for testing the database creation
    * and migration code.
    */
   readonly attribute mozIStorageConnection DBConnection;
 };
 %{C++
 // The contractID for the generic implementation built in to xpcom.
 #define NS_CONTENT_PREF_SERVICE_CONTRACTID "@mozilla.org/content-pref/service;1"
 %}

The Tor Browser / annotate

dom/interfaces/base/nsIContentPrefService.idl@b8a032363ba2 (annotated)

dom/interfaces/base/nsIContentPrefService.idl