dom/interfaces/base/nsIContentPrefService.idl@7e26c7da4463
dom/interfaces/base/nsIContentPrefService.idl
Wed, 31 Dec 2014 06:55:50 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:55:50 +0100
- changeset 2
- 7e26c7da4463
- permissions
- -rw-r--r--
Added tag UPSTREAM_283F7C6 for changeset ca08bd8f51b2
1 /* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5 #include "nsISupports.idl"
7 interface nsIVariant;
8 interface nsIPropertyBag2;
9 interface nsIContentURIGrouper;
10 interface nsILoadContext;
11 interface mozIStorageConnection;
13 [scriptable, uuid(746c7a02-f6c1-4869-b434-7c8b86e60e61)]
14 interface nsIContentPrefObserver : nsISupports
15 {
16 /**
17 * Called when a content pref is set to a different value.
18 *
19 * @param aGroup the group to which the pref belongs, or null
20 * if it's a global pref (applies to all sites)
21 * @param aName the name of the pref that was set
22 * @param aValue the new value of the pref
23 */
24 void onContentPrefSet(in AString aGroup, in AString aName, in nsIVariant aValue);
26 /**
27 * Called when a content pref is removed.
28 *
29 * @param aGroup the group to which the pref belongs, or null
30 * if it's a global pref (applies to all sites)
31 * @param aName the name of the pref that was removed
32 */
33 void onContentPrefRemoved(in AString aGroup, in AString aName);
34 };
36 [scriptable, function, uuid(c1b3d6df-5373-4606-8494-8bcf14a7fc62)]
37 interface nsIContentPrefCallback : nsISupports
38 {
39 void onResult(in nsIVariant aResult);
40 };
42 /**
43 * @deprecated Please use nsIContentPrefService2 instead.
44 */
45 [scriptable, uuid(e3f772f3-023f-4b32-b074-36cf0fd5d414)]
46 interface nsIContentPrefService : nsISupports
47 {
48 /**
49 * Get a pref.
50 *
51 * Besides the regular string, integer, boolean, etc. values, this method
52 * may return null (nsIDataType::VTYPE_EMPTY), which means the pref is set
53 * to NULL in the database, as well as undefined (nsIDataType::VTYPE_VOID),
54 * which means there is no record for this pref in the database.
55 *
56 * This method can be called from content processes in electrolysis builds.
57 * We have a whitelist of values that can be read in such a way.
58 *
59 * @param aGroup the group for which to get the pref, as an nsIURI
60 * from which the hostname will be used, a string
61 * (typically in the format of a hostname), or null
62 * to get the global pref (applies to all sites)
63 * @param aName the name of the pref to get
64 * @param aPrivacyContext
65 * a context from which to determine the privacy status
66 * of the pref (ie. whether to search in memory or in
67 * permanent storage for it), obtained from a relevant
68 * window or channel.
69 * @param aCallback an optional nsIContentPrefCallback to receive the
70 * result. If desired, JavaScript callers can instead
71 * provide a function to call upon completion
72 *
73 * @returns the value of the pref
74 * @throws NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null
75 * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
76 */
77 nsIVariant getPref(in nsIVariant aGroup, in AString aName,
78 in nsILoadContext aPrivacyContext,
79 [optional] in nsIContentPrefCallback aCallback);
81 /**
82 * Set a pref.
83 *
84 * This method can be called from content processes in electrolysis builds.
85 * We have a whitelist of values that can be set in such a way.
86 *
87 * @param aGroup the group for which to set the pref, as an nsIURI
88 * from which the hostname will be used, a string
89 * (typically in the format of a hostname), or null
90 * to set the global pref (applies to all sites)
91 * @param aName the name of the pref to set
92 * @param aValue the new value of the pref
93 * @param aPrivacyContext
94 * a context from which to determine the privacy status
95 * of the pref (ie. whether to store it in memory or in
96 * permanent storage), obtained from a relevant
97 * window or channel.
98 * @throws NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null
99 * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
100 */
101 void setPref(in nsIVariant aGroup, in AString aName, in nsIVariant aValue, in nsILoadContext aPrivacyContext);
103 /**
104 * Check whether or not a pref exists.
105 *
106 * @param aGroup the group for which to check for the pref, as an nsIURI
107 * from which the hostname will be used, a string
108 * (typically in the format of a hostname), or null
109 * to check for the global pref (applies to all sites)
110 * @param aName the name of the pref to check for
111 * @param aPrivacyContext
112 * a context from which to determine the privacy status
113 * of the pref (ie. whether to search in memory or in
114 * permanent storage for it), obtained from a relevant
115 * window or channel.
116 * @throws NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null
117 * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
118 */
119 boolean hasPref(in nsIVariant aGroup, in AString aName, in nsILoadContext aContext);
121 /**
122 * Check whether or not the value of a pref (or its non-existance) is cached.
123 *
124 * @param aGroup the group for which to check for the pref, as an nsIURI
125 * from which the hostname will be used, a string
126 * (typically in the format of a hostname), or null
127 * to check for the global pref (applies to all sites)
128 * @param aName the name of the pref to check for
129 * @param aPrivacyContext
130 * a context from which to determine the privacy status
131 * of the pref (ie. whether to search in memory or in
132 * permanent storage for it), obtained from a relevant
133 * window or channel.
134 * @throws NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null
135 * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
136 */
137 boolean hasCachedPref(in nsIVariant aGroup, in AString aName, in nsILoadContext aContext);
139 /**
140 * Remove a pref.
141 *
142 * @param aGroup the group for which to remove the pref, as an nsIURI
143 * from which the hostname will be used, a string
144 * (typically in the format of a hostname), or null
145 * to remove the global pref (applies to all sites)
146 * @param aName the name of the pref to remove
147 * @param aPrivacyContext
148 * a context from which to determine the privacy status
149 * of the pref (ie. whether to search in memory or in
150 * permanent storage for it), obtained from a relevant
151 * window or channel.
152 * @throws NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null
153 * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
154 */
155 void removePref(in nsIVariant aGroup, in AString aName, in nsILoadContext aContext);
157 /**
158 * Remove all grouped prefs. Useful for removing references to the sites
159 * the user has visited when the user clears their private data.
160 *
161 * @param aPrivacyContext
162 * a context from which to determine the privacy status
163 * of the pref (ie. whether to remove prefs in memory or
164 * in permanent storage), obtained from a relevant
165 * window or channel.
166 */
167 void removeGroupedPrefs(in nsILoadContext aContext);
169 /**
170 * Remove all prefs with the given name.
171 *
172 * @param aName the setting name for which to remove prefs
173 * @param aPrivacyContext
174 * a context from which to determine the privacy status
175 * of the prefs (ie. whether to remove prefs in memory or
176 * in permanent storage), obtained from a relevant
177 * window or channel.
178 * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
179 */
180 void removePrefsByName(in AString aName, in nsILoadContext aContext);
182 /**
183 * Get the prefs that apply to the given site.
184 *
185 * @param aGroup the group for which to retrieve prefs, as an nsIURI
186 * from which the hostname will be used, a string
187 * (typically in the format of a hostname), or null
188 * to get the global prefs (apply to all sites)
189 * @param aPrivacyContext
190 * a context from which to determine the privacy status
191 * of the pref (ie. whether to search for prefs in memory
192 * or in permanent storage), obtained from a relevant
193 * window or channel.
194 *
195 * @returns a property bag of prefs
196 * @throws NS_ERROR_ILLEGAL_VALUE if aGroup is not a string, nsIURI, or null
197 */
198 nsIPropertyBag2 getPrefs(in nsIVariant aGroup, in nsILoadContext aContext);
200 /**
201 * Get the prefs with the given name.
202 *
203 * @param aName the setting name for which to retrieve prefs
204 * @param aPrivacyContext
205 * a context from which to determine the privacy status
206 * of the pref (ie. whether to search for prefs in memory
207 * or in permanent storage), obtained from a relevant
208 * window or channel.
209 *
210 * @returns a property bag of prefs
211 * @throws NS_ERROR_ILLEGAL_VALUE if aName is null or an empty string
212 */
213 nsIPropertyBag2 getPrefsByName(in AString aName, in nsILoadContext aContext);
215 /**
216 * Add an observer.
217 *
218 * @param aName the setting to observe, or null to add
219 * a generic observer that observes all settings
220 * @param aObserver the observer to add
221 */
222 void addObserver(in AString aName, in nsIContentPrefObserver aObserver);
224 /**
225 * Remove an observer.
226 *
227 * @param aName the setting being observed, or null to remove
228 * a generic observer that observes all settings
229 * @param aObserver the observer to remove
230 */
231 void removeObserver(in AString aName, in nsIContentPrefObserver aObserver);
233 /**
234 * The component that the service uses to determine the groups to which
235 * URIs belong. By default this is the "hostname grouper", which groups
236 * URIs by full hostname (a.k.a. site).
237 */
238 readonly attribute nsIContentURIGrouper grouper;
240 /**
241 * The database connection to the content preferences database.
242 * Useful for accessing and manipulating preferences in ways that are caller-
243 * specific or for which there is not yet a generic method, although generic
244 * functionality useful to multiple callers should generally be added to this
245 * unfrozen interface. Also useful for testing the database creation
246 * and migration code.
247 */
248 readonly attribute mozIStorageConnection DBConnection;
249 };
251 %{C++
252 // The contractID for the generic implementation built in to xpcom.
253 #define NS_CONTENT_PREF_SERVICE_CONTRACTID "@mozilla.org/content-pref/service;1"
254 %}
