summaryrefslogtreecommitdiffstats
path: root/dom/interfaces/base/nsIContentPrefService2.idl
diff options
context:
space:
mode:
authorMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
committerMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
commit5f8de423f190bbb79a62f804151bc24824fa32d8 (patch)
tree10027f336435511475e392454359edea8e25895d /dom/interfaces/base/nsIContentPrefService2.idl
parent49ee0794b5d912db1f95dce6eb52d781dc210db5 (diff)
downloadUXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.gz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.lz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.xz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.zip
Add m-esr52 at 52.6.0
Diffstat (limited to 'dom/interfaces/base/nsIContentPrefService2.idl')
-rw-r--r--dom/interfaces/base/nsIContentPrefService2.idl405
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;
+};