dom/interfaces/base/nsIContentPrefService2.idl

   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  *
  91  * Callbacks
  92  *
  93  * The methods of callback objects are always called asynchronously.
  94  *
  95  * Observers are called after callbacks are called, but they are called in the
  96  * same turn of the event loop as callbacks.
  97  *
  98  * See nsIContentPrefCallback2 below for more information about callbacks.
  99  */
 100
 101 [scriptable, uuid(bed98666-d995-470f-bebd-62476d318576)]
 102 interface nsIContentPrefService2 : nsISupports
 103 {
 104   /**
 105    * Group (called "domain" in this interface) names longer than this will be
 106    * truncated automatically.
 107    */
 108   const unsigned short GROUP_NAME_MAX_LENGTH = 2000;
 109
 110   /**
 111    * Gets all the preferences with the given name.
 112    *
 113    * @param name      The preferences' name.
 114    * @param context   The private-browsing context, if any.
 115    * @param callback  handleResult is called once for each preference unless
 116    *                  no such preferences exist, in which case handleResult
 117    *                  is not called at all.
 118    */
 119   void getByName(in AString name,
 120                  in nsILoadContext context,
 121                  in nsIContentPrefCallback2 callback);
 122
 123   /**
 124    * Gets the preference with the given domain and name.
 125    *
 126    * @param domain    The preference's domain.
 127    * @param name      The preference's name.
 128    * @param context   The private-browsing context, if any.
 129    * @param callback  handleResult is called once unless no such preference
 130    *                  exists, in which case handleResult is not called at all.
 131    */
 132   void getByDomainAndName(in AString domain,
 133                           in AString name,
 134                           in nsILoadContext context,
 135                           in nsIContentPrefCallback2 callback);
 136
 137   /**
 138    * Gets all preferences with the given name whose domains are either the same
 139    * as or subdomains of the given domain.
 140    *
 141    * @param domain    The preferences' domain.
 142    * @param name      The preferences' name.
 143    * @param context   The private-browsing context, if any.
 144    * @param callback  handleResult is called once for each preference.  If no
 145    *                  such preferences exist, handleResult is not called at all.
 146    */
 147   void getBySubdomainAndName(in AString domain,
 148                              in AString name,
 149                              in nsILoadContext context,
 150                              in nsIContentPrefCallback2 callback);
 151
 152   /**
 153    * Gets the preference with no domain and the given name.
 154    *
 155    * @param name      The preference's name.
 156    * @param context   The private-browsing context, if any.
 157    * @param callback  handleResult is called once unless no such preference
 158    *                  exists, in which case handleResult is not called at all.
 159    */
 160   void getGlobal(in AString name,
 161                  in nsILoadContext context,
 162                  in nsIContentPrefCallback2 callback);
 163
 164   /**
 165    * Synchronously retrieves from the in-memory cache the preference with the
 166    * given domain and name.
 167    *
 168    * In addition to caching preference values, the cache also keeps track of
 169    * preferences that are known not to exist.  If the preference is known not to
 170    * exist, the value attribute of the returned object will be undefined
 171    * (nsIDataType::VTYPE_VOID).
 172    *
 173    * If the preference is neither cached nor known not to exist, then null is
 174    * returned, and get() must be called to determine whether the preference
 175    * exists.
 176    *
 177    * @param domain   The preference's domain.
 178    * @param name     The preference's name.
 179    * @param context  The private-browsing context, if any.
 180    * @return         The preference, or null if no such preference is known to
 181    *                 exist.
 182    */
 183   nsIContentPref getCachedByDomainAndName(in AString domain,
 184                                           in AString name,
 185                                           in nsILoadContext context);
 186
 187   /**
 188    * Synchronously retrieves from the in-memory cache all preferences with the
 189    * given name whose domains are either the same as or subdomains of the given
 190    * domain.
 191    *
 192    * The preferences are returned in an array through the out-parameter.  If a
 193    * preference for a particular subdomain is known not to exist, then an object
 194    * corresponding to that preference will be present in the array, and, as with
 195    * getCachedByDomainAndName, its value attribute will be undefined.
 196    *
 197    * @param domain   The preferences' domain.
 198    * @param name     The preferences' name.
 199    * @param context  The private-browsing context, if any.
 200    * @return         The array of preferences.
 201    */
 202   Array<nsIContentPref> getCachedBySubdomainAndName(in AString domain,
 203                                                     in AString name,
 204                                                     in nsILoadContext context);
 205
 206   /**
 207    * Synchronously retrieves from the in-memory cache the preference with no
 208    * domain and the given name.
 209    *
 210    * As with getCachedByDomainAndName, if the preference is cached then it is
 211    * returned; if the preference is known not to exist, then the value attribute
 212    * of the returned object will be undefined; if the preference is neither
 213    * cached nor known not to exist, then null is returned.
 214    *
 215    * @param name     The preference's name.
 216    * @param context  The private-browsing context, if any.
 217    * @return         The preference, or null if no such preference is known to
 218    *                 exist.
 219    */
 220   nsIContentPref getCachedGlobal(in AString name,
 221                                  in nsILoadContext context);
 222
 223   /**
 224    * Sets a preference.
 225    *
 226    * @param domain    The preference's domain.
 227    * @param name      The preference's name.
 228    * @param value     The preference's value.
 229    * @param context   The private-browsing context, if any.
 230    * @param callback  handleCompletion is called when the preference has been
 231    *                  stored.
 232    */
 233   void set(in AString domain,
 234            in AString name,
 235            in nsIVariant value,
 236            in nsILoadContext context,
 237            [optional] in nsIContentPrefCallback2 callback);
 238
 239   /**
 240    * Sets a preference with no domain.
 241    *
 242    * @param name      The preference's name.
 243    * @param value     The preference's value.
 244    * @param context   The private-browsing context, if any.
 245    * @param callback  handleCompletion is called when the preference has been
 246    *                  stored.
 247    */
 248   void setGlobal(in AString name,
 249                  in nsIVariant value,
 250                  in nsILoadContext context,
 251                  [optional] in nsIContentPrefCallback2 callback);
 252
 253   /**
 254    * Removes the preference with the given domain and name.
 255    *
 256    * @param domain    The preference's domain.
 257    * @param name      The preference's name.
 258    * @param context   The private-browsing context, if any.
 259    * @param callback  handleCompletion is called when the operation completes.
 260    */
 261   void removeByDomainAndName(in AString domain,
 262                              in AString name,
 263                              in nsILoadContext context,
 264                              [optional] in nsIContentPrefCallback2 callback);
 265
 266   /**
 267    * Removes all the preferences with the given name whose domains are either
 268    * the same as or subdomains of the given domain.
 269    *
 270    * @param domain    The preferences' domain.
 271    * @param name      The preferences' name.
 272    * @param context   The private-browsing context, if any.
 273    * @param callback  handleCompletion is called when the operation completes.
 274    */
 275   void removeBySubdomainAndName(in AString domain,
 276                                 in AString name,
 277                                 in nsILoadContext context,
 278                                 [optional] in nsIContentPrefCallback2 callback);
 279
 280   /**
 281    * Removes the preference with no domain and the given name.
 282    *
 283    * @param name      The preference's name.
 284    * @param context   The private-browsing context, if any.
 285    * @param callback  handleCompletion is called when the operation completes.
 286    */
 287   void removeGlobal(in AString name,
 288                     in nsILoadContext context,
 289                     [optional] in nsIContentPrefCallback2 callback);
 290
 291   /**
 292    * Removes all preferences with the given domain.
 293    *
 294    * @param domain    The preferences' domain.
 295    * @param context   The private-browsing context, if any.
 296    * @param callback  handleCompletion is called when the operation completes.
 297    */
 298   void removeByDomain(in AString domain,
 299                       in nsILoadContext context,
 300                       [optional] in nsIContentPrefCallback2 callback);
 301
 302   /**
 303    * Removes all preferences whose domains are either the same as or subdomains
 304    * of the given domain.
 305    *
 306    * @param domain    The preferences' domain.
 307    * @param context   The private-browsing context, if any.
 308    * @param callback  handleCompletion is called when the operation completes.
 309    */
 310   void removeBySubdomain(in AString domain,
 311                          in nsILoadContext context,
 312                          [optional] in nsIContentPrefCallback2 callback);
 313
 314   /**
 315    * Removes all preferences with the given name regardless of domain, including
 316    * global preferences with the given name.
 317    *
 318    * @param name      The preferences' name.
 319    * @param context   The private-browsing context, if any.
 320    * @param callback  handleCompletion is called when the operation completes.
 321    */
 322   void removeByName(in AString name,
 323                     in nsILoadContext context,
 324                     [optional] in nsIContentPrefCallback2 callback);
 325
 326   /**
 327    * Removes all non-global preferences -- in other words, all preferences that
 328    * have a domain.
 329    *
 330    * @param context   The private-browsing context, if any.
 331    * @param callback  handleCompletion is called when the operation completes.
 332    */
 333   void removeAllDomains(in nsILoadContext context,
 334                         [optional] in nsIContentPrefCallback2 callback);
 335
 336   /**
 337    * Removes all non-global preferences created after and including |since|.
 338    *
 339    * @param since     Timestamp in milliseconds.
 340    * @param context   The private-browsing context, if any.
 341    * @param callback  handleCompletion is called when the operation completes.
 342    */
 343   void removeAllDomainsSince(in unsigned long long since,
 344                              in nsILoadContext context,
 345                              [optional] in nsIContentPrefCallback2 callback);
 346
 347   /**
 348    * Removes all global preferences -- in other words, all preferences that have
 349    * no domain.
 350    *
 351    * @param context   The private-browsing context, if any.
 352    * @param callback  handleCompletion is called when the operation completes.
 353    */
 354   void removeAllGlobals(in nsILoadContext context,
 355                         [optional] in nsIContentPrefCallback2 callback);
 356
 357   /**
 358    * Registers an observer that will be notified whenever a preference with the
 359    * given name is set or removed.
 360    *
 361    * When a set or remove method is called, observers are called after the set
 362    * or removal completes and after the method's callback is called, and they
 363    * are called in the same turn of the event loop as the callback.
 364    *
 365    * The service holds a strong reference to the observer, so the observer must
 366    * be removed later to avoid leaking it.
 367    *
 368    * @param name      The name of the preferences to observe.  Pass null to
 369    *                  observe all preference changes regardless of name.
 370    * @param observer  The observer.
 371    */
 372   void addObserverForName(in AString name,
 373                           in nsIContentPrefObserver observer);
 374
 375   /**
 376    * Unregisters an observer for the given name.
 377    *
 378    * @param name      The name for which the observer was registered.  Pass null
 379    *                  if the observer was added with a null name.
 380    * @param observer  The observer.
 381    */
 382   void removeObserverForName(in AString name,
 383                              in nsIContentPrefObserver observer);
 384
 385   /**
 386    * Extracts and returns the domain from the given string representation of a
 387    * URI.  This is how the API extracts domains from URIs passed to it.
 388    *
 389    * @param str  The string representation of a URI, like
 390    *             "http://example.com/foo/bar".
 391    * @return     If the given string is a valid URI, the domain of that URI is
 392    *             returned.  Otherwise, the string itself is returned.
 393    */
 394   AString extractDomain(in AString str);
 395 };
 396
 397 /**
 398  * The callback used by the above methods.
 399  */
 400 [scriptable, uuid(1a12cf41-79e8-4d0f-9899-2f7b27c5d9a1)]
 401 interface nsIContentPrefCallback2 : nsISupports
 402 {
 403   /**
 404    * For the retrieval methods, this is called once for each retrieved
 405    * preference.  It is not called for other methods.
 406    *
 407    * @param pref  The retrieved preference.
 408    */
 409   void handleResult(in nsIContentPref pref);
 410
 411   /**
 412    * Called when an error occurs.  This may be called multiple times before
 413    * handleCompletion is called.
 414    *
 415    * @param error  A number in Components.results describing the error.
 416    */
 417   void handleError(in nsresult error);
 418
 419   /**
 420    * Called when the method finishes.  This will be called exactly once for
 421    * each method invocation, and afterward no other callback methods will be
 422    * called.
 423    *
 424    * @param reason  One of the COMPLETE_* values indicating the manner in which
 425    *                the method completed.
 426    */
 427   void handleCompletion(in unsigned short reason);
 428
 429   const unsigned short COMPLETE_OK = 0;
 430   const unsigned short COMPLETE_ERROR = 1;
 431 };
 432
 433 [scriptable, function, uuid(9f24948d-24b5-4b1b-b554-7dbd58c1d792)]
 434 interface nsIContentPref : nsISupports
 435 {
 436   readonly attribute AString domain;
 437   readonly attribute AString name;
 438   readonly attribute nsIVariant value;
 439 };
 440
 441 %{C++
 442 // The contractID for the generic implementation built in to xpcom.
 443 #define NS_CONTENT_PREF_SERVICE_CONTRACTID "@mozilla.org/content-pref/service;1"
 444 %}