/* 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" %}