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

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

dom/interfaces/base/nsIContentPrefService2.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 nsIContentPrefObserver;
 interface nsIContentPrefCallback2;
 interface nsILoadContext;
 interface nsIContentPref;
 /**
  * Content Preferences
  *
  * Content preferences allow the application to associate arbitrary data, or
  * "preferences", with specific domains, or web "content".  Specifically, a
  * content preference is a structure with three values: a domain with which the
  * preference is associated, a name that identifies the preference within its
  * domain, and a value.  (See nsIContentPref below.)
  *
  * For example, if you want to remember the user's preference for a certain zoom
  * level on www.mozilla.org pages, you might store a preference whose domain is
  * "www.mozilla.org", whose name is "zoomLevel", and whose value is the numeric
  * zoom level.
  *
  * A preference need not have a domain, and in that case the preference is
  * called a "global" preference.  This interface doesn't impart any special
  * significance to global preferences; they're simply name-value pairs that
  * aren't associated with any particular domain.  As a consumer of this
  * interface, you might choose to let a global preference override all non-
  * global preferences of the same name, for example, for whatever definition of
  * "override" is appropriate for your use case.
  *
  *
  * Domain Parameters
  *
  * Many methods of this interface accept a "domain" parameter.  Domains may be
  * specified either exactly, like "example.com", or as full URLs, like
  * "http://example.com/foo/bar".  In the latter case the API extracts the full
  * domain from the URL, so if you specify "http://foo.bar.example.com/baz", the
  * domain is taken to be "foo.bar.example.com", not "example.com".
  *
  *
  * Private-Browsing Context Parameters
  *
  * Many methods also accept a "context" parameter.  This parameter relates to
  * private browsing and determines the kind of storage that a method uses,
  * either the usual permanent storage or temporary storage set aside for private
  * browsing sessions.
  *
  * Pass null to unconditionally use permanent storage.  Pass an nsILoadContext
  * to use storage appropriate to the context's usePrivateBrowsing attribute: if
  * usePrivateBrowsing is true, temporary private-browsing storage is used, and
  * otherwise permanent storage is used.  A context can be obtained from the
  * window or channel whose content pertains to the preferences being modified or
  * retrieved.
  *
  *
  * Callbacks
  *
  * The methods of callback objects are always called asynchronously.
  *
  * Observers are called after callbacks are called, but they are called in the
  * same turn of the event loop as callbacks.
  *
  * See nsIContentPrefCallback2 below for more information about callbacks.
  */
 [scriptable, uuid(f2507add-dc39-48e0-9147-e0270376148b)]
 interface nsIContentPrefService2 : nsISupports
 {
   /**
    * Gets all the preferences with the given name.
    *
    * @param name      The preferences' name.
    * @param context   The private-browsing context, if any.
    * @param callback  handleResult is called once for each preference unless
    *                  no such preferences exist, in which case handleResult
    *                  is not called at all.
    */
   void getByName(in AString name,
                  in nsILoadContext context,
                  in nsIContentPrefCallback2 callback);
   /**
    * Gets the preference with the given domain and name.
    *
    * @param domain    The preference's domain.
    * @param name      The preference's name.
    * @param context   The private-browsing context, if any.
    * @param callback  handleResult is called once unless no such preference
    *                  exists, in which case handleResult is not called at all.
    */
   void getByDomainAndName(in AString domain,
                           in AString name,
                           in nsILoadContext context,
                           in nsIContentPrefCallback2 callback);
   /**
    * Gets all preferences with the given name whose domains are either the same
    * as or subdomains of the given domain.
    *
    * @param domain    The preferences' domain.
    * @param name      The preferences' name.
    * @param context   The private-browsing context, if any.
    * @param callback  handleResult is called once for each preference.  If no
    *                  such preferences exist, handleResult is not called at all.
    */
   void getBySubdomainAndName(in AString domain,
                              in AString name,
                              in nsILoadContext context,
                              in nsIContentPrefCallback2 callback);
   /**
    * Gets the preference with no domain and the given name.
    *
    * @param name      The preference's name.
    * @param context   The private-browsing context, if any.
    * @param callback  handleResult is called once unless no such preference
    *                  exists, in which case handleResult is not called at all.
    */
   void getGlobal(in AString name,
                  in nsILoadContext context,
                  in nsIContentPrefCallback2 callback);
   /**
    * Synchronously retrieves from the in-memory cache the preference with the
    * given domain and name.
    *
    * In addition to caching preference values, the cache also keeps track of
    * preferences that are known not to exist.  If the preference is known not to
    * exist, the value attribute of the returned object will be undefined
    * (nsIDataType::VTYPE_VOID).
    *
    * If the preference is neither cached nor known not to exist, then null is
    * returned, and get() must be called to determine whether the preference
    * exists.
    *
    * @param domain   The preference's domain.
    * @param name     The preference's name.
    * @param context  The private-browsing context, if any.
    * @return         The preference, or null if no such preference is known to
    *                 exist.
    */
   nsIContentPref getCachedByDomainAndName(in AString domain,
                                           in AString name,
                                           in nsILoadContext context);
   /**
    * Synchronously retrieves from the in-memory cache all preferences with the
    * given name whose domains are either the same as or subdomains of the given
    * domain.
    *
    * The preferences are returned in an array through the out-parameter.  If a
    * preference for a particular subdomain is known not to exist, then an object
    * corresponding to that preference will be present in the array, and, as with
    * getCachedByDomainAndName, its value attribute will be undefined.
    *
    * @param domain   The preferences' domain.
    * @param name     The preferences' name.
    * @param context  The private-browsing context, if any.
    * @param len      The length of the returned array.
    * @param prefs    The array of preferences.
    */
   void getCachedBySubdomainAndName(in AString domain,
                                    in AString name,
                                    in nsILoadContext context,
                                    [optional] out unsigned long len,
                                    [retval,array,size_is(len)] out nsIContentPref prefs);
   /**
    * Synchronously retrieves from the in-memory cache the preference with no
    * domain and the given name.
    *
    * As with getCachedByDomainAndName, if the preference is cached then it is
    * returned; if the preference is known not to exist, then the value attribute
    * of the returned object will be undefined; if the preference is neither
    * cached nor known not to exist, then null is returned.
    *
    * @param name     The preference's name.
    * @param context  The private-browsing context, if any.
    * @return         The preference, or null if no such preference is known to
    *                 exist.
    */
   nsIContentPref getCachedGlobal(in AString name,
                                  in nsILoadContext context);
   /**
    * Sets a preference.
    *
    * @param domain    The preference's domain.
    * @param name      The preference's name.
    * @param value     The preference's value.
    * @param context   The private-browsing context, if any.
    * @param callback  handleCompletion is called when the preference has been
    *                  stored.
    */
   void set(in AString domain,
            in AString name,
            in nsIVariant value,
            in nsILoadContext context,
            [optional] in nsIContentPrefCallback2 callback);
   /**
    * Sets a preference with no domain.
    *
    * @param name      The preference's name.
    * @param value     The preference's value.
    * @param context   The private-browsing context, if any.
    * @param callback  handleCompletion is called when the preference has been
    *                  stored.
    */
   void setGlobal(in AString name,
                  in nsIVariant value,
                  in nsILoadContext context,
                  [optional] in nsIContentPrefCallback2 callback);
   /**
    * Removes the preference with the given domain and name.
    *
    * @param domain    The preference's domain.
    * @param name      The preference's name.
    * @param context   The private-browsing context, if any.
    * @param callback  handleCompletion is called when the operation completes.
    */
   void removeByDomainAndName(in AString domain,
                              in AString name,
                              in nsILoadContext context,
                              [optional] in nsIContentPrefCallback2 callback);
   /**
    * Removes all the preferences with the given name whose domains are either
    * the same as or subdomains of the given domain.
    *
    * @param domain    The preferences' domain.
    * @param name      The preferences' name.
    * @param context   The private-browsing context, if any.
    * @param callback  handleCompletion is called when the operation completes.
    */
   void removeBySubdomainAndName(in AString domain,
                                 in AString name,
                                 in nsILoadContext context,
                                 [optional] in nsIContentPrefCallback2 callback);
   /**
    * Removes the preference with no domain and the given name.
    *
    * @param name      The preference's name.
    * @param context   The private-browsing context, if any.
    * @param callback  handleCompletion is called when the operation completes.
    */
   void removeGlobal(in AString name,
                     in nsILoadContext context,
                     [optional] in nsIContentPrefCallback2 callback);
   /**
    * Removes all preferences with the given domain.
    *
    * @param domain    The preferences' domain.
    * @param context   The private-browsing context, if any.
    * @param callback  handleCompletion is called when the operation completes.
    */
   void removeByDomain(in AString domain,
                       in nsILoadContext context,
                       [optional] in nsIContentPrefCallback2 callback);
   /**
    * Removes all preferences whose domains are either the same as or subdomains
    * of the given domain.
    *
    * @param domain    The preferences' domain.
    * @param context   The private-browsing context, if any.
    * @param callback  handleCompletion is called when the operation completes.
    */
   void removeBySubdomain(in AString domain,
                          in nsILoadContext context,
                          [optional] in nsIContentPrefCallback2 callback);
   /**
    * Removes all preferences with the given name regardless of domain, including
    * global preferences with the given name.
    *
    * @param name      The preferences' name.
    * @param context   The private-browsing context, if any.
    * @param callback  handleCompletion is called when the operation completes.
    */
   void removeByName(in AString name,
                     in nsILoadContext context,
                     [optional] in nsIContentPrefCallback2 callback);
   /**
    * Removes all non-global preferences -- in other words, all preferences that
    * have a domain.
    *
    * @param context   The private-browsing context, if any.
    * @param callback  handleCompletion is called when the operation completes.
    */
   void removeAllDomains(in nsILoadContext context,
                         [optional] in nsIContentPrefCallback2 callback);
   /**
    * Removes all global preferences -- in other words, all preferences that have
    * no domain.
    *
    * @param context   The private-browsing context, if any.
    * @param callback  handleCompletion is called when the operation completes.
    */
   void removeAllGlobals(in nsILoadContext context,
                         [optional] in nsIContentPrefCallback2 callback);
   /**
    * Registers an observer that will be notified whenever a preference with the
    * given name is set or removed.
    *
    * When a set or remove method is called, observers are called after the set
    * or removal completes and after the method's callback is called, and they
    * are called in the same turn of the event loop as the callback.
    *
    * The service holds a strong reference to the observer, so the observer must
    * be removed later to avoid leaking it.
    *
    * @param name      The name of the preferences to observe.  Pass null to
    *                  observe all preference changes regardless of name.
    * @param observer  The observer.
    */
   void addObserverForName(in AString name,
                           in nsIContentPrefObserver observer);
   /**
    * Unregisters an observer for the given name.
    *
    * @param name      The name for which the observer was registered.  Pass null
    *                  if the observer was added with a null name.
    * @param observer  The observer.
    */
   void removeObserverForName(in AString name,
                              in nsIContentPrefObserver observer);
   /**
    * Extracts and returns the domain from the given string representation of a
    * URI.  This is how the API extracts domains from URIs passed to it.
    *
    * @param str  The string representation of a URI, like
    *             "http://example.com/foo/bar".
    * @return     If the given string is a valid URI, the domain of that URI is
    *             returned.  Otherwise, the string itself is returned.
    */
   AString extractDomain(in AString str);
 };
 /**
  * The callback used by the above methods.
  */
 [scriptable, uuid(1a12cf41-79e8-4d0f-9899-2f7b27c5d9a1)]
 interface nsIContentPrefCallback2 : nsISupports
 {
   /**
    * For the retrieval methods, this is called once for each retrieved
    * preference.  It is not called for other methods.
    *
    * @param pref  The retrieved preference.
    */
   void handleResult(in nsIContentPref pref);
   /**
    * Called when an error occurs.  This may be called multiple times before
    * handleCompletion is called.
    *
    * @param error  A number in Components.results describing the error.
    */
   void handleError(in nsresult error);
   /**
    * Called when the method finishes.  This will be called exactly once for
    * each method invocation, and afterward no other callback methods will be
    * called.
    *
    * @param reason  One of the COMPLETE_* values indicating the manner in which
    *                the method completed.
    */
   void handleCompletion(in unsigned short reason);
   const unsigned short COMPLETE_OK = 0;
   const unsigned short COMPLETE_ERROR = 1;
 };
 [scriptable, function, uuid(9f24948d-24b5-4b1b-b554-7dbd58c1d792)]
 interface nsIContentPref : nsISupports
 {
   readonly attribute AString domain;
   readonly attribute AString name;
   readonly attribute nsIVariant value;
 };

The Tor Browser / annotate

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

dom/interfaces/base/nsIContentPrefService2.idl