Copyright © 2012 W3C® (MIT, ERCIM, Keio), 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 was published by the Web Applications (WebApps) Working Group as a First Public 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, archives). All feedback is 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.
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].
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], File API: Directories and System (File System API) [FILE-SYSTEM], Indexed Database [INDEXEDDB] and Web SQL Database [WEBSQL].
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).
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] 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.temporaryStorage.queryUsageAndQuota( function (usage, quota) { // Continue to initialize local cache using the obtained // usage and quota (availability) information. initializeCache(usage, quota); }, function (error) { log("Got error: ", error); });
Similarly, the application needs to request additional persistent storage to support offline mode when it is enabled by the user.
function onError(error) { // Handle an error. log("Got error: ", error); } function setUpOfflineMode(availableSpace) { // ... } // A function which is to be called when 'offline-mode' is enabled. function onOfflineEnabled(amountOfSpaceNeeded) { // First check how much we can use in the Persistent storage. navigator.persistentStorage.queryUsageAndQuota( function (usage, quota) { var availableSpace = quota - usage; if (availableSpace >= amountOfSpaceNeeded) { // We're fine; just continue to set up offline mode. setUpOfflineMode(availableSpace); return; } var requestingQuota = amountOfSpaceNeeded + usage; navigator.persistentStorage.requestQuota( requestingQuota, function (grantedQuota) { setUpOfflineMode(grantedQuota - usage); }, onError); }, onError); }
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.
interface StorageQuota {
void queryUsageAndQuota (in StorageUsageCallback
successCallback, in optional StorageErrorCallback
errorCallback);
void requestQuota (in unsigned long long newQuotaInBytes, in optional StorageQuotaCallback
successCallback, in optional StorageErrorCallback
errorCallback);
};
queryUsageAndQuota
Queries the current usage (how much data is stored) and
quota available for the requesting application.
Either one of
successCallback
or errorCallback
is called to indicate the request is successfully handled or not.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
successCallback |
| ✘ | ✘ | |
errorCallback |
| ✘ | ✔ |
void
requestQuota
Requests a new quota for the requesting application.
It is not guaranteed that the requested amount of space
is granted just by calling this API.
Calling this API may trigger user prompting to request
explicit user permission to proceed.
Either one of successCallback
or errorCallback
is called to indicate
the request is successfully handled or not.
successCallback
may return a smaller amount of quota
than requested.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
newQuotaInBytes | unsigned long long | ✘ | ✘ | |
successCallback |
| ✘ | ✔ | |
errorCallback |
| ✘ | ✔ |
void
This interface is defined after the storage model defined in File System API [FILE-SYSTEM], and therefore uses the terminology and interface model similar to the API, e.g. employing Callback model rather than Event model.
The space queried and granted by StorageQuota
must have the
following properties:
StorageUsageCallback
callbackThis callback is used to return usage and quota information.
callback StorageUsageCallback = void (in unsigned long long currentUsageInBytes, in unsigned long long currentQuotaInBytes);
Used to supply the current usage and quota information in bytes.
currentUsageInBytes
indicates the total amount of data
stored in the storage of the requested storage type.
Depending on the UA's usage tracking system
the returned value may differ from the exact real-time usage of the
user's physical local storage.
currentQuotaInBytes
indicates the current upper limit
of the storage space that is exposed to and can be used
by the requesting application.
StorageQuotaCallback
callbackThis callback is used to return a new quota information granted by a UA.
callback StorageQuotaCallback = void (in unsigned long long grantedQuotaInBytes);
StorageErrorCallback
callbackThis interface is the callback used to indicate an error has occured.
callback StorageErrorCallback = void (in DOMError error);
error
parameter.
StorageQuota
All instances of Navigator
type are defined to also implement
StorageQuotaEnvironment
interface.
[NoInterfaceObject]
interface StorageQuotaEnvironment {
readonly attribute StorageQuota
persistentStorage;
readonly attribute StorageQuota
temporaryStorage;
};
persistentStorage
of type StorageQuota
, readonlytemporaryStorage
of type StorageQuota
, readonlyThis 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
[DOM4]. However, 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.
StorageQuota
be able to tell which storage API is participating the unified quota management?
StorageQuota
be able to tell which type of storage the UA is willing to use as the default storage type for storage APIs other than in File System API?
Many thanks to Robin Berjon for making our lives so much easier with his cool tool.