The Tor Browser / file comparison

comparison: dom/interfaces/base/nsIContentPrefService2.idl

dom/interfaces/base/nsIContentPrefService2.idl

branch
TOR_BUG_9701
changeset 15
b8a032363ba2
equal deleted inserted replaced
-1:000000000000 0:7c20699e72fb
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 file,
3 * You can obtain one at http://mozilla.org/MPL/2.0/. */
4
5 #include "nsISupports.idl"
6
7 interface nsIVariant;
8 interface nsIContentPrefObserver;
9 interface nsIContentPrefCallback2;
10 interface nsILoadContext;
11 interface nsIContentPref;
12
13 /**
14 * Content Preferences
15 *
16 * Content preferences allow the application to associate arbitrary data, or
17 * "preferences", with specific domains, or web "content". Specifically, a
18 * content preference is a structure with three values: a domain with which the
19 * preference is associated, a name that identifies the preference within its
20 * domain, and a value. (See nsIContentPref below.)
21 *
22 * For example, if you want to remember the user's preference for a certain zoom
23 * level on www.mozilla.org pages, you might store a preference whose domain is
24 * "www.mozilla.org", whose name is "zoomLevel", and whose value is the numeric
25 * zoom level.
26 *
27 * A preference need not have a domain, and in that case the preference is
28 * called a "global" preference. This interface doesn't impart any special
29 * significance to global preferences; they're simply name-value pairs that
30 * aren't associated with any particular domain. As a consumer of this
31 * interface, you might choose to let a global preference override all non-
32 * global preferences of the same name, for example, for whatever definition of
33 * "override" is appropriate for your use case.
34 *
35 *
36 * Domain Parameters
37 *
38 * Many methods of this interface accept a "domain" parameter. Domains may be
39 * specified either exactly, like "example.com", or as full URLs, like
40 * "http://example.com/foo/bar". In the latter case the API extracts the full
41 * domain from the URL, so if you specify "http://foo.bar.example.com/baz", the
42 * domain is taken to be "foo.bar.example.com", not "example.com".
43 *
44 *
45 * Private-Browsing Context Parameters
46 *
47 * Many methods also accept a "context" parameter. This parameter relates to
48 * private browsing and determines the kind of storage that a method uses,
49 * either the usual permanent storage or temporary storage set aside for private
50 * browsing sessions.
51 *
52 * Pass null to unconditionally use permanent storage. Pass an nsILoadContext
53 * to use storage appropriate to the context's usePrivateBrowsing attribute: if
54 * usePrivateBrowsing is true, temporary private-browsing storage is used, and
55 * otherwise permanent storage is used. A context can be obtained from the
56 * window or channel whose content pertains to the preferences being modified or
57 * retrieved.
58 *
59 *
60 * Callbacks
61 *
62 * The methods of callback objects are always called asynchronously.
63 *
64 * Observers are called after callbacks are called, but they are called in the
65 * same turn of the event loop as callbacks.
66 *
67 * See nsIContentPrefCallback2 below for more information about callbacks.
68 */
69
70 [scriptable, uuid(f2507add-dc39-48e0-9147-e0270376148b)]
71 interface nsIContentPrefService2 : nsISupports
72 {
73 /**
74 * Gets all the preferences with the given name.
75 *
76 * @param name The preferences' name.
77 * @param context The private-browsing context, if any.
78 * @param callback handleResult is called once for each preference unless
79 * no such preferences exist, in which case handleResult
80 * is not called at all.
81 */
82 void getByName(in AString name,
83 in nsILoadContext context,
84 in nsIContentPrefCallback2 callback);
85
86 /**
87 * Gets the preference with the given domain and name.
88 *
89 * @param domain The preference's domain.
90 * @param name The preference's name.
91 * @param context The private-browsing context, if any.
92 * @param callback handleResult is called once unless no such preference
93 * exists, in which case handleResult is not called at all.
94 */
95 void getByDomainAndName(in AString domain,
96 in AString name,
97 in nsILoadContext context,
98 in nsIContentPrefCallback2 callback);
99
100 /**
101 * Gets all preferences with the given name whose domains are either the same
102 * as or subdomains of the given domain.
103 *
104 * @param domain The preferences' domain.
105 * @param name The preferences' name.
106 * @param context The private-browsing context, if any.
107 * @param callback handleResult is called once for each preference. If no
108 * such preferences exist, handleResult is not called at all.
109 */
110 void getBySubdomainAndName(in AString domain,
111 in AString name,
112 in nsILoadContext context,
113 in nsIContentPrefCallback2 callback);
114
115 /**
116 * Gets the preference with no domain and the given name.
117 *
118 * @param name The preference's name.
119 * @param context The private-browsing context, if any.
120 * @param callback handleResult is called once unless no such preference
121 * exists, in which case handleResult is not called at all.
122 */
123 void getGlobal(in AString name,
124 in nsILoadContext context,
125 in nsIContentPrefCallback2 callback);
126
127 /**
128 * Synchronously retrieves from the in-memory cache the preference with the
129 * given domain and name.
130 *
131 * In addition to caching preference values, the cache also keeps track of
132 * preferences that are known not to exist. If the preference is known not to
133 * exist, the value attribute of the returned object will be undefined
134 * (nsIDataType::VTYPE_VOID).
135 *
136 * If the preference is neither cached nor known not to exist, then null is
137 * returned, and get() must be called to determine whether the preference
138 * exists.
139 *
140 * @param domain The preference's domain.
141 * @param name The preference's name.
142 * @param context The private-browsing context, if any.
143 * @return The preference, or null if no such preference is known to
144 * exist.
145 */
146 nsIContentPref getCachedByDomainAndName(in AString domain,
147 in AString name,
148 in nsILoadContext context);
149
150 /**
151 * Synchronously retrieves from the in-memory cache all preferences with the
152 * given name whose domains are either the same as or subdomains of the given
153 * domain.
154 *
155 * The preferences are returned in an array through the out-parameter. If a
156 * preference for a particular subdomain is known not to exist, then an object
157 * corresponding to that preference will be present in the array, and, as with
158 * getCachedByDomainAndName, its value attribute will be undefined.
159 *
160 * @param domain The preferences' domain.
161 * @param name The preferences' name.
162 * @param context The private-browsing context, if any.
163 * @param len The length of the returned array.
164 * @param prefs The array of preferences.
165 */
166 void getCachedBySubdomainAndName(in AString domain,
167 in AString name,
168 in nsILoadContext context,
169 [optional] out unsigned long len,
170 [retval,array,size_is(len)] out nsIContentPref prefs);
171
172 /**
173 * Synchronously retrieves from the in-memory cache the preference with no
174 * domain and the given name.
175 *
176 * As with getCachedByDomainAndName, if the preference is cached then it is
177 * returned; if the preference is known not to exist, then the value attribute
178 * of the returned object will be undefined; if the preference is neither
179 * cached nor known not to exist, then null is returned.
180 *
181 * @param name The preference's name.
182 * @param context The private-browsing context, if any.
183 * @return The preference, or null if no such preference is known to
184 * exist.
185 */
186 nsIContentPref getCachedGlobal(in AString name,
187 in nsILoadContext context);
188
189 /**
190 * Sets a preference.
191 *
192 * @param domain The preference's domain.
193 * @param name The preference's name.
194 * @param value The preference's value.
195 * @param context The private-browsing context, if any.
196 * @param callback handleCompletion is called when the preference has been
197 * stored.
198 */
199 void set(in AString domain,
200 in AString name,
201 in nsIVariant value,
202 in nsILoadContext context,
203 [optional] in nsIContentPrefCallback2 callback);
204
205 /**
206 * Sets a preference with no domain.
207 *
208 * @param name The preference's name.
209 * @param value The preference's value.
210 * @param context The private-browsing context, if any.
211 * @param callback handleCompletion is called when the preference has been
212 * stored.
213 */
214 void setGlobal(in AString name,
215 in nsIVariant value,
216 in nsILoadContext context,
217 [optional] in nsIContentPrefCallback2 callback);
218
219 /**
220 * Removes the preference with the given domain and name.
221 *
222 * @param domain The preference's domain.
223 * @param name The preference's name.
224 * @param context The private-browsing context, if any.
225 * @param callback handleCompletion is called when the operation completes.
226 */
227 void removeByDomainAndName(in AString domain,
228 in AString name,
229 in nsILoadContext context,
230 [optional] in nsIContentPrefCallback2 callback);
231
232 /**
233 * Removes all the preferences with the given name whose domains are either
234 * the same as or subdomains of the given domain.
235 *
236 * @param domain The preferences' domain.
237 * @param name The preferences' name.
238 * @param context The private-browsing context, if any.
239 * @param callback handleCompletion is called when the operation completes.
240 */
241 void removeBySubdomainAndName(in AString domain,
242 in AString name,
243 in nsILoadContext context,
244 [optional] in nsIContentPrefCallback2 callback);
245
246 /**
247 * Removes the preference with no domain and the given name.
248 *
249 * @param name The preference's name.
250 * @param context The private-browsing context, if any.
251 * @param callback handleCompletion is called when the operation completes.
252 */
253 void removeGlobal(in AString name,
254 in nsILoadContext context,
255 [optional] in nsIContentPrefCallback2 callback);
256
257 /**
258 * Removes all preferences with the given domain.
259 *
260 * @param domain The preferences' domain.
261 * @param context The private-browsing context, if any.
262 * @param callback handleCompletion is called when the operation completes.
263 */
264 void removeByDomain(in AString domain,
265 in nsILoadContext context,
266 [optional] in nsIContentPrefCallback2 callback);
267
268 /**
269 * Removes all preferences whose domains are either the same as or subdomains
270 * of the given domain.
271 *
272 * @param domain The preferences' domain.
273 * @param context The private-browsing context, if any.
274 * @param callback handleCompletion is called when the operation completes.
275 */
276 void removeBySubdomain(in AString domain,
277 in nsILoadContext context,
278 [optional] in nsIContentPrefCallback2 callback);
279
280 /**
281 * Removes all preferences with the given name regardless of domain, including
282 * global preferences with the given name.
283 *
284 * @param name The preferences' name.
285 * @param context The private-browsing context, if any.
286 * @param callback handleCompletion is called when the operation completes.
287 */
288 void removeByName(in AString name,
289 in nsILoadContext context,
290 [optional] in nsIContentPrefCallback2 callback);
291
292 /**
293 * Removes all non-global preferences -- in other words, all preferences that
294 * have a domain.
295 *
296 * @param context The private-browsing context, if any.
297 * @param callback handleCompletion is called when the operation completes.
298 */
299 void removeAllDomains(in nsILoadContext context,
300 [optional] in nsIContentPrefCallback2 callback);
301
302 /**
303 * Removes all global preferences -- in other words, all preferences that have
304 * no domain.
305 *
306 * @param context The private-browsing context, if any.
307 * @param callback handleCompletion is called when the operation completes.
308 */
309 void removeAllGlobals(in nsILoadContext context,
310 [optional] in nsIContentPrefCallback2 callback);
311
312 /**
313 * Registers an observer that will be notified whenever a preference with the
314 * given name is set or removed.
315 *
316 * When a set or remove method is called, observers are called after the set
317 * or removal completes and after the method's callback is called, and they
318 * are called in the same turn of the event loop as the callback.
319 *
320 * The service holds a strong reference to the observer, so the observer must
321 * be removed later to avoid leaking it.
322 *
323 * @param name The name of the preferences to observe. Pass null to
324 * observe all preference changes regardless of name.
325 * @param observer The observer.
326 */
327 void addObserverForName(in AString name,
328 in nsIContentPrefObserver observer);
329
330 /**
331 * Unregisters an observer for the given name.
332 *
333 * @param name The name for which the observer was registered. Pass null
334 * if the observer was added with a null name.
335 * @param observer The observer.
336 */
337 void removeObserverForName(in AString name,
338 in nsIContentPrefObserver observer);
339
340 /**
341 * Extracts and returns the domain from the given string representation of a
342 * URI. This is how the API extracts domains from URIs passed to it.
343 *
344 * @param str The string representation of a URI, like
345 * "http://example.com/foo/bar".
346 * @return If the given string is a valid URI, the domain of that URI is
347 * returned. Otherwise, the string itself is returned.
348 */
349 AString extractDomain(in AString str);
350 };
351
352 /**
353 * The callback used by the above methods.
354 */
355 [scriptable, uuid(1a12cf41-79e8-4d0f-9899-2f7b27c5d9a1)]
356 interface nsIContentPrefCallback2 : nsISupports
357 {
358 /**
359 * For the retrieval methods, this is called once for each retrieved
360 * preference. It is not called for other methods.
361 *
362 * @param pref The retrieved preference.
363 */
364 void handleResult(in nsIContentPref pref);
365
366 /**
367 * Called when an error occurs. This may be called multiple times before
368 * handleCompletion is called.
369 *
370 * @param error A number in Components.results describing the error.
371 */
372 void handleError(in nsresult error);
373
374 /**
375 * Called when the method finishes. This will be called exactly once for
376 * each method invocation, and afterward no other callback methods will be
377 * called.
378 *
379 * @param reason One of the COMPLETE_* values indicating the manner in which
380 * the method completed.
381 */
382 void handleCompletion(in unsigned short reason);
383
384 const unsigned short COMPLETE_OK = 0;
385 const unsigned short COMPLETE_ERROR = 1;
386 };
387
388 [scriptable, function, uuid(9f24948d-24b5-4b1b-b554-7dbd58c1d792)]
389 interface nsIContentPref : nsISupports
390 {
391 readonly attribute AString domain;
392 readonly attribute AString name;
393 readonly attribute nsIVariant value;
394 };

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial