1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
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"
%}
|
