diff options
Diffstat (limited to 'dom/interfaces/base/nsIContentPrefService.idl')
| -rw-r--r-- | dom/interfaces/base/nsIContentPrefService.idl | 263 |
1 files changed, 263 insertions, 0 deletions
diff --git a/dom/interfaces/base/nsIContentPrefService.idl b/dom/interfaces/base/nsIContentPrefService.idl new file mode 100644 index 000000000..9c3cf3665 --- /dev/null +++ b/dom/interfaces/base/nsIContentPrefService.idl @@ -0,0 +1,263 @@ +/* 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(43635c53-b445-4c4e-8cc5-562697299b55)] +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 + * @param aIsPrivate an optional flag determining whether the + * original context is private or not + */ + void onContentPrefSet(in AString aGroup, + in AString aName, + in nsIVariant aValue, + [optional] in boolean aIsPrivate); + + /** + * 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 + * @param aIsPrivate an optional flag determining whether the + * original context is private or not + */ + void onContentPrefRemoved(in AString aGroup, + in AString aName, + [optional] in boolean aIsPrivate); +}; + +[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" +%} |