Copyright © 2012-2013 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification defines an API to manage usage and availability of local storage resources, and defines a means by which a user agent (UA) may grant Web applications permission to use more local space, temporarily or persistently, via various different storage APIs.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document is a proposal that is being made available for public review in order to solicit feedback, particularly from implementors, with a goal of potential cross-browser implementation and standardization.
This document was published by the Web Applications (WebApps) Working Group as a Working Draft.
This document is intended to become a W3C Recommendation.
If you wish to make comments regarding this document, please send them to
public-webapps@w3.org
(subscribe,
archive)
with a Subject prefix of [quota-api]
.
All comments are welcome.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This section is non-normative.
Today we have a variety of storage APIs that can store inherently complex or large data in order to satisfy offline data requirements of Web applications. Examples of these APIs include: Application Cache [OFFLINE-WEBAPPS], FileSystem API [FILE-SYSTEM][NEW-FILE-SYSTEM], Indexed Database [INDEXEDDB] and Web SQL Database [WEB-SQL].
These APIs may require larger local space than the conventional cookie storage or Web Storage [WEBSTORAGE], but they do not provide a means by which a Web application can query and manage how much data is currently stored and how much more can be stored.
This specification defines an API to query and manage usage and availability of a user's local storage. The storage space granted by the API is intended to be shared by different storage APIs, therefore a user and UA only need to manage single upper limit for all storage per logical application unit, e.g. per origin or per browser (which is implementation specific).
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC2119].
User agents that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL] as this specification uses that specification and terminology.
The concept fires a simple event is defined in [HTML5].
The Event, EventTarget, EventListener interfaces are defined in [DOM4].
The DOMError and DOMException interfaces are defined in [DOM4].
The Promise interface is currently defined and discussed in the WHATWG DOM specification.
This section is non-normative.
A Web application can request temporary or persistent local storage space depending on its purpose.
Temporary type of storage is especially useful if an application wants to cache data locally to improve its performance, but can fall back to fetching or recreating the same data at a data loss.
Conversely, persistent type of storage is useful if an application wants to store critical offline data that is necessary to be functional, or wants to manage local data amount and lifetime on its own policy rather than relying on the UA's default eviction policy for temporary storage.
Suppose there is a photo editing application. This application manages user photo data using Indexed Database [INDEXEDDB], stores photo images using Filesystem API [FILE-SYSTEM] [NEW-FILE-SYSTEM] and optinally utilizes Application Cache [OFFLINE-WEBAPPS] to make it work offline.
The application needs to query how much data it can store in the temporary storage to determine its initial cache size.
// Query current usage and availability in Temporary storage: navigator.storageQuota.queryInfo("temporary").then( function(storageInfo) { // Continue to initialize local cache using the obtained // usage and remaining space (quota - usage) information. initializeCache(storageInfo.usage, storageInfo.quota - storageInfo.usage); });
Similarly, the application needs to request additional persistent storage to support offline mode when it is enabled by the user.
// A function which is to be called when 'offline-mode' is enabled // by the user. function onOfflineModeEnabled(amountOfSpaceNeeded) { // First check how much we can use in the Persistent storage. navigator.storageQuota.queryInfo("persistent").then( function (storageInfo) { var availableSpace = storageInfo.quota - storageInfo.usage; if (availableSpace >= amountOfSpaceNeeded) { // We're fine; just continue with the returned storage info. return storageInfo; } return navigator.storageQuota.requestPersistentQuota( amountOfSpaceNeeded + storageInfo.usage); } ).then( function (storageInfo) { // Prepare for offline mode using the current available // storage space. prepareForOfflineMode(storageInfo.quota - storageInfo.usage); }, function (error) { // Handle error. } ); }
StorageType
enumenum StorageType {
"temporary",
"persistent"
};
Enumeration description | |
---|---|
temporary | Indicates temporary storage type. |
persistent | Indicates persistent storage type. |
StorageInfo
interface[NoInterfaceObject]
interface StorageInfo {
readonly attribute unsigned long long usage;
readonly attribute unsigned long long quota;
};
quota
of type unsigned long long, readonly
The current upper limit of the storage space that can be used by
the application for a given storage type.
This includes the storage area that is already used by the
application, so storageInfo.usage
needs to be
subtracted from storageInfo.quota
to get the
remaining available storage space.
For temporary storage
this value may reflect the actual storage space available
on the user's local device and may change from time to time.
For persistent storage this value must return the
consistent quota size that is granted to the
application by requestPersistentQuota
.
If the application does not have the associated persistent
quota yet the UA may return a UA-specific default quota value
(which could be 0).
usage
of type unsigned long long, readonly The total amount of data (in bytes) stored by the application for a given storage type. Depending on how the UA calculates data usage the returned value may differ from the exact real-time usage of the user's physical local storage.
StorageQuota
interface
The StorageQuota
interface provides means to query
and request storage usage and quota information.
The API provided by the interface is asynchronous since
querying or allocating space in a user's local storage may require
blocking I/O operations, e.g. examining the local disk status or
making changes in a local database.
[NoInterfaceObject]
interface StorageQuota {
readonly attribute StorageType
[] supportedTypes;
Promise queryInfo (StorageType
type);
Promise requestPersistentQuota (unsigned long long newQuota);
};
supportedTypes
of type array of StorageType
, readonly queryInfo
This method queries the storage info of the given storage
type
.
This returns StorageInfo
that has the current data
usage and available quota information for the application.
When queryInfo
method is called, the UA must
run the following steps:
Promise
object.
supportedTypes
array),
let error be a new DOMError
created with the name "NotSupportedError" and
jump to the step labeled failure below.
DOMError
and jump to the step labeled failure below.
StorageInfo
object, created with
usage and quota, and
resolve promise
with storageInfo as its resulting value.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
type |
| ✘ | ✘ |
requestPersistentQuota
Requests a new quota in persistent storage
for the requesting application.
It is not guaranteed that the requested amount of space
is granted just by calling this API, and the UA
may return a new
object
(without rejecting the request) with a smaller quota value
than requested.
Calling this API may trigger user prompting to request
explicit user permission to proceed.
StorageInfo
requestPersistentQuota
method is
called, the UA must run the following steps:
Promise
object.
queryInfo
requests.
grantedQuota may be smaller than
newQuota, but must be equal to or greater than
the old quota.
DOMError
and jump to the step labeled failure below.
StorageInfo
object, created with
usage and grantedQuota, and
resolve promise
with storageInfo as its resulting value.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
newQuota |
| ✘ | ✘ |
StorageQuota
interface
StorageQuota
interface.
StorageEvent
interface
An event object implementing this interface is passed to
onstoragechange
event handler when storage information is updated.
[Constructor(DOMString type, optional StorageEventInit eventInitDict)]
interface StorageEvent : Event {
readonly attribute unsigned long long usage;
readonly attribute unsigned long long quota;
};
quota
of type unsigned long long, readonly usage
of type unsigned long long, readonly Events are constructed as defined in constructing events in [DOM4].
dictionary StorageEventInit : EventInit {
unsigned long long usage = 0;
unsigned long long quota = 0;
};
StorageEventInit
Membersquota
of type unsigned long long, defaulting to 0
usage
of type unsigned long long, defaulting to 0
StorageWatcher
interface
StorageWatcher
interface is to watch real time
storage changes. This fires storagechange
event
every time a storage status change is detected by the UA,
or about every rate
second(s),
whichever is least frequent.
If rate
is not given in the constructor, the UA
fires storagechange
event whenever it detects
the usage or quota changes in the backend, but no more frequent
than 50ms.
Regardless of the rate
value,
the UA must fire one storagechange
event
with the current storage status
immediately (but asynchronously) after a watcher is constructed,
unless close()
is called before the first
storagechange
event is dispatched.
[Constructor(StorageType type, optional unsigned long rate)]
interface StorageWatcher : EventTarget {
void close ();
readonly attribute StorageType
type;
readonly attribute unsigned long rate;
attribute EventListener onstoragechange;
};
onstoragechange
of type EventListener, storagechange
event.
rate
of type unsigned long, readonly rate
value which this
watcher is constructed with.
type
of type StorageType
, readonly type
which this
watcher is constructed with and is monitoring changes on.
close
The space queried and granted by StorageQuota
have the
following properties:
This section is non-normative.
Storage APIs except for Web Storage, i.e. Application Cache, File System API, Indexed Database and Web SQL Database, should respect the quota management API and must have following properties:DOMError
or DOMException
(including when the granted quota is zero, i.e. the UA refuses
to grant any quota or the storage is disabled for the site).
As an exception, if the write is being made in the background where
it cannot throw
exception or return an error, the API may fail silently. For example, Application Cache may silently discard or fail to cache data when it is hitting quota limit.
Indexed Database [INDEXEDDB] is expected to have temporary and persistent storage types in its next version, and when that happens the UA should store data for temporary database in temporary storage and for persistent database in persistent storage, respectively.
Many thanks to Robin Berjon for making our lives so much easier with his cool tool.