dom/webidl/Storage.webidl

   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 file,
   4 * You can obtain one at http://mozilla.org/MPL/2.0/.
   5 *
   6 * The origin of this IDL file is
   7 * http://www.whatwg.org/html/#the-storage-interface
   8 *
   9 * © Copyright 2004-2011 Apple Computer, Inc., Mozilla Foundation, and
  10 * Opera Software ASA. You are granted a license to use, reproduce
  11 * and create derivative works of this document.
  12 */
  13
  14 [Exposed=Window]
  15 interface Storage {
  16   [Throws, NeedsSubjectPrincipal]
  17   readonly attribute unsigned long length;
  18
  19   [Throws, NeedsSubjectPrincipal]
  20   DOMString? key(unsigned long index);
  21
  22   [Throws, NeedsSubjectPrincipal]
  23   getter DOMString? getItem(DOMString key);
  24
  25   [Throws, NeedsSubjectPrincipal]
  26   setter undefined setItem(DOMString key, DOMString value);
  27
  28   [Throws, NeedsSubjectPrincipal]
  29   deleter undefined removeItem(DOMString key);
  30
  31   [Throws, NeedsSubjectPrincipal]
  32   undefined clear();
  33
  34   [ChromeOnly]
  35   readonly attribute boolean isSessionOnly;
  36 };
  37
  38 /**
  39  * Testing methods that exist only for the benefit of automated glass-box
  40  * testing.  Will never be exposed to content at large and unlikely to be useful
  41  * in a WebDriver context.
  42  */
  43 partial interface Storage {
  44   /**
  45    * Does a security-check and ensures the underlying database has been opened
  46    * without actually calling any database methods.  (Read-only methods will
  47    * have a similar effect but also impact the state of the snapshot.)
  48    */
  49   [Throws, NeedsSubjectPrincipal, Pref="dom.storage.testing"]
  50   undefined open();
  51
  52   /**
  53    * Automatically ends any explicit snapshot and drops the reference to the
  54    * underlying database, but does not otherwise perturb the database.
  55    */
  56   [Throws, NeedsSubjectPrincipal, Pref="dom.storage.testing"]
  57   undefined close();
  58
  59   /**
  60    * Ensures the database has been opened and initiates an explicit snapshot.
  61    * Snapshots are normally automatically ended and checkpointed back to the
  62    * parent, but explicitly opened snapshots must be explicitly ended via
  63    * `endExplicitSnapshot` or `close`.
  64    */
  65   [Throws, NeedsSubjectPrincipal, Pref="dom.storage.testing"]
  66   undefined beginExplicitSnapshot();
  67
  68   /**
  69    * Checkpoints the explicitly begun snapshot. This is only useful for testing
  70    * of snapshot re-using when multiple checkpoints are involved. There's no
  71    * need to call this before `endExplicitSnapshot` because it checkpoints the
  72    * snapshot before it's ended.
  73    */
  74   [Throws, NeedsSubjectPrincipal, Pref="dom.storage.testing"]
  75   undefined checkpointExplicitSnapshot();
  76
  77   /**
  78    * Ends the explicitly begun snapshot and retains the underlying database.
  79    * Compare with `close` which also drops the reference to the database.
  80    */
  81   [Throws, NeedsSubjectPrincipal, Pref="dom.storage.testing"]
  82   undefined endExplicitSnapshot();
  83
  84   /**
  85    * Returns true if the underlying database has been opened, the database is
  86    * not being closed and it has a snapshot (initialized implicitly or
  87    * explicitly).
  88    */
  89   [Throws, NeedsSubjectPrincipal, Pref="dom.storage.testing"]
  90   readonly attribute boolean hasSnapshot;
  91
  92   /**
  93    * Returns snapshot usage.
  94    *
  95    * @throws NS_ERROR_NOT_AVAILABLE if the underlying database hasn't been
  96    *         opened or the database is being closed or it doesn't have a
  97    *         snapshot.
  98    */
  99   [Throws, NeedsSubjectPrincipal, Pref="dom.storage.testing"]
 100   readonly attribute long long snapshotUsage;
 101 };