The Tor Browser / file revision

 /* 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;

 };