michael@0: /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIDOMStorage;
michael@0: interface nsIPrincipal;
michael@0: interface nsIURI;
michael@0: 
michael@0: /**
michael@0:  * General purpose interface that has two implementations, for localStorage
michael@0:  * resp. sessionStorage with "@mozilla.org/dom/localStorage-manager;1" resp.
michael@0:  * "@mozilla.org/dom/sessionStorage-manager;1" contract IDs.
michael@0:  */
michael@0: [scriptable, uuid(96dd7614-fcc8-4745-9a1d-52f44dea8818)]
michael@0: interface nsIDOMStorageManager : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * This starts async preloading of a storage cache for scope
michael@0:    * defined by the principal.
michael@0:    *
michael@0:    * @param aFirstPartyIsolationURI
michael@0:    *    First party URI to bound storage to.
michael@0:    * @param aPrincipal
michael@0:    *    Principal to bound storage to.
michael@0:    */
michael@0:   void precacheStorage(in nsIPrincipal aPrincipal);
michael@0:   void precacheStorageForFirstParty(in nsIURI aFirstPartyIsolationURI,
michael@0:                                     in nsIPrincipal aPrincipal);
michael@0: 
michael@0:   /**
michael@0:    * Returns instance of DOM storage object for given principal.
michael@0:    * A new object is always returned and it is ensured there is
michael@0:    * a storage for the scope created.
michael@0:    *
michael@0:    * @param aFirstPartyIsolationURI
michael@0:    *    First party URI to bound storage to.
michael@0:    * @param aPrincipal
michael@0:    *    Principal to bound storage to.
michael@0:    * @param aDocumentURI
michael@0:    *    URL of the demanding document, used for DOM storage event only.
michael@0:    * @param aPrivate
michael@0:    *    Whether the demanding document is running in Private Browsing mode or not.
michael@0:    */
michael@0:   nsIDOMStorage createStorage(in nsIPrincipal aPrincipal,
michael@0:                               in DOMString aDocumentURI,
michael@0:                               [optional] in bool aPrivate);
michael@0:   nsIDOMStorage createStorageForFirstParty(in nsIURI aFirstPartyIsolationURI,
michael@0:                                            in nsIPrincipal aPrincipal,
michael@0:                                            in DOMString aDocumentURI,
michael@0:                                            [optional] in bool aPrivate);
michael@0:   /**
michael@0:    * Returns instance of DOM storage object for given principal.
michael@0:    * If there is no storage managed for the scope, then null is returned and
michael@0:    * no object is created.  Otherwise, an object (new) for the existing storage
michael@0:    * scope is returned.
michael@0:    *
michael@0:    * @param aPrincipal
michael@0:    *    Principal to bound storage to.
michael@0:    * @param aPrivate
michael@0:    *    Whether the demanding document is running in Private Browsing mode or not.
michael@0:    */
michael@0:   nsIDOMStorage getStorage(in nsIPrincipal aPrincipal,
michael@0:                            [optional] in bool aPrivate);
michael@0:   nsIDOMStorage getStorageForFirstParty(in nsIURI aFirstPartyIsolationURI,
michael@0:                                         in nsIPrincipal aPrincipal,
michael@0:                                         [optional] in bool aPrivate);
michael@0: 
michael@0:   /**
michael@0:    * Clones given storage into this storage manager.
michael@0:    *
michael@0:    * @param aStorageToCloneFrom
michael@0:    *    The storage to copy all items from into this manager.  Manager will then
michael@0:    *    return a new and independent object that contains snapshot of data from
michael@0:    *    the moment this method was called.  Modification to this new object will
michael@0:    *    not affect the original storage content we cloned from and vice versa.
michael@0:    */
michael@0:   void cloneStorage(in nsIDOMStorage aStorageToCloneFrom);
michael@0: 
michael@0:   /**
michael@0:    * Returns true if the storage belongs to the given principal and is managed
michael@0:    * (i.e. has been created and is cached) by this storage manager.
michael@0:    *
michael@0:    * @param aFirstPartyIsolationURI
michael@0:    *    First party URI to check the storage against.
michael@0:    * @param aPrincipal
michael@0:    *    Principal to check the storage against.
michael@0:    * @param aStorage
michael@0:    *    The storage object to examine.
michael@0:    *
michael@0:    * @result
michael@0:    *    true when the storage object is bound with the principal and is managed
michael@0:    *         by this storage manager.
michael@0:    *    false otherwise
michael@0:    */
michael@0:   bool checkStorage(in nsIPrincipal aPrincipal,
michael@0:                     in nsIDOMStorage aStorage);
michael@0:   bool checkStorageForFirstParty(in nsIURI aFirstPartyIsolationURI,
michael@0:                                  in nsIPrincipal aPrincipal,
michael@0:                                  in nsIDOMStorage aStorage);
michael@0: 
michael@0:   /**
michael@0:    * @deprecated
michael@0:    *
michael@0:    * Returns instance of localStorage object for aURI's origin.
michael@0:    * This method ensures there is always only a single instance
michael@0:    * for a single origin.
michael@0:    *
michael@0:    * Currently just forwards to the createStorage method of this
michael@0:    * interface.
michael@0:    *
michael@0:    * Extension developers are strongly encouraged to use getStorage
michael@0:    * or createStorage method instead.
michael@0:    */
michael@0:   nsIDOMStorage getLocalStorageForPrincipal(in nsIPrincipal aPrincipal,
michael@0:                                             in DOMString aDocumentURI,
michael@0:                                             [optional] in bool aPrivate);
michael@0: };