Add m-esr52 at 52.6.0

1 files changed, 405 insertions, 0 deletions

diff --git a/dom/interfaces/base/nsIContentPrefService2.idl b/dom/interfaces/base/nsIContentPrefService2.idl
new file mode 100644
index 000000000..4ac1e21d8
--- /dev/null
+++ b/dom/interfaces/base/nsIContentPrefService2.idl
@@ -0,0 +1,405 @@
+/* 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(bed98666-d995-470f-bebd-62476d318576)]
+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 non-global preferences created after and including |since|.
+   *
+   * @param since     Timestamp in milliseconds.
+   * @param context   The private-browsing context, if any.
+   * @param callback  handleCompletion is called when the operation completes.
+   */
+  void removeAllDomainsSince(in unsigned long long since,
+                             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;
+};