1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/dom/interfaces/base/nsIContentPrefService.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,254 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +#include "nsISupports.idl"
1.9 +
1.10 +interface nsIVariant;
1.11 +interface nsIPropertyBag2;
1.12 +interface nsIContentURIGrouper;
1.13 +interface nsILoadContext;
1.14 +interface mozIStorageConnection;
1.15 +
1.16 +[scriptable, uuid(746c7a02-f6c1-4869-b434-7c8b86e60e61)]
1.17 +interface nsIContentPrefObserver : nsISupports
1.18 +{
1.19 + /**
1.20 + * Called when a content pref is set to a different value.
1.21 + *
1.22 + * @param aGroup the group to which the pref belongs, or null
1.23 + * if it's a global pref (applies to all sites)
1.24 + * @param aName the name of the pref that was set
1.25 + * @param aValue the new value of the pref
1.26 + */
1.27 + void onContentPrefSet(in AString aGroup, in AString aName, in nsIVariant aValue);
1.28 +
1.29 + /**
1.30 + * Called when a content pref is removed.
1.31 + *
1.32 + * @param aGroup the group to which the pref belongs, or null
1.33 + * if it's a global pref (applies to all sites)
1.34 + * @param aName the name of the pref that was removed
1.35 + */
1.36 + void onContentPrefRemoved(in AString aGroup, in AString aName);
1.37 +};
1.38 +
1.39 +[scriptable, function, uuid(c1b3d6df-5373-4606-8494-8bcf14a7fc62)]
1.40 +interface nsIContentPrefCallback : nsISupports
1.41 +{
1.42 + void onResult(in nsIVariant aResult);
1.43 +};
1.44 +
1.45 +/**
1.46 + * @deprecated Please use nsIContentPrefService2 instead.
1.47 + */
1.48 +[scriptable, uuid(e3f772f3-023f-4b32-b074-36cf0fd5d414)]
1.49 +interface nsIContentPrefService : nsISupports
1.50 +{
1.51 + /**
1.52 + * Get a pref.
1.53 + *
1.54 + * Besides the regular string, integer, boolean, etc. values, this method
1.55 + * may return null (nsIDataType::VTYPE_EMPTY), which means the pref is set
1.56 + * to NULL in the database, as well as undefined (nsIDataType::VTYPE_VOID),
1.57 + * which means there is no record for this pref in the database.
1.58 + *
1.59 + * This method can be called from content processes in electrolysis builds.
1.60 + * We have a whitelist of values that can be read in such a way.
1.61 + *
1.62 + * @param aGroup the group for which to get the pref, as an nsIURI
1.63 + * from which the hostname will be used, a string
1.64 + * (typically in the format of a hostname), or null
1.65 + * to get the global pref (applies to all sites)
1.66 + * @param aName the name of the pref to get
1.67 + * @param aPrivacyContext
1.68 + * a context from which to determine the privacy status
1.69 + * of the pref (ie. whether to search in memory or in
1.70 + * permanent storage for it), obtained from a relevant
1.71 + * window or channel.
1.72 + * @param aCallback an optional nsIContentPrefCallback to receive the
1.73 + * result. If desired, JavaScript callers can instead
1.74 + * provide a function to call upon completion
1.75 + *
1.76 + * @returns the value of the pref
1.77 + * @throws NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null
1.78 + * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
1.79 + */
1.80 + nsIVariant getPref(in nsIVariant aGroup, in AString aName,
1.81 + in nsILoadContext aPrivacyContext,
1.82 + [optional] in nsIContentPrefCallback aCallback);
1.83 +
1.84 + /**
1.85 + * Set a pref.
1.86 + *
1.87 + * This method can be called from content processes in electrolysis builds.
1.88 + * We have a whitelist of values that can be set in such a way.
1.89 + *
1.90 + * @param aGroup the group for which to set the pref, as an nsIURI
1.91 + * from which the hostname will be used, a string
1.92 + * (typically in the format of a hostname), or null
1.93 + * to set the global pref (applies to all sites)
1.94 + * @param aName the name of the pref to set
1.95 + * @param aValue the new value of the pref
1.96 + * @param aPrivacyContext
1.97 + * a context from which to determine the privacy status
1.98 + * of the pref (ie. whether to store it in memory or in
1.99 + * permanent storage), obtained from a relevant
1.100 + * window or channel.
1.101 + * @throws NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null
1.102 + * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
1.103 + */
1.104 + void setPref(in nsIVariant aGroup, in AString aName, in nsIVariant aValue, in nsILoadContext aPrivacyContext);
1.105 +
1.106 + /**
1.107 + * Check whether or not a pref exists.
1.108 + *
1.109 + * @param aGroup the group for which to check for the pref, as an nsIURI
1.110 + * from which the hostname will be used, a string
1.111 + * (typically in the format of a hostname), or null
1.112 + * to check for the global pref (applies to all sites)
1.113 + * @param aName the name of the pref to check for
1.114 + * @param aPrivacyContext
1.115 + * a context from which to determine the privacy status
1.116 + * of the pref (ie. whether to search in memory or in
1.117 + * permanent storage for it), obtained from a relevant
1.118 + * window or channel.
1.119 + * @throws NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null
1.120 + * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
1.121 + */
1.122 + boolean hasPref(in nsIVariant aGroup, in AString aName, in nsILoadContext aContext);
1.123 +
1.124 + /**
1.125 + * Check whether or not the value of a pref (or its non-existance) is cached.
1.126 + *
1.127 + * @param aGroup the group for which to check for the pref, as an nsIURI
1.128 + * from which the hostname will be used, a string
1.129 + * (typically in the format of a hostname), or null
1.130 + * to check for the global pref (applies to all sites)
1.131 + * @param aName the name of the pref to check for
1.132 + * @param aPrivacyContext
1.133 + * a context from which to determine the privacy status
1.134 + * of the pref (ie. whether to search in memory or in
1.135 + * permanent storage for it), obtained from a relevant
1.136 + * window or channel.
1.137 + * @throws NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null
1.138 + * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
1.139 + */
1.140 + boolean hasCachedPref(in nsIVariant aGroup, in AString aName, in nsILoadContext aContext);
1.141 +
1.142 + /**
1.143 + * Remove a pref.
1.144 + *
1.145 + * @param aGroup the group for which to remove the pref, as an nsIURI
1.146 + * from which the hostname will be used, a string
1.147 + * (typically in the format of a hostname), or null
1.148 + * to remove the global pref (applies to all sites)
1.149 + * @param aName the name of the pref to remove
1.150 + * @param aPrivacyContext
1.151 + * a context from which to determine the privacy status
1.152 + * of the pref (ie. whether to search in memory or in
1.153 + * permanent storage for it), obtained from a relevant
1.154 + * window or channel.
1.155 + * @throws NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null
1.156 + * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
1.157 + */
1.158 + void removePref(in nsIVariant aGroup, in AString aName, in nsILoadContext aContext);
1.159 +
1.160 + /**
1.161 + * Remove all grouped prefs. Useful for removing references to the sites
1.162 + * the user has visited when the user clears their private data.
1.163 + *
1.164 + * @param aPrivacyContext
1.165 + * a context from which to determine the privacy status
1.166 + * of the pref (ie. whether to remove prefs in memory or
1.167 + * in permanent storage), obtained from a relevant
1.168 + * window or channel.
1.169 + */
1.170 + void removeGroupedPrefs(in nsILoadContext aContext);
1.171 +
1.172 + /**
1.173 + * Remove all prefs with the given name.
1.174 + *
1.175 + * @param aName the setting name for which to remove prefs
1.176 + * @param aPrivacyContext
1.177 + * a context from which to determine the privacy status
1.178 + * of the prefs (ie. whether to remove prefs in memory or
1.179 + * in permanent storage), obtained from a relevant
1.180 + * window or channel.
1.181 + * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
1.182 + */
1.183 + void removePrefsByName(in AString aName, in nsILoadContext aContext);
1.184 +
1.185 + /**
1.186 + * Get the prefs that apply to the given site.
1.187 + *
1.188 + * @param aGroup the group for which to retrieve prefs, as an nsIURI
1.189 + * from which the hostname will be used, a string
1.190 + * (typically in the format of a hostname), or null
1.191 + * to get the global prefs (apply to all sites)
1.192 + * @param aPrivacyContext
1.193 + * a context from which to determine the privacy status
1.194 + * of the pref (ie. whether to search for prefs in memory
1.195 + * or in permanent storage), obtained from a relevant
1.196 + * window or channel.
1.197 + *
1.198 + * @returns a property bag of prefs
1.199 + * @throws NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null
1.200 + */
1.201 + nsIPropertyBag2 getPrefs(in nsIVariant aGroup, in nsILoadContext aContext);
1.202 +
1.203 + /**
1.204 + * Get the prefs with the given name.
1.205 + *
1.206 + * @param aName the setting name for which to retrieve prefs
1.207 + * @param aPrivacyContext
1.208 + * a context from which to determine the privacy status
1.209 + * of the pref (ie. whether to search for prefs in memory
1.210 + * or in permanent storage), obtained from a relevant
1.211 + * window or channel.
1.212 + *
1.213 + * @returns a property bag of prefs
1.214 + * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
1.215 + */
1.216 + nsIPropertyBag2 getPrefsByName(in AString aName, in nsILoadContext aContext);
1.217 +
1.218 + /**
1.219 + * Add an observer.
1.220 + *
1.221 + * @param aName the setting to observe, or null to add
1.222 + * a generic observer that observes all settings
1.223 + * @param aObserver the observer to add
1.224 + */
1.225 + void addObserver(in AString aName, in nsIContentPrefObserver aObserver);
1.226 +
1.227 + /**
1.228 + * Remove an observer.
1.229 + *
1.230 + * @param aName the setting being observed, or null to remove
1.231 + * a generic observer that observes all settings
1.232 + * @param aObserver the observer to remove
1.233 + */
1.234 + void removeObserver(in AString aName, in nsIContentPrefObserver aObserver);
1.235 +
1.236 + /**
1.237 + * The component that the service uses to determine the groups to which
1.238 + * URIs belong. By default this is the "hostname grouper", which groups
1.239 + * URIs by full hostname (a.k.a. site).
1.240 + */
1.241 + readonly attribute nsIContentURIGrouper grouper;
1.242 +
1.243 + /**
1.244 + * The database connection to the content preferences database.
1.245 + * Useful for accessing and manipulating preferences in ways that are caller-
1.246 + * specific or for which there is not yet a generic method, although generic
1.247 + * functionality useful to multiple callers should generally be added to this
1.248 + * unfrozen interface. Also useful for testing the database creation
1.249 + * and migration code.
1.250 + */
1.251 + readonly attribute mozIStorageConnection DBConnection;
1.252 +};
1.253 +
1.254 +%{C++
1.255 +// The contractID for the generic implementation built in to xpcom.
1.256 +#define NS_CONTENT_PREF_SERVICE_CONTRACTID "@mozilla.org/content-pref/service;1"
1.257 +%}
