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