diff -r 000000000000 -r 6474c204b198 dom/interfaces/base/nsIContentPrefService.idl --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/dom/interfaces/base/nsIContentPrefService.idl Wed Dec 31 06:09:35 2014 +0100 @@ -0,0 +1,254 @@ +/* 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 nsIPropertyBag2; +interface nsIContentURIGrouper; +interface nsILoadContext; +interface mozIStorageConnection; + +[scriptable, uuid(746c7a02-f6c1-4869-b434-7c8b86e60e61)] +interface nsIContentPrefObserver : nsISupports +{ + /** + * Called when a content pref is set to a different value. + * + * @param aGroup the group to which the pref belongs, or null + * if it's a global pref (applies to all sites) + * @param aName the name of the pref that was set + * @param aValue the new value of the pref + */ + void onContentPrefSet(in AString aGroup, in AString aName, in nsIVariant aValue); + + /** + * Called when a content pref is removed. + * + * @param aGroup the group to which the pref belongs, or null + * if it's a global pref (applies to all sites) + * @param aName the name of the pref that was removed + */ + void onContentPrefRemoved(in AString aGroup, in AString aName); +}; + +[scriptable, function, uuid(c1b3d6df-5373-4606-8494-8bcf14a7fc62)] +interface nsIContentPrefCallback : nsISupports +{ + void onResult(in nsIVariant aResult); +}; + +/** + * @deprecated Please use nsIContentPrefService2 instead. + */ +[scriptable, uuid(e3f772f3-023f-4b32-b074-36cf0fd5d414)] +interface nsIContentPrefService : nsISupports +{ + /** + * Get a pref. + * + * Besides the regular string, integer, boolean, etc. values, this method + * may return null (nsIDataType::VTYPE_EMPTY), which means the pref is set + * to NULL in the database, as well as undefined (nsIDataType::VTYPE_VOID), + * which means there is no record for this pref in the database. + * + * This method can be called from content processes in electrolysis builds. + * We have a whitelist of values that can be read in such a way. + * + * @param aGroup the group for which to get the pref, as an nsIURI + * from which the hostname will be used, a string + * (typically in the format of a hostname), or null + * to get the global pref (applies to all sites) + * @param aName the name of the pref to get + * @param aPrivacyContext + * a context from which to determine the privacy status + * of the pref (ie. whether to search in memory or in + * permanent storage for it), obtained from a relevant + * window or channel. + * @param aCallback an optional nsIContentPrefCallback to receive the + * result. If desired, JavaScript callers can instead + * provide a function to call upon completion + * + * @returns the value of the pref + * @throws NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null + * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string + */ + nsIVariant getPref(in nsIVariant aGroup, in AString aName, + in nsILoadContext aPrivacyContext, + [optional] in nsIContentPrefCallback aCallback); + + /** + * Set a pref. + * + * This method can be called from content processes in electrolysis builds. + * We have a whitelist of values that can be set in such a way. + * + * @param aGroup the group for which to set the pref, as an nsIURI + * from which the hostname will be used, a string + * (typically in the format of a hostname), or null + * to set the global pref (applies to all sites) + * @param aName the name of the pref to set + * @param aValue the new value of the pref + * @param aPrivacyContext + * a context from which to determine the privacy status + * of the pref (ie. whether to store it in memory or in + * permanent storage), obtained from a relevant + * window or channel. + * @throws NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null + * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string + */ + void setPref(in nsIVariant aGroup, in AString aName, in nsIVariant aValue, in nsILoadContext aPrivacyContext); + + /** + * Check whether or not a pref exists. + * + * @param aGroup the group for which to check for the pref, as an nsIURI + * from which the hostname will be used, a string + * (typically in the format of a hostname), or null + * to check for the global pref (applies to all sites) + * @param aName the name of the pref to check for + * @param aPrivacyContext + * a context from which to determine the privacy status + * of the pref (ie. whether to search in memory or in + * permanent storage for it), obtained from a relevant + * window or channel. + * @throws NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null + * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string + */ + boolean hasPref(in nsIVariant aGroup, in AString aName, in nsILoadContext aContext); + + /** + * Check whether or not the value of a pref (or its non-existance) is cached. + * + * @param aGroup the group for which to check for the pref, as an nsIURI + * from which the hostname will be used, a string + * (typically in the format of a hostname), or null + * to check for the global pref (applies to all sites) + * @param aName the name of the pref to check for + * @param aPrivacyContext + * a context from which to determine the privacy status + * of the pref (ie. whether to search in memory or in + * permanent storage for it), obtained from a relevant + * window or channel. + * @throws NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null + * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string + */ + boolean hasCachedPref(in nsIVariant aGroup, in AString aName, in nsILoadContext aContext); + + /** + * Remove a pref. + * + * @param aGroup the group for which to remove the pref, as an nsIURI + * from which the hostname will be used, a string + * (typically in the format of a hostname), or null + * to remove the global pref (applies to all sites) + * @param aName the name of the pref to remove + * @param aPrivacyContext + * a context from which to determine the privacy status + * of the pref (ie. whether to search in memory or in + * permanent storage for it), obtained from a relevant + * window or channel. + * @throws NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null + * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string + */ + void removePref(in nsIVariant aGroup, in AString aName, in nsILoadContext aContext); + + /** + * Remove all grouped prefs. Useful for removing references to the sites + * the user has visited when the user clears their private data. + * + * @param aPrivacyContext + * a context from which to determine the privacy status + * of the pref (ie. whether to remove prefs in memory or + * in permanent storage), obtained from a relevant + * window or channel. + */ + void removeGroupedPrefs(in nsILoadContext aContext); + + /** + * Remove all prefs with the given name. + * + * @param aName the setting name for which to remove prefs + * @param aPrivacyContext + * a context from which to determine the privacy status + * of the prefs (ie. whether to remove prefs in memory or + * in permanent storage), obtained from a relevant + * window or channel. + * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string + */ + void removePrefsByName(in AString aName, in nsILoadContext aContext); + + /** + * Get the prefs that apply to the given site. + * + * @param aGroup the group for which to retrieve prefs, as an nsIURI + * from which the hostname will be used, a string + * (typically in the format of a hostname), or null + * to get the global prefs (apply to all sites) + * @param aPrivacyContext + * a context from which to determine the privacy status + * of the pref (ie. whether to search for prefs in memory + * or in permanent storage), obtained from a relevant + * window or channel. + * + * @returns a property bag of prefs + * @throws NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null + */ + nsIPropertyBag2 getPrefs(in nsIVariant aGroup, in nsILoadContext aContext); + + /** + * Get the prefs with the given name. + * + * @param aName the setting name for which to retrieve prefs + * @param aPrivacyContext + * a context from which to determine the privacy status + * of the pref (ie. whether to search for prefs in memory + * or in permanent storage), obtained from a relevant + * window or channel. + * + * @returns a property bag of prefs + * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string + */ + nsIPropertyBag2 getPrefsByName(in AString aName, in nsILoadContext aContext); + + /** + * Add an observer. + * + * @param aName the setting to observe, or null to add + * a generic observer that observes all settings + * @param aObserver the observer to add + */ + void addObserver(in AString aName, in nsIContentPrefObserver aObserver); + + /** + * Remove an observer. + * + * @param aName the setting being observed, or null to remove + * a generic observer that observes all settings + * @param aObserver the observer to remove + */ + void removeObserver(in AString aName, in nsIContentPrefObserver aObserver); + + /** + * The component that the service uses to determine the groups to which + * URIs belong. By default this is the "hostname grouper", which groups + * URIs by full hostname (a.k.a. site). + */ + readonly attribute nsIContentURIGrouper grouper; + + /** + * The database connection to the content preferences database. + * Useful for accessing and manipulating preferences in ways that are caller- + * specific or for which there is not yet a generic method, although generic + * functionality useful to multiple callers should generally be added to this + * unfrozen interface. Also useful for testing the database creation + * and migration code. + */ + readonly attribute mozIStorageConnection DBConnection; +}; + +%{C++ +// The contractID for the generic implementation built in to xpcom. +#define NS_CONTENT_PREF_SERVICE_CONTRACTID "@mozilla.org/content-pref/service;1" +%}