/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIDOMStorage;
interface nsIPrincipal;
interface mozIDOMWindow;

/**
 * General purpose interface that has two implementations, for localStorage
 * resp. sessionStorage with "@mozilla.org/dom/localStorage-manager;1" resp.
 * "@mozilla.org/dom/sessionStorage-manager;1" contract IDs.
 */
[scriptable, uuid(a20c742e-3ed1-44fb-b897-4080a75b1662)]
interface nsIDOMStorageManager : nsISupports
{
  /**
   * This starts async preloading of a storage cache for scope
   * defined by the principal.
   */
  void precacheStorage(in nsIPrincipal aPrincipal);

  /**
   * Returns instance of DOM storage object for given principal.
   * A new object is always returned and it is ensured there is
   * a storage for the scope created.
   *
   * @param aWindow
   *    The parent window.
   * @param aPrincipal
   *    Principal to bound storage to.
   * @param aDocumentURI
   *    URL of the demanding document, used for DOM storage event only.
   * @param aPrivate
   *    Whether the demanding document is running in Private Browsing mode or not.
   */
  nsIDOMStorage createStorage(in mozIDOMWindow aWindow,
                              in nsIPrincipal aPrincipal,
                              in DOMString aDocumentURI,
                              [optional] in bool aPrivate);
  /**
   * Returns instance of DOM storage object for given principal.
   * If there is no storage managed for the scope, then null is returned and
   * no object is created.  Otherwise, an object (new) for the existing storage
   * scope is returned.
   *
   * @param aWindow
   *    The parent window.
   * @param aPrincipal
   *    Principal to bound storage to.
   * @param aPrivate
   *    Whether the demanding document is running in Private Browsing mode or not.
   */
  nsIDOMStorage getStorage(in mozIDOMWindow aWindow,
                           in nsIPrincipal aPrincipal,
                           [optional] in bool aPrivate);

  /**
   * Clones given storage into this storage manager.
   *
   * @param aStorageToCloneFrom
   *    The storage to copy all items from into this manager.  Manager will then
   *    return a new and independent object that contains snapshot of data from
   *    the moment this method was called.  Modification to this new object will
   *    not affect the original storage content we cloned from and vice versa.
   */
  void cloneStorage(in nsIDOMStorage aStorageToCloneFrom);

  /**
   * Returns true if the storage belongs to the given principal and is managed
   * (i.e. has been created and is cached) by this storage manager.
   *
   * @param aPrincipal
   *    Principal to check the storage against.
   * @param aStorage
   *    The storage object to examine.
   *
   * @result
   *    true when the storage object is bound with the principal and is managed
   *         by this storage manager.
   *    false otherwise
   */
  bool checkStorage(in nsIPrincipal aPrincipal,
                    in nsIDOMStorage aStorage);

  /**
   * @deprecated
   *
   * Returns instance of localStorage object for aURI's origin.
   * This method ensures there is always only a single instance
   * for a single origin.
   *
   * Currently just forwards to the createStorage method of this
   * interface.
   *
   * Extension developers are strongly encouraged to use getStorage
   * or createStorage method instead.
   */
  nsIDOMStorage getLocalStorageForPrincipal(in nsIPrincipal aPrincipal,
                                            in DOMString aDocumentURI,
                                            [optional] in bool aPrivate);
};