Merge Chromium + Blink git repositories

[chromium-blink-merge.git] / chrome / common / extensions / docs / templates / articles / offline_storage.html

<h1>Managing HTML5 Offline Storage</h1>

<p>
HTML5 introduced many storage APIs that let you  store a large amount of data locally in your users' browsers. But the amount of space allocated for each app is, by default, restricted to a few megabytes. Google Chrome  lets you ask for a larger storage quota, beyond the previous limit of just 5 MB. </p>
<p>This document introduces you to the basic concepts around the types of storage used in Chrome and describes the experimental Quota Management API, which lets you manage your storage quota. The document assumes that you are already familiar with the  general concepts of client-side storage  and know how to use  offline APIs. </p>
<h2 id="contents">Contents</h2>
<ol>
  <li><a href="#types">Types of storage</a>
  <ol>
    <li><a href="#temporary">Temporary  </a></li>
    <li><a href="#persistent">Persistent</a></li>
    <li><a href="#unlimited">Unlimited</a></li>
    <li><a href="#table">Comparing Storage Types</a></li>
  </ol>
  </li>
 
  <li><a href="#managing_quota">Managing your quota</a>
  <ol>
  <li><a href="#query">Query  storage usage and availability</a></li>
  <li><a href="#asking_more">Ask for more storage</a></li>
  <li><a href="#reset">Reset quota for testing</a></li>
  </ol>
  
  </li>
  <li><a href="#reference">API reference</a>
    <ol>
  <li><a href="#constants">Constants</a></li>
  <li><a href="#method_overview">Method overview</a></li>
  <li><a href="#methods">Methods</a></li>
  </ol>
  
  </li>
  <li><a href="#future">Future development</a></li>
</ol>
<h2 id="types">Types of storage</h2>
<p>In Google Chrome, you can ask for three types of storage: </p>
<ul>
  <li><a href="#temporary">Temporary  </a></li>
  <li><a href="#persistent">Persistent</a></li>
  <li><a href="#unlimited">Unlimited</a></li>
</ul>
<p>These storage types are described in greater detail in the following sections and  compared with each other in the <a href="#table">table</a> below. </p>
<h3 id="temporary">Temporary  storage</h3>
<p id="temporary">Temporary  storage is transient storage that is available to any web app. Chrome automatically gives your  app temporary storage, so you do not need to request allocation. </p>
<h4>Sharing the pool</h4>
<p>Temporary storage is shared among all web apps  running in the browser.{#It is also shared across all offline APIs, such as App Cache, IndexedDB, and File System. However, it does not include web storage APIs like Local Storage and Session Storage, which still has a limit of  5 MB per origin.#} The shared pool can be up to 1/3 of the of available disk space. Storage already used by apps  is included in the calculation of the shared pool; that is to say, the calculation is based on <code>(available storage space + storage being used by apps) * .333</code> . </p>
<p>Each app  can have up to 20% of the shared pool. As an example, if the total available disk space is 60 GB, the shared pool is 20 GB, and the app can have up to 4 GB.  This is calculated from 20% (up to 4 GB) of 1/3 (up to 20 GB) of the available disk space (60 GB). </p>
<h4>Asking for more space</h4>
<p>Although you can <a href="#query">query</a> for the amount of  storage space available for your app and the amount of data  already  stored for your app, you cannot ask for more temporary storage space. If  an app exceeds the  allocated quota, an error is thrown.</p>
<h4>Running out of storage</h4>
<p>Once the storage quota for the entire pool is exceeded, the entire  data  stored for the least recently used host gets deleted.  The browser, however, will not expunge the data in LocalStorage and SessionStorage. For data stored in other offline APIs, the browser deletes the data in whole and not in part so that app data doesn't get corrupted in unexpected ways. </p>
<p>As each app is limited to a maximum of 20% of the storage pool, deletion is  likely only if the user is actively running more than five offline apps that are each using the maximum storage. </p>
<p>However, available storage space can shrink as users add more files on their hard drives. When the available disk space gets tight (Remember, the shared pool only gets  half of the <em>current</em> available disk space), the browser deletes all the data stored for the least recently used host. </p>

<h3 id="persistent">Persistent  storage</h3>
<p>Persistent storage is storage that stays in the browser unless the user expunges it. It is available only to apps that use the File System API, but will eventually be available to other offline APIs like IndexedDB   and Application Cache.</p>
<p>An application can have a larger quota for persistent storage than temporary storage, but you must request  storage using the Quota Management API and the user must grant you  permission to use more space. Chrome presents an info bar that prompts the user to grant the app more local storage space.</p>

<h3 id="unlimited">Unlimited   storage</h3>
<p>Unlimited storage is similar to persistent storage, but it is available only to  Chrome apps and extensions (.crx files). The size of unlimited storage is limited only by the availability of space in the user's hard drive. You can ask for the <code>unlimitedStorage</code> permission in the manifest file for an <a href="/chrome/apps/docs/developers_guide#manifest">app</a> or <a href="http://code.google.com/chrome/extensions/manifest.html#permissions">extension</a>. At installation, the user is informed of permissions required by the app or extension. By proceeding with the installation, the user implicitly grants  permission for all pages whose URLs are listed in the manifest.json file.</p>
<p>To learn more, see the respective developer guides for <a href="/chrome/apps/docs/developers_guide#manifest">apps</a> and <a href="http://code.google.com/chrome/extensions/manifest.html">extensions</a>. </p>

<p class="backtotop"><a href="#top">Back to top</a></p>

<h3 id="table">Comparing Storage Types </h3>
<p>The following table  describes the differences among the three types of storage. <a name="table"></p>
<table>
    <tr>
        <th width="215" scope="col">&nbsp;</th>
        <th width="385" scope="col">Temporary storage</th>
        <th width="385" scope="col">Persistent storage</th>
        <th width="385" scope="col">Unlimited storage</th>
    </tr>
    <tr>
      <td><strong>Basic description</strong></td>
      <td><p>Transient storage that is available to any web app. </p>
      <p>It is automatic and does not need to be requested. </p></td>
      <td> Permanent storage that must be requested through the Quota Management API and granted by users.</td>
      <td><p>Permanent storage for Chrome extensions and apps. </p>
      <p>It is set in the manifest file and must be granted by users.</p></td>
    </tr>
    <tr>
      <td><strong>Availability</strong></td>
      <td><p>All web apps.</p></td>
      <td>All web apps.</td>
      <td>Unique to  <a href="http://code.google.com/chrome/extensions/index.html">Chrome extensions</a> as well as hosted and installed <a href="http://code.google.com/chrome/apps/index.html">web apps</a>.</td>
    </tr>
    <tr>
      <td><strong>Permission</strong></td>
      <td>None. You can use it without explicitly requesting  it. </td>
      <td><p>You have to request  more storage using the Quota Management API. </p></td>
      <td>You can ask for the <code>unlimitedStorage</code> permission in the manifest file for the  <a href="/chrome/apps/docs/developers_guide#manifest">app</a> or <a href="http://code.google.com/chrome/extensions/manifest.html#permissions">extension</a>. </td>
    </tr>
    <tr>
      <td><strong>User experience at first use</strong></td>
      <td>Invisible to the user. The app just runs.</td>
      <td><p>Chrome displays an info bar that prompts the user to either accept or decline the storage request. </p>
      <p>But if the amount of quota you request is actually less than the app's current allocation, no prompt is shown. The larger quota is kept. </p></td>
      <td><p>At installation, the user is informed of permissions required by the app or extension. By proceeding with the installation, the user implicitly grants  permission for all pages whose URLs are listed in the manifest.json file for <a href="/chrome/apps/docs/developers_guide#manifest">app</a>  or <a href="http://code.google.com/chrome/extensions/manifest.html">extension</a>.   </p></td>
    </tr>
   
    <tr>
      <td><strong>User experience at subsequent requests for increased storage </strong></td>
      <td>Not applicable. You cannot ask for more temporary storage.</td>
      <td><p>Chrome prompts the user again. </p>
      <p>&nbsp;</p>
      <p></p></td>
      <td>Chrome does not prompt the user after installation, regardless of the requests for increased quota by the app or extension.  </td>
    </tr>
    <tr>
      <td><strong>Persistence of data</strong></td>
      <td><p>Transient. The browser can delete the data.</p></td>
      <td><p>Persistent. The browser doesn't delete the data unless the user instructs it to. Data is available in subsequent accesses. </p>
      <p>Do not assume that the data is permanent, because the user can delete it. </p> </td>
      <td><p>Same as persistent storage. </p>
      <p>&nbsp;</p></td>
    </tr>
    <tr>
      <td><strong>Default storage space</strong></td>
      <td><p>Up to 20% of the shared pool.</p></td>
      <td>0 MB. You have to explicitly ask for a specific storage space. </td>
      <td><p>0 MB. You have to explicitly ask for <code>unlimitedStorage</code> in the manifest file. </p>
      <p>If you do not specify your storage requirements, Chrome allocates storage to the app from the shared pool of temporary storage. </p></td>
    </tr>
    <tr>
      <td><strong>Maximum storage space</strong></td>
      <td>Up to 20% of the shared pool. </td>
      <td>As large as the available space on the hard drive.  It has no fixed pool of storage.</td>
      <td>As large as the available space on the hard drive. </td>
    </tr>
    <tr>
      <td><strong>Recommended use case</strong></td>
      <td>Caching.</td>
      <td>Apps that work offline or have a large number of assets. </td>
      <td>Apps that were designed to run in Google Chrome.</td>
    </tr>
    <tr>
      <td><strong>APIs that can use it</strong></td>
      <td> <p>Offline APIs</p>
        <ul>
          <li>App Cache </li>
          <li> File System</li>
          <li> IndexedDB </li>
          <li> WebSQL (<a href="http://www.w3.org/TR/webdatabase/">deprecated</a> since November 18, 2010) </li>
        </ul>
     {% comment %}
<p class="note"><strong>Note:</strong> Web storage APIs like LocalStorage and SessionStorage remain fixed at 5 MB. </p>

{% endcomment %}</td>
      <td>File System API</td>
      <td><p>Offline APIs</p>
        <ul>
          <li>App Cache </li>
          <li> File System</li>
          <li> IndexedDB </li>
          <li> WebSQL (deprecated) </li>         
      </ul>
      {% comment %}
<p class="note"><strong>Note:</strong> Web storage APIs like LocalStorage and SessionStorage remain fixed at 5 MB.</p>

{% endcomment %}</td>
      </td>
    </tr>
</table>

<p class="backtotop"><a href="#top">Back to top</a></p>

<h2 id="managing_quota">Managing your quota</h2>
<p>With the Quota Management API, which was introduced in Chrome 13, you can do the following:</p>
<ul>
  <li><a href="#query">Query  storage usage and availability</a></li>
  <li><a href="#asking_more">Ask for more storage</a></li>
  <li><a href="#reset">Reset quota for testing</a></li>
</ul>
<p>The API is implemented with the  global object <code>window.webkitStorageInfo</code>. </p>
<p>For the reference documentation, see the <a href="#reference">next section</a>.</p>
<h3 id="query">Querying  storage usage and availability</h3>
<p>To query the storage size that is being used and the available space left for the host, call <code>queryUsageAndQuota()</code> with the following:</p>
<ul>
  <li>Type of storage you want to check</li>
  <li>Success callback </li>
</ul>
<p>The usage reported by the  API might not match  with the actual size of the user data, as each storage might need some extra bytes to store its metadata. Also, status updates can lag, resulting in the API not reflecting the most recent storage status. </p>
<p>The following code snippet shows how you can ask about storage space:</p>
<pre class="prettyprint">
// Request storage usage and capacity left
// Choose either Temporary or Persistent
navigator.webkitTemporaryStorage.queryUsageAndQuota ( 
    function(usedBytes, grantedBytes) {  
        console.log('we are using ', usedBytes, ' of ', grantedBytes, 'bytes');
    }, 
    function(e) { console.log('Error', e);  }
);
</pre>
<p>If you want to ask for the status of persistent storage, simply replace <span class="prettyprint"><code>webkitStorageInfo.<strong>TEMPORARY</strong></code></span> with <span class="prettyprint"><code>webkitStorageInfo.<strong>PERSISTENT</strong></code></span>. The enum is also in the <code>window</code> object (global namespace), so you can also use <code>window.<strong>PERSISTENT</strong></code> and  <code>window.<strong>TEMPORARY</strong></code>.</p>
<p class="backtotop"><a href="#top">Back to top</a></p>

<h3 id="asking_more">Asking for more storage</h3>
<p>You don't need to ask for more temporary storage as the allocation is automatic, and you can't get beyond the maximum limit (as described in the <a href="#table">table</a>). </p>
<p>For persistent storage for File System API, the  default quota is 0, so you need to explicitly request storage for your application. Call <code>requestQuota()</code> with the following:</p>
<ul>
  <li>Type of storage</li>
  <li>Size</li>
  <li>Success callback</li>
</ul>
<p>Depending on what you ask for, the following happens:</p>
<ul>
  <li>If you ask for a larger quota, the browser presents an info bar to the user and prompts them to either grant or deny permission for increased quota. In some cases, the request might be silently rejected, and the current quota or smaller quota is returned.</li>
  <li>If the amount of quota you request is less than the app's current allocation, no prompt is shown. </li>
  <li>If you ask for more storage than what is allowed, you get an error (<code>QUOTA_EXCEEDED_ERR</code>). </li>
  <li>If you call <code>requestQuota()</code> again after the user has already granted permission, nothing happens. So don't bother calling the method again.</li>
</ul>
<p>The following shows how you can ask for more storage space:</p>
<pre class="prettyprint">
// Request Quota (only for File System API) </span> 
var requestedBytes = 1024*1024*10; // 10MB

navigator.webkitPersistentStorage.requestQuota (
    requestedBytes, function(grantedBytes) {  
        window.requestFileSystem(PERSISTENT, grantedBytes, onInitFs, errorHandler);

    }, function(e) { console.log('Error', e); }
);
});</pre>
<p class="backtotop"><a href="#top">Back to top</a></p>

<h3 id="reset">Resetting quota for testing</h3>
<p>When you are testing storage in your app, you might want to clear the stored data so that you can test quota management afresh in your app. To do so:</p>
<ol>
  <li>Enter <code>chrome://settings/cookies</code> in the omnibox (the address bar). </li>
  <li>Search for your app.</li>
  <li>Select your app. </li>
  <li>Click the <strong>X</strong> on the  right side of the highlighted selection.</li>
</ol>


<p class="backtotop"><a href="#top">Back to top</a></p>

<h2 id="reference">API reference</h2>
<p>This section documents the methods of the Quota Management API.</p>
<h3 id="constants">Constants</h3>
<p>The  following are <code>webkitStorageInfo</code> constants, which indicate the type of storage. </p>
<table>
  <thead>
    <tr>
      <th scope="col" width="111">Constant</th>
      <th scope="col" width="53">Value</th>
      <th scope="col" width="690">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code><a name="const_done" id="const_done">TEMPORARY</a></code></td>
      <td>0</td>
      <td>Temporary storage.</td>
    </tr>
    <tr>
      <td><code><a name="const_loading" id="const_loading">PERSISTENT</a></code></td>
      <td>1</td>
      <td>Persistent storage. </td>
    </tr>
  </tbody>
</table>
<h3 id="method_overview">Method overview</h3>
<table>
  <tbody>
    <tr>
      <td><code>void <a href="#queryUsageAndQuota" title="#add">queryUsageAndQuota</a> (in unsigned short storageType, StorageInfoUsageCallback successCallback, in  optional StorageInfoErrorCallback errorCallback) </code></td>
    </tr>
    <tr>
      <td><code>void <a href="#requestQuota" title="#add">requestQuota</a> (in unsigned short storageType, unsigned long long newQuotaInBytes, optional StorageInfoQuotaCallback successCallback, optional StorageInfoErrorCallback errorCallback)</code></td>
    </tr>
  </tbody>
</table>
<h3 id="methods">Methods</h3>
<h4 id="queryUsageAndQuota">queryUsageAndQuota</h4>
<p>Check the storage size that is being used and the available space left for the host.</p>

<pre class="prettyprint"> // you could also use it from webkitPersistentStorage
navigator.webkitTemporaryStorage.queryUsageAndQuota(
      successCallback,
      errorCallback);</pre>
<dl>
  <dt>successCallback</dt>
  <dd>Optional callback with two parameters: <ul>
    <li>The current number of bytes the app is using. </li>
    <li>The number of bytes left in the quota. </li>
  </ul>
  </dd>
</dl>
<dl>
  <dt>errorCallback</dt>
  <dd>Optional error callback.</dd>
  <dt>&nbsp;</dt>
</dl>
<p class="backtotop"><a href="#top">Back to top</a></p>
<hr />
<h4 id="requestQuota">requestQuota</h4>

<p>Ask for more storage. The browser presents an info bar to prompt user to grant or deny the app the permission to have more storage.</p>

<pre class="prettyprint"> // you could also use it from webkitTemporaryStorage
navigator.webkitPersistentStorage.requestQuota (
      newQuotaInBytes,
      quotaCallback,
      errorCallback);</pre>

<h5>Parameters</h5>
<dl>
 
  <dt>newQuotaInBytes</dt>
  <dd>The amount of bytes you want in your storage quota.  </dd>
</dl>
<dl>
  <dt>successCallback</dt>
  <dd>Optional callback that passes the amount of bytes granted. </dd>
</dl>
<dl>
  <dt>errorCallback</dt>
  <dd>Optional error callback.</dd>
</dl>

<h2 id="future">Future development</h2>
<p>The plan is to put all HTML5 offline storage APIs—including IndexedDB, Application Cache, File System,{# LocalStorage, SessionStorage,#} and other APIs that might be specified—under the Quota Management API. You will be able to manage all storage allocation with it. </p>