nsIContentPrefService2.idl
/* 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;
};
