dom/interfaces/storage/nsIDOMStorageManager.idl
author Kyle Huey <khuey@kylehuey.com>
Tue, 05 Nov 2013 22:16:25 +0800
changeset 153570 aab2a2b73b900689ad2b16dcd7f3ba694c4fcf2e
parent 128768 8480e7da11d17bf6925932cd60548c8cd3e9f399
child 195640 326c91338df021db68e55ac9549c6dc7e5eb906b
permissions -rw-r--r--
Bug 933099: Banish <windows.h> from nsGlobalWindow.cpp. r=bz

/* -*- 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;

/**
 * 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(8096f9ea-fa61-4960-b5d7-fb30ac42c8d8)]
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 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 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 aPrincipal
   *    Principal to bound storage to.
   * @param aPrivate
   *    Whether the demanding document is running in Private Browsing mode or not.
   */
  nsIDOMStorage getStorage(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);
};