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