The Tor Browser: dom/interfaces/storage/nsIDOMStorageManager.idl@b8a032363ba2

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

     1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */

     2 /* This Source Code Form is subject to the terms of the Mozilla Public

     3  * License, v. 2.0. If a copy of the MPL was not distributed with this

     4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

     6 #include "nsISupports.idl"

     8 interface nsIDOMStorage;

     9 interface nsIPrincipal;

    10 interface nsIURI;

    12 /**

    13  * General purpose interface that has two implementations, for localStorage

    14  * resp. sessionStorage with "@mozilla.org/dom/localStorage-manager;1" resp.

    15  * "@mozilla.org/dom/sessionStorage-manager;1" contract IDs.

    16  */

    17 [scriptable, uuid(96dd7614-fcc8-4745-9a1d-52f44dea8818)]

    18 interface nsIDOMStorageManager : nsISupports

    19 {

    20   /**

    21    * This starts async preloading of a storage cache for scope

    22    * defined by the principal.

    23    *

    24    * @param aFirstPartyIsolationURI

    25    *    First party URI to bound storage to.

    26    * @param aPrincipal

    27    *    Principal to bound storage to.

    28    */

    29   void precacheStorage(in nsIPrincipal aPrincipal);

    30   void precacheStorageForFirstParty(in nsIURI aFirstPartyIsolationURI,

    31                                     in nsIPrincipal aPrincipal);

    33   /**

    34    * Returns instance of DOM storage object for given principal.

    35    * A new object is always returned and it is ensured there is

    36    * a storage for the scope created.

    37    *

    38    * @param aFirstPartyIsolationURI

    39    *    First party URI to bound storage to.

    40    * @param aPrincipal

    41    *    Principal to bound storage to.

    42    * @param aDocumentURI

    43    *    URL of the demanding document, used for DOM storage event only.

    44    * @param aPrivate

    45    *    Whether the demanding document is running in Private Browsing mode or not.

    46    */

    47   nsIDOMStorage createStorage(in nsIPrincipal aPrincipal,

    48                               in DOMString aDocumentURI,

    49                               [optional] in bool aPrivate);

    50   nsIDOMStorage createStorageForFirstParty(in nsIURI aFirstPartyIsolationURI,

    51                                            in nsIPrincipal aPrincipal,

    52                                            in DOMString aDocumentURI,

    53                                            [optional] in bool aPrivate);

    54   /**

    55    * Returns instance of DOM storage object for given principal.

    56    * If there is no storage managed for the scope, then null is returned and

    57    * no object is created.  Otherwise, an object (new) for the existing storage

    58    * scope is returned.

    59    *

    60    * @param aPrincipal

    61    *    Principal to bound storage to.

    62    * @param aPrivate

    63    *    Whether the demanding document is running in Private Browsing mode or not.

    64    */

    65   nsIDOMStorage getStorage(in nsIPrincipal aPrincipal,

    66                            [optional] in bool aPrivate);

    67   nsIDOMStorage getStorageForFirstParty(in nsIURI aFirstPartyIsolationURI,

    68                                         in nsIPrincipal aPrincipal,

    69                                         [optional] in bool aPrivate);

    71   /**

    72    * Clones given storage into this storage manager.

    73    *

    74    * @param aStorageToCloneFrom

    75    *    The storage to copy all items from into this manager.  Manager will then

    76    *    return a new and independent object that contains snapshot of data from

    77    *    the moment this method was called.  Modification to this new object will

    78    *    not affect the original storage content we cloned from and vice versa.

    79    */

    80   void cloneStorage(in nsIDOMStorage aStorageToCloneFrom);

    82   /**

    83    * Returns true if the storage belongs to the given principal and is managed

    84    * (i.e. has been created and is cached) by this storage manager.

    85    *

    86    * @param aFirstPartyIsolationURI

    87    *    First party URI to check the storage against.

    88    * @param aPrincipal

    89    *    Principal to check the storage against.

    90    * @param aStorage

    91    *    The storage object to examine.

    92    *

    93    * @result

    94    *    true when the storage object is bound with the principal and is managed

    95    *         by this storage manager.

    96    *    false otherwise

    97    */

    98   bool checkStorage(in nsIPrincipal aPrincipal,

    99                     in nsIDOMStorage aStorage);

   100   bool checkStorageForFirstParty(in nsIURI aFirstPartyIsolationURI,

   101                                  in nsIPrincipal aPrincipal,

   102                                  in nsIDOMStorage aStorage);

   104   /**

   105    * @deprecated

   106    *

   107    * Returns instance of localStorage object for aURI's origin.

   108    * This method ensures there is always only a single instance

   109    * for a single origin.

   110    *

   111    * Currently just forwards to the createStorage method of this

   112    * interface.

   113    *

   114    * Extension developers are strongly encouraged to use getStorage

   115    * or createStorage method instead.

   116    */

   117   nsIDOMStorage getLocalStorageForPrincipal(in nsIPrincipal aPrincipal,

   118                                             in DOMString aDocumentURI,

   119                                             [optional] in bool aPrivate);

   120 };

The Tor Browser / file revision