- From: CVS User abarsto <cvsmail@w3.org>
- Date: Sat, 19 Apr 2014 11:50:12 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/file-system/pub/FileSystem
In directory roscoe:/tmp/cvs-serv31279
Modified Files:
Overview.html
Log Message:
This version is the April 2014 WG NOTE
--- /sources/public/2009/dap/file-system/pub/FileSystem/Overview.html 2012/04/17 00:03:11 1.12
+++ /sources/public/2009/dap/file-system/pub/FileSystem/Overview.html 2014/04/19 11:50:12 1.13
@@ -1,1419 +1,255 @@
-<!DOCTYPE html PUBLIC '-//W3C//DTD HTML 4.01 Transitional//EN' 'http://www.w3.org/TR/html4/loose.dtd'>
-<html lang="en" dir="ltr">
-<head>
- <title>File API: Directories and System</title>
- <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
-
-
- <link href="Overview_files/respec.css" rel="stylesheet" type="text/css" charset="utf-8">
- <link href="http://www.w3.org/StyleSheets/TR/W3C-WD" rel="stylesheet" type="text/css" charset="utf-8"></head>
- <body style="display: inherit; "><div class="head"><p><a href="http://www.w3.org/"><img width="72" height="48" src="http://www.w3.org/Icons/w3c_home" alt="W3C"></a></p><h1 class="title" id="title">File <acronym title="Application Programming
- Interface">API</acronym>: Directories and System</h1><h2 id="w3c-working-draft-17-april-2012"><acronym title="World Wide Web Consortium">W3C</acronym> Working Draft 17 April 2012</h2><dl><dt>This version:</dt><dd><a href="http://www.w3.org/TR/2012/WD-file-system-api-20120417/">http://www.w3.org/TR/2012/WD-file-system-api-20120417/</a></dd><dt>Latest published version:</dt><dd><a href="http://www.w3.org/TR/file-system-api/">http://www.w3.org/TR/file-system-api/</a></dd><dt>Latest editor's draft:</dt><dd><a href="http://dev.w3.org/2009/dap/file-system/file-dir-sys.html">http://dev.w3.org/2009/dap/file-system/file-dir-sys.html</a></dd><dt>Previous version:</dt><dd><a href="http://www.w3.org/TR/2011/WD-file-system-api-20110419/">http://www.w3.org/TR/2011/WD-file-system-api-20110419/</a></dd><dt>Editor:</dt><dd><a href="http://www.ofb.net/~uranium/">Eric Uhrhane</a>, <a href="http://www.google.com/">Google</a></dd>
-</dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2012 <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.eu/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. <acronym title="World Wide Web Consortium">W3C</acronym> <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p><hr></div>
- <div id="abstract" class="introductory section"><h2>Abstract</h2><p>
- This specification defines an <acronym title="Application Programming
- Interface">API</acronym> to navigate file system hierarchies, and defines
- a means by which a <a href="#dfn-user-agent" class="internalDFN">user agent</a> may expose sandboxed sections of a
- user's local filesystem to web applications. It builds on
- [<cite><a class="bibref" rel="biblioentry" href="#bib-FILE-WRITER-ED">FILE-WRITER-ED</a></cite>], which in turn built on [<cite><a class="bibref" rel="biblioentry" href="#bib-FILE-API-ED">FILE-API-ED</a></cite>], each adding a
- different kind of functionality.
- </p></div><div id="sotd" class="introductory section"><h2>Status of This Document</h2><p><em>This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current <acronym title="World Wide Web Consortium">W3C</acronym> publications and the latest revision of this technical report can be found in the <a href="http://www.w3.org/TR/"><acronym title="World Wide Web Consortium">W3C</acronym> technical reports index</a> at http://www.w3.org/TR/.</em></p><p>This document was published by the <a href="http://www.w3.org/2008/webapps/">WebApps Working Group</a> as a Working Draft. This document is intended to become a <acronym title="World Wide Web Consortium">W3C</acronym> Recommendation. If you wish to make comments regarding this document, please send them to <a href="mailto:public-webapps@w3.org">public-webapps@w3.org</a> (<a href="mailto:public-webapps-request@w3.org?subject=subscribe">subscribe</a>, <a href="http://lists.w3.org/Arhives/Public/public-webapps/">archives</a>). All feedback is welcome.</p><p>Publication as a Working Draft does not imply endorsement by the <acronym title="World Wide Web Consortium">W3C</acronym> 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.</p><p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004 <acronym title="World Wide Web Consortium">W3C</acronym> Patent Policy</a>. <acronym title="World Wide Web Consortium">W3C</acronym> maintains a <a href="http://www.w3.org/2004/01/pp-impl/42538/status" rel="disclosure">public list of any patent disclosures</a> 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 <a href="http://www.w3.org/Cnsortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the <acronym title="World Wide Web Consortium">W3C</acronym> Patent Policy</a>.</p></div><div id="toc" class="section"><h2 class="introductory">Table of Contents</h2><ul class="toc"><li class="tocline"><a href="#conformance" class="tocxref"><span class="secno">1. </span>Conformance</a></li><li class="tocline"><a href="#introduction" class="tocxref"><span class="secno">2. </span>Introduction</a><ul class="toc"><li class="tocline"><a href="#use-cases" class="tocxref"><span class="secno">2.1 </span>Use Cases</a></li><li class="tocline"><a href="#examples" class="tocxref"><span class="secno">2.2 </span>Examples</a></li></ul></li><li class="tocline"><a href="#terminology" class="tocxref"><span class="secno">3. </span>Terminology</a></li><li class="tocline"><a href="#data-persistence-and-accessing-the-api"class="tocxref"><span class="secno">4. </span>Data Persistence and accessing the <acronym title="Application Programming
- Interface">API</acronym></a><ul class="toc"><li class="tocline"><a href="#temporary-vs.-persistent-storage" class="tocxref"><span class="secno">4.1 </span>Temporary vs. Persistent Storage</a></li><li class="tocline"><a href="#restrictions" class="tocxref"><span class="secno">4.2 </span>Restrictions</a></li><li class="tocline"><a href="#security-considerations" class="tocxref"><span class="secno">4.3 </span>Security Considerations</a></li><li class="tocline"><a href="#obtaining-access-to-file-system-entry-points" class="tocxref"><span class="secno">4.4 </span>Obtaining access to file system entry points</a><ul class="toc"><li class="tocline"><a href="#using-localfilesystem" class="tocxref"><span class="secno">4.4.1 </span>Using <code>LocalFileSystem</code></a><ul class="toc"><li class="tocline"><a href="#methods" class="tocxref"><span class="secno">4.4.1.1 </span>Methods</a></li><li class="tocline"><a href="#constants" class="tocxref"><span class="secno">4.4.1.2 </span>Constants</a></li></ul></li><li lass="tocline"><a href="#using-localfilesystemsync" class="tocxref"><span class="secno">4.4.2 </span>Using <code>LocalFileSystemSync</code></a><ul class="toc"><li class="tocline"><a href="#methods-1" class="tocxref"><span class="secno">4.4.2.1 </span>Methods</a></li><li class="tocline"><a href="#constants-1" class="tocxref"><span class="secno">4.4.2.2 </span>Constants</a></li></ul></li></ul></li></ul></li><li class="tocline"><a href="#shared-data-types" class="tocxref"><span class="secno">5. </span>Shared data types</a><ul class="toc"><li class="tocline"><a href="#the-metadata-interface" class="tocxref"><span class="secno">5.1 </span>The <code>Metadata</code> interface</a><ul class="toc"><li class="tocline"><a href="#attributes" class="tocxref"><span class="secno">5.1.1 </span>Attributes</a></li></ul></li><li class="tocline"><a href="#the-flags-dictionary" class="tocxref"><span class="secno">5.2 </span>The <code>Flags</code> dictionary</a><ul class="toc"><li class="tocline"><a href="#dictionary-flags-member" class="tocxref"><span class="secno">5.2.1 </span>Dictionary <span class="idlType formerLink idlType"><code>Flags</code></span> Members</a></li><li class="tocline"><a href="#examples-1" class="tocxref"><span class="secno">5.2.2 </span>Examples</a></li></ul></li></ul></li><li class="tocline"><a href="#the-asynchronous-filesystem-interface" class="tocxref"><span class="secno">6. </span>The asynchronous filesystem interface</a><ul class="toc"><li class="tocline"><a href="#the-filesystem-interface" class="tocxref"><span class="secno">6.1 </span>The <code>FileSystem</code> interface</a><ul class="toc"><li class="tocline"><a href="#attributes-1" class="tocxref"><span class="secno">6.1.1 </span>Attributes</a></li></ul></li><li class="tocline"><a href="#the-entry-interface" class="tocxref"><span class="secno">6.2 </span>The <code>Entry</code> interface</a><ul class="toc"><li class="tocline"><a href="#attributes-2" class="tocxref"><span class="secno">6.2.1 </span>Attributes</a></li><li class="tocline"><a href="#metods-2" class="tocxref"><span class="secno">6.2.2 </span>Methods</a></li></ul></li><li class="tocline"><a href="#the-directoryentry-interface" class="tocxref"><span class="secno">6.3 </span>The <code>DirectoryEntry</code> interface</a><ul class="toc"><li class="tocline"><a href="#methods-3" class="tocxref"><span class="secno">6.3.1 </span>Methods</a></li></ul></li><li class="tocline"><a href="#the-directoryreader-interface" class="tocxref"><span class="secno">6.4 </span>The <code>DirectoryReader</code> interface</a><ul class="toc"><li class="tocline"><a href="#methods-4" class="tocxref"><span class="secno">6.4.1 </span>Methods</a></li></ul></li><li class="tocline"><a href="#the-fileentry-interface" class="tocxref"><span class="secno">6.5 </span>The <code>FileEntry</code> interface</a><ul class="toc"><li class="tocline"><a href="#methods-5" class="tocxref"><span class="secno">6.5.1 </span>Methods</a></li></ul></li><li class="tocline"><a href="#callbacks" class="tocxref"><span class="secno">6.6 </span>Callback</a><ul class="toc"><li class="tocline"><a href="#the-filesystemcallback-interface" class="tocxref"><span class="secno">6.6.1 </span>The <code>FileSystemCallback</code> interface</a><ul class="toc"><li class="tocline"><a href="#methods-6" class="tocxref"><span class="secno">6.6.1.1 </span>Methods</a></li></ul></li><li class="tocline"><a href="#the-entrycallback-interface" class="tocxref"><span class="secno">6.6.2 </span>The <code>EntryCallback</code> interface</a><ul class="toc"><li class="tocline"><a href="#methods-7" class="tocxref"><span class="secno">6.6.2.1 </span>Methods</a></li></ul></li><li class="tocline"><a href="#the-entriescallback-interface" class="tocxref"><span class="secno">6.6.3 </span>The <code>EntriesCallback</code> interface</a><ul class="toc"><li class="tocline"><a href="#methods-8" class="tocxref"><span class="secno">6.6.3.1 </span>Methods</a></li></ul></li><li class="tocline"><a href="#the-metadatacallback-interface" class="tocxref"><span class="secno">6.6.4 </span>The <code>MetadataCllback</code> interface</a><ul class="toc"><li class="tocline"><a href="#methods-9" class="tocxref"><span class="secno">6.6.4.1 </span>Methods</a></li></ul></li><li class="tocline"><a href="#the-filewritercallback-interface" class="tocxref"><span class="secno">6.6.5 </span>The <code>FileWriterCallback</code> interface</a><ul class="toc"><li class="tocline"><a href="#methods-10" class="tocxref"><span class="secno">6.6.5.1 </span>Methods</a></li></ul></li><li class="tocline"><a href="#the-filecallback-interface" class="tocxref"><span class="secno">6.6.6 </span>The <code>FileCallback</code> interface</a><ul class="toc"><li class="tocline"><a href="#methods-11" class="tocxref"><span class="secno">6.6.6.1 </span>Methods</a></li></ul></li><li class="tocline"><a href="#the-voidcallback-interface" class="tocxref"><span class="secno">6.6.7 </span>The <code>VoidCallback</code> interface</a><ul class="toc"><li class="tocline"><a href="#methods-12" class="tocxref"><span class="secno">6.6.7.1 </span>Methods</a></li></ul</li><li class="tocline"><a href="#the-errorcallback-interface" class="tocxref"><span class="secno">6.6.8 </span>The <code>ErrorCallback</code> interface</a><ul class="toc"><li class="tocline"><a href="#methods-13" class="tocxref"><span class="secno">6.6.8.1 </span>Methods</a></li></ul></li></ul></li></ul></li><li class="tocline"><a href="#the-synchronous-filesystem-interface" class="tocxref"><span class="secno">7. </span>The synchronous filesystem interface</a><ul class="toc"><li class="tocline"><a href="#the-filesystemsync-interface" class="tocxref"><span class="secno">7.1 </span>The <code>FileSystemSync</code> interface</a><ul class="toc"><li class="tocline"><a href="#attributes-3" class="tocxref"><span class="secno">7.1.1 </span>Attributes</a></li></ul></li><li class="tocline"><a href="#the-entrysync-interface" class="tocxref"><span class="secno">7.2 </span>The <code>EntrySync</code> interface</a><ul class="toc"><li class="tocline"><a href="#attributes-4" class="tocxref"><span class="secno">7.2.1 </spanAttributes</a></li><li class="tocline"><a href="#methods-14" class="tocxref"><span class="secno">7.2.2 </span>Methods</a></li></ul></li><li class="tocline"><a href="#the-directoryentrysync-interface" class="tocxref"><span class="secno">7.3 </span>The <code>DirectoryEntrySync</code> interface</a><ul class="toc"><li class="tocline"><a href="#methods-15" class="tocxref"><span class="secno">7.3.1 </span>Methods</a></li></ul></li><li class="tocline"><a href="#the-directoryreadersync-interface" class="tocxref"><span class="secno">7.4 </span>The <code>DirectoryReaderSync</code> interface</a><ul class="toc"><li class="tocline"><a href="#methods-16" class="tocxref"><span class="secno">7.4.1 </span>Methods</a></li></ul></li><li class="tocline"><a href="#the-fileentrysync-interface" class="tocxref"><span class="secno">7.5 </span>The <code>FileEntrySync</code> interface</a><ul class="toc"><li class="tocline"><a href="#methods-17" class="tocxref"><span class="secno">7.5.1 </span>Methods</a></li></ul></li></ul></li><li cass="tocline"><a href="#errors-and-exceptions" class="tocxref"><span class="secno">8. </span>Errors and Exceptions</a><ul class="toc"><li class="tocline"><a href="#occurrence" class="tocxref"><span class="secno">8.1 </span>Occurrence</a></li><li class="tocline"><a href="#definitions" class="tocxref"><span class="secno">8.2 </span>Definitions</a></li></ul></li><li class="tocline"><a href="#uniformity-of-interface" class="tocxref"><span class="secno">9. </span>Uniformity of interface</a><ul class="toc"><li class="tocline"><a href="#case-sensitivity" class="tocxref"><span class="secno">9.1 </span>Case-sensitivity</a></li><li class="tocline"><a href="#encoding" class="tocxref"><span class="secno">9.2 </span>Encoding</a></li><li class="tocline"><a href="#naming-restrictions" class="tocxref"><span class="secno">9.3 </span>Naming restrictions</a></li><li class="tocline"><a href="#directories" class="tocxref"><span class="secno">9.4 </span>Directories</a></li></ul></li><li class="tocline"><a href="#acknowledgements class="tocxref"><span class="secno">A. </span>Acknowledgements</a></li><li class="tocline"><a href="#references" class="tocxref"><span class="secno">B. </span>References</a><ul class="toc"><li class="tocline"><a href="#normative-references" class="tocxref"><span class="secno">B.1 </span>Normative references</a></li><li class="tocline"><a href="#informative-references" class="tocxref"><span class="secno">B.2 </span>Informative references</a></li></ul></li></ul></div>
-
- <div id="conformance" class="section"><!--OddPage--><h2><span class="secno">1. </span>Conformance</h2><p>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.</p>
-<p>The key words <em class="rfc2119" title="must">must</em>, <em class="rfc2119" title="must not">must not</em>, <em class="rfc2119" title="required">required</em>, <em class="rfc2119" title="should">should</em>, <em class="rfc2119" title="should not">should not</em>, <em class="rfc2119" title="recommended">recommended</em>, <em class="rfc2119" title="may">may</em>, and <em class="rfc2119" title="optional">optional</em> in this specification are to be interpreted as described in [<cite><a class="bibref" rel="biblioentry" href="#bib-RFC2119">RFC2119</a></cite>].</p>
-
- <p>
- This specification defines conformance criteria that apply to a single
- product: a <dfn id="dfn-user-agent">user agent</dfn> that implements the interfaces that it
- contains.
- </p>
- </div>
-
- <div class="informative section" id="introduction">
- <!--OddPage--><h2><span class="secno">2. </span>Introduction</h2><p><em>This section is non-normative.</em></p>
- <p>
- This <acronym title="Application Programming
- Interface">API</acronym> is intended to satisfy client-side-storage use cases not
- well served by databases. These are generally applications that involve
- large binary blobs and/or share data with applications outside of the
- browser.
- </p>
- <p>
- It is intended to be minimal in extent, but sufficiently powerful that
- easy-to-use libraries may be built on top of it.
- </p>
- <div id="use-cases" class="section">
- <h3><span class="secno">2.1 </span>Use Cases</h3>
- <ol>
- <li>Persistent uploader
- <ul>
- <li>When a file or directory is selected for upload, it copies it
- into a local sandbox and uploads a chunk at a time.</li>
- <li>It can restart uploads after browser crashes, network
- interruptions, etc.</li>
- </ul>
- </li>
- <li>Video game or other app with lots of media assets
- <ul>
- <li>It downloads one or several large tarballs, and expands them
- locally into a directory structure.</li>
- <li>The same download should work on any operating system.</li>
- <li>It can manage prefetching just the next-to-be-needed assets in
- the background, so going to the next game level or activating a new
- feature doesn't require waiting for a download.</li>
- <li>It uses those assets directly from its local cache, by direct
- file reads or by handing local URLs to image or video tags, WebGL
- asset loaders, etc.</li>
- <li>The files may be of arbitrary binary format.</li>
- <li>On the server side, a compressed tarball will often be much
- smaller than a collection of separately-compressed files. Also, 1
- tarball instead of 1000 little files will involve fewer seeks, all
- else being equal.</li>
- </ul>
- </li>
-
- <li>Audio/Photo editor with offline access or local cache for speed
- <ul>
- <li>The data blobs are potentially quite large, and are
- read-write.</li>
- <li>It may want to do partial writes to files (ovewriting just the
- ID3/EXIF tags, for example).</li>
- <li>The ability to organize project files by creating directories
- would be useful.</li>
- <li>Edited files should be accessable by client-side applications
- [iTunes, Picasa].
- </li></ul>
- </li>
-
- <li>Offline video viewer
- <ul>
- <li>It downloads large files (>1GB) for later viewing.</li>
- <li>It needs efficient seek + streaming.</li>
- <li>It must be able to hand a URL to the video tag.</li>
- <li>It should enable access to partly-downloaded files e.g. to let
- you watch the first episode of the DVD even if your download didn't
- complete before you got on the plane.</li>
- <li>It should be able to pull a single episode out of the middle of
- a download and give just that to the video tag.</li>
- </ul>
- </li>
-
- <li>Offline Web Mail Client
- <ul>
- <li>Downloads attachments and stores them locally.</li>
- <li>Caches user-selected attachments for later upload.</li>
- <li>Needs to be able to refer to cached attachments and image
- thumbnails for display and upload.</li>
- <li>Should be able to trigger the UA's download manager just as if
- talking to a server.</li>
- <li>Should be able to upload an email with attachments as a
- multipart post, rather than sending a file at a time in an XHR.</li>
- </ul>
- </li>
- </ol>
- </div>
- <div id="examples" class="section">
- <h3><span class="secno">2.2 </span>Examples</h3>
- <pre class="example sh_javascript sh_sourceCode"><span class="sh_comment">// In the DOM or worker context:</span>
-
-<span class="sh_keyword">function</span> <span class="sh_function">useAsyncFS</span><span class="sh_symbol">(</span>fs<span class="sh_symbol">)</span> <span class="sh_cbracket">{</span>
- <span class="sh_comment">// see getAsText example in [</span><cite><a class="bibref" rel="biblioentry" href="#bib-FILE-API-ED"><span class="sh_comment">FILE-API-ED</span></a></cite><span class="sh_comment">].</span>
- fs<span class="sh_symbol">.</span>root<span class="sh_symbol">.</span><span class="sh_function">getFile</span><span class="sh_symbol">(</span><span class="sh_string">"already_there.txt"</span><span class="sh_symbol">,</span> <span class="sh_keyword">null</span><span class="sh_symbol">,</span> <span class="sh_keyword">function</span> <span class="sh_symbol">(</span>f<span class="sh_symbol">)</span> <span class="sh_cbracket">{</span>
- <span class="sh_function">getAsText</span><span class="sh_symbol">(</span>f<span class="sh_symbol">.</span><span class="sh_function">file</span><span class="sh_symbol">());</span>
- <span class="sh_cbracket">}</span><span class="sh_symbol">);</span>
-
- <span class="sh_comment">// But now we can also write to the file; see [</span><cite><a class="bibref" rel="biblioentry" href="#bib-FILE-WRITER-ED"><span class="sh_comment">FILE-WRITER-ED</span></a></cite><span class="sh_comment">].</span>
- fs<span class="sh_symbol">.</span>root<span class="sh_symbol">.</span><span class="sh_function">getFile</span><span class="sh_symbol">(</span><span class="sh_string">"logFile"</span><span class="sh_symbol">,</span> <span class="sh_cbracket">{</span>create<span class="sh_symbol">:</span> <span class="sh_keyword">true</span><span class="sh_cbracket">}</span><span class="sh_symbol">,</span> <span class="sh_keyword">function</span> <span class="sh_symbol">(</span>f<span class="sh_symbol">)</span> <span class="sh_cbracket">{</span>
- f<span class="sh_symbol">.</span><span class="sh_function">createWriter</span><span class="sh_symbol">(</span>writeDataToLogFile<span class="sh_symbol">);</span>
- <span class="sh_cbracket">}</span><span class="sh_symbol">);</span>
-<span class="sh_cbracket">}</span>
-<span class="sh_function">requestFileSystem</span><span class="sh_symbol">(</span>TEMPORARY<span class="sh_symbol">,</span> <span class="sh_number">1024</span> <span class="sh_symbol">*</span> <span class="sh_number">1024</span><span class="sh_symbol">,</span> <span class="sh_keyword">function</span><span class="sh_symbol">(</span>fs<span class="sh_symbol">)</span> <span class="sh_cbracket">{</span>
- <span class="sh_function">useAsyncFS</span><span class="sh_symbol">(</span>fs<span class="sh_symbol">);</span>
-<span class="sh_cbracket">}</span><span class="sh_symbol">);</span>
-
-<span class="sh_comment">// In a worker:</span>
-
-<span class="sh_keyword">var</span> tempFS <span class="sh_symbol">=</span> <span class="sh_function">requestFileSystem</span><span class="sh_symbol">(</span>TEMPORARY<span class="sh_symbol">,</span> <span class="sh_number">1024</span> <span class="sh_symbol">*</span> <span class="sh_number">1024</span><span class="sh_symbol">);</span>
-<span class="sh_keyword">var</span> logFile <span class="sh_symbol">=</span> tempFS<span class="sh_symbol">.</span>root<span class="sh_symbol">.</span><span class="sh_function">getFile</span><span class="sh_symbol">(</span><span class="sh_string">"logFile"</span><span class="sh_symbol">,</span> <span class="sh_cbracket">{</span>create<span class="sh_symbol">:</span> <span class="sh_keyword">true</span><span class="sh_cbracket">}</span><span class="sh_symbol">);</span>
-<span class="sh_keyword">var</span> writer <span class="sh_symbol">=</span> logFile<span class="sh_symbol">.</span><span class="sh_function">createWriter</span><span class="sh_symbol">();</span>
-writer<span class="sh_symbol">.</span><span class="sh_function">seek</span><span class="sh_symbol">(</span>writer<span class="sh_symbol">.</span>length<span class="sh_symbol">);</span>
-<span class="sh_function">writeDataToLogFile</span><span class="sh_symbol">(</span>writer<span class="sh_symbol">);</span></pre>
- </div>
- </div>
- <div id="terminology" class="section">
- <!--OddPage--><h2><span class="secno">3. </span>Terminology</h2>
-
- <p></p>
- The term <dfn id="dfn-throw">throw</dfn> in this specification, as it pertains to
- exceptions, is used as defined in the DOM4 specification [<cite><a class="bibref" rel="biblioentry" href="#bib-DOM4">DOM4</a></cite>].
- <p>
- </p>
- <dfn id="dfn-domerror">DOMError</dfn> is defined in the DOM4 specification [<cite><a class="bibref" rel="biblioentry" href="#bib-DOM4">DOM4</a></cite>].
- <p>
- </p>
- <dfn id="dfn-file">File</dfn> is defined in the File <acronym title="Application Programming
- Interface">API</acronym> specification [<cite><a class="bibref" rel="biblioentry" href="#bib-FILE-API-ED">FILE-API-ED</a></cite>].
- <p>
- </p>
- <dfn id="dfn-filewriter">FileWriter</dfn> and <dfn id="dfn-filewritersync">FileWriterSync</dfn> are defined in the
- FileWriter specification [<cite><a class="bibref" rel="biblioentry" href="#bib-FILE-WRITER-ED">FILE-WRITER-ED</a></cite>].
- <p>
- </p></div>
- <div id="data-persistence-and-accessing-the-api" class="section">
- <!--OddPage--><h2><span class="secno">4. </span>Data Persistence and accessing the <acronym title="Application Programming
- Interface">API</acronym></h2>
- <div class="informative section" id="temporary-vs.-persistent-storage">
- <h3><span class="secno">4.1 </span>Temporary vs. Persistent Storage</h3><p><em>This section is non-normative.</em></p>
- <p>
- An application can request <a href="#dfn-temporary" class="internalDFN">temporary</a> or <a href="#dfn-persistent" class="internalDFN">persistent</a>
- storage space. Temporary storage may be easier to get, at the UA's
- discretion [looser quota restrictions, available without prompting the
- user], but the data stored there may be deleted at the UA's
- convenience, e.g. to deal with a shortage of disk space.
- </p>
- <p>
- Conversely, once <a href="#dfn-persistent" class="internalDFN">persistent</a> storage has been granted, data
- stored there by the application should not be deleted by the UA
- without user intervention. The application may of course delete it at
- will. The UA should require permission from the user before granting
- <a href="#dfn-persistent" class="internalDFN">persistent</a> storage space to the application.
- </p>
- <p>
- This <acronym title="Application Programming
- Interface">API</acronym> specifies the standard origin isolation in a filesystem
- context, along with persistence of data across invocations.
- Applications will likely use <a href="#dfn-temporary" class="internalDFN">temporary</a> storage for caching, and
- if it's still around from a previous session, it is often useful.
- Persistent data, on the other hand, is useless if you can't access it
- again the next time you're invoked. However, even <a href="#dfn-persistent" class="internalDFN">persistent</a>
- data may be deleted manually by the user [either through the UA or via
- direct filesystem operations].
- </p>
- </div>
- <div id="restrictions" class="section">
- <h3><span class="secno">4.2 </span>Restrictions</h3>
- <a href="#idl-def-FileSystem" class="idlType"><code>FileSystem</code></a> and <a href="#idl-def-FileSystemSync" class="idlType"><code>FileSystemSync</code></a> objects returned by
- <code>requestFileSystem</code> <em class="rfc2119" title="must">must</em> have the following properties:
- <ul>
- <li>The filesystems accessible by any origin <em class="rfc2119" title="must">must</em> be disjoint from
- those accessible by any other origin.</li>
- <li>Data stored in a <dfn id="dfn-persistent">persistent</dfn> filesystem <em class="rfc2119" title="should not">should not</em> be
- deleted by the UA, other than in response to a removal <acronym title="Application Programming
- Interface">API</acronym> call,
- without explicit authorization from the user.</li>
- <li>Data stored in a <dfn id="dfn-temporary">temporary</dfn> filesystem <em class="rfc2119" title="may">may</em> be deleted by
- the UA at its discretion, without application or user
- intervention.</li>
- <li>If
- <ol>
- <li> an application in a given origin requests a <a href="#dfn-persistent" class="internalDFN">persistent</a>
- filesystem on multiple occasions;</li>
- <li> each request is granted;</li>
- <li> and data from an earlier request still exists in the first
- filesystem at the time of a subsequent request.</li>
- </ol>
- then the <a href="#idl-def-FileSystem" class="idlType"><code>FileSystem</code></a> or <a href="#idl-def-FileSystemSync" class="idlType"><code>FileSystemSync</code></a> returned from
- the subsequent request <em class="rfc2119" title="must">must</em> refer to the same underlying filesystem
- and root directory as the previous request.</li>
- <li>If
- <ol>
- <li> an application in a given origin requests a <a href="#dfn-temporary" class="internalDFN">temporary</a>
- filesystem on multiple occasions;</li>
- <li> each request is granted;</li>
- <li> and data from an earlier request still exists in the first
- filesystem at the time of a subsequent request.</li>
- </ol>
- then the <a href="#idl-def-FileSystem" class="idlType"><code>FileSystem</code></a> or <a href="#idl-def-FileSystemSync" class="idlType"><code>FileSystemSync</code></a> returned from
- the subsequent request <em class="rfc2119" title="should">should</em> refer to the same underlying
- filesystem and root directory as the previous request.</li>
- </ul>
- </div>
- <div class="informative section" id="security-considerations">
- <h3><span class="secno">4.3 </span>Security Considerations</h3><p><em>This section is non-normative.</em></p>
- <p>
- Because this <acronym title="Application Programming
- Interface">API</acronym> may allow untrusted code to read and write parts of a
- user's hard drive, there are a number of security and privacy issues
- that must be dealt with. Risks to the user include:
- </p><ul>
- <li>Denial of service by filling a local disk or using up IO
- bandwidth. This can be mitigated in part through quota
- limitations.</li>
- <li>Theft or erasure of private data. This is mitigated by limiting
- the scope of access to the local filesystem to a chroot-like,
- origin-specific sandbox.</li>
- <li>Storing malicious executables or illegal data on a user's
- system. This is similar to the risk of any download, and similar
- security precautions apply, but is potentially worse in that:
- <ul>
- <li>It may involve multiple files.</li>
- <li>The files may be in a part of the filesystem that's harder
- for the user to find than the standard downloads directory.</li>
- <li>The malicious writes may happen long enough after granting
- of filesystem access that the user doesn't connect the two
- events.</li>
- </ul>
- This may be mitigated by restricting file creation/rename to
- non-executable extensions, virtualizing paths [leading to
- unguessable or non-executable filenames] and by making sure the
- execute bit is not set on any file created or modified via the <acronym title="Application Programming
- Interface">API</acronym>.
- </li>
- </ul>
- <p></p>
- <p>
- As with any other client-side storage, filesystem access allows for
- cookie-resurrection attacks. UAs will likely wish to present the
- option of clearing it when the user clears any other origin-specific
- storage, blocking access to it when cookies are blocked, etc. This is
- especially important if <a href="#dfn-temporary" class="internalDFN">temporary</a> storage space is permitted by
- default without explicit user permission.
- </p>
- </div>
- <div id="obtaining-access-to-file-system-entry-points" class="section">
- <h3><span class="secno">4.4 </span>Obtaining access to file system entry points</h3>
- <p>
- There are several ways in which a file system entry point can be
- obtained. Not all <a>user agents</a> may in fact implement all of
- them. However, in order to avoid blocking UI actions while waiting on
- filesystem IO, we define only an asynchronous interface for Window,
- and restrict the synchronous <acronym title="Application Programming
- Interface">API</acronym> to the Worker context defined in
- [<cite><a class="bibref" rel="biblioentry" href="#bib-WEBWORKERS-ED">WEBWORKERS-ED</a></cite>].
- </p>
- <div id="using-localfilesystem" class="section">
- <h4><span class="secno">4.4.1 </span>Using <code>LocalFileSystem</code></h4>
- <pre class="idl"><span class="idlImplements"><a>Window</a> implements <a href="#idl-def-LocalFileSystem" class="idlType"><code>LocalFileSystem</code></a>;</span></pre><div class="idlImplementsDesc"><p>All instances of the <code><a>Window</a></code> type are defined to also implement the <a href="#idl-def-LocalFileSystem" class="idlType"><code>LocalFileSystem</code></a> interface.</p></div>
- <pre class="idl"><span class="idlImplements"><a>WorkerGlobalScope</a> implements <a href="#idl-def-LocalFileSystem" class="idlType"><code>LocalFileSystem</code></a>;</span></pre><div class="idlImplementsDesc"><p>All instances of the <code><a>WorkerGlobalScope</a></code> type are defined to also implement the <a href="#idl-def-LocalFileSystem" class="idlType"><code>LocalFileSystem</code></a> interface.</p></div>
- <pre class="idl"><span class="idlInterface" id="idl-def-LocalFileSystem">[<span class="extAttr">Supplemental, NoInterfaceObject</span>]
-interface <span class="idlInterfaceID">LocalFileSystem</span> {
-<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-LocalFileSystem-TEMPORARY">TEMPORARY</a></span> = <span class="idlConstValue">0</span>;</span>
-<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-LocalFileSystem-PERSISTENT">PERSISTENT</a></span> = <span class="idlConstValue">1</span>;</span>
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-LocalFileSystem-requestFileSystem-void-unsigned-short-type-unsigned-long-long-size-FileSystemCallback-successCallback-ErrorCallback-errorCallback">requestFileSystem</a></span> (<span class="idlParam"><span class="idlParamType"><a>unsigned short</a></span> <span class="idlParamName">type</span></span>, <span class="idlParam"><span class="idlParamType"><a>unsigned long long</a></span> <span class="idlParamName">size</span></span>, <span class="idlParam"><span class="idlParamType"><a href="#idl-def-FileSystemCallback" class="idlType"><code>FileSystemCallback</code></a></span> <span class="idlParamName">successCallback</span></span>, <span class="idlParam">optional <span class="idlParamType"><a href="#idl-def-ErrorCallback" class="idlType"><code>ErrorCallback</code></a></span> <span class="idlParamName">errorCallback</span></span>);</span>
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-LocalFileSystem-resolveLocalFileSystemURL-void-DOMString-url-EntryCallback-successCallback-ErrorCallback-errorCallback">resolveLocalFileSystemURL</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">url</span></span>, <span class="idlParam"><span class="idlParamType"><a href="#idl-def-EntryCallback" class="idlType"><code>EntryCallback</code></a></span> <span class="idlParamName">successCallback</span></span>, <span class="idlParam">optional <span class="idlParamType"><a href="#idl-def-ErrorCallback" class="idlType"><code>ErrorCallback</code></a></span> <span class="idlParamName">errorCallback</span></span>);</span>
-};</span>
-</pre><div id="methods" class="section"><h5><span class="secno">4.4.1.1 </span>Methods</h5><dl class="methods"><dt id="widl-LocalFileSystem-requestFileSystem-void-unsigned-short-type-unsigned-long-long-size-FileSystemCallback-successCallback-ErrorCallback-errorCallback"><code>requestFileSystem</code></dt><dd>
- <p>
- Requests a filesystem in which to store application data.
- </p>
- <p>
- If successful, this function <em class="rfc2119" title="must">must</em> give access to an
- origin-private filesystem, as defined above.
- </p>
-
- <table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">type</td><td class="prmType"><code><a>unsigned short</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">
- Whether the filesystem requested should be <a href="#dfn-persistent" class="internalDFN">persistent</a>,
- as defined above. Use one of <code>TEMPORARY</code> or
- <code>PERSISTENT</code>.
- </td></tr><tr><td class="prmName">size</td><td class="prmType"><code><a>unsigned long long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">
- This is an indicator of how much storage space, in bytes, the
- application expects to need.
- </td></tr><tr><td class="prmName">successCallback</td><td class="prmType"><code><a href="#idl-def-FileSystemCallback" class="idlType"><code>FileSystemCallback</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">
- The callback that is called when the <a href="#dfn-user-agent" class="internalDFN">user agent</a> provides
- a filesystem.
- </td></tr><tr><td class="prmName">errorCallback</td><td class="prmType"><code><a href="#idl-def-ErrorCallback" class="idlType"><code>ErrorCallback</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">
- A callback that is called when errors happen, or when the
- request to obtain the filesystem is denied.
- </td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-LocalFileSystem-resolveLocalFileSystemURL-void-DOMString-url-EntryCallback-successCallback-ErrorCallback-errorCallback"><code>resolveLocalFileSystemURL</code></dt><dd>
- <p>
- Allows the user to look up the Entry for a file or directory
- referred to by a local URL.
- </p>
-
- <table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">url</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">
- A URL referring to a local file in a filesystem accessable via
- this <acronym title="Application Programming
- Interface">API</acronym>.
- </td></tr><tr><td class="prmName">successCallback</td><td class="prmType"><code><a href="#idl-def-EntryCallback" class="idlType"><code>EntryCallback</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">
- A callback that is called to report the Entry to which the
- supplied URL refers.
- </td></tr><tr><td class="prmName">errorCallback</td><td class="prmType"><code><a href="#idl-def-ErrorCallback" class="idlType"><code>ErrorCallback</code></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">
- A callback that is called when errors happen, or when the
- request to obtain the Entry is denied.
- </td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></div><div id="constants" class="section"><h5><span class="secno">4.4.1.2 </span>Constants</h5><dl class="constants"><dt id="widl-LocalFileSystem-PERSISTENT"><code>PERSISTENT</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
- Used for storage that should not be removed by the <a href="#dfn-user-agent" class="internalDFN">user
- agent</a> without application or user permission.
- </dd><dt id="widl-LocalFileSystem-TEMPORARY"><code>TEMPORARY</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
- Used for storage with no guarantee of persistence.
- </dd></dl></div>
- </div>
- <div id="using-localfilesystemsync" class="section">
- <h4><span class="secno">4.4.2 </span>Using <code>LocalFileSystemSync</code></h4>
- <pre class="idl"><span class="idlImplements"><a>WorkerGlobalScope</a> implements <a href="#idl-def-LocalFileSystemSync" class="idlType"><code>LocalFileSystemSync</code></a>;</span></pre><div class="idlImplementsDesc"><p>All instances of the <code><a>WorkerGlobalScope</a></code> type are defined to also implement the <a href="#idl-def-LocalFileSystemSync" class="idlType"><code>LocalFileSystemSync</code></a> interface.</p></div>
- <pre class="idl"><span class="idlInterface" id="idl-def-LocalFileSystemSync">[<span class="extAttr">Supplemental, NoInterfaceObject</span>]
-interface <span class="idlInterfaceID">LocalFileSystemSync</span> {
-<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-LocalFileSystemSync-TEMPORARY">TEMPORARY</a></span> = <span class="idlConstValue">0</span>;</span>
-<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-LocalFileSystemSync-PERSISTENT">PERSISTENT</a></span> = <span class="idlConstValue">1</span>;</span>
-<span class="idlMethod"> <span class="idlMethType"><a href="#idl-def-FileSystemSync" class="idlType"><code>FileSystemSync</code></a></span> <span class="idlMethName"><a href="#widl-LocalFileSystemSync-requestFileSystemSync-FileSystemSync-unsigned-short-type-unsigned-long-long-size">requestFileSystemSync</a></span> (<span class="idlParam"><span class="idlParamType"><a>unsigned short</a></span> <span class="idlParamName">type</span></span>, <span class="idlParam"><span class="idlParamType"><a>unsigned long long</a></span> <span class="idlParamName">size</span></span>);</span>
-<span class="idlMethod"> <span class="idlMethType"><a href="#idl-def-EntrySync" class="idlType"><code>EntrySync</code></a></span> <span class="idlMethName"><a href="#widl-LocalFileSystemSync-resolveLocalFileSystemSyncURL-EntrySync-DOMString-url">resolveLocalFileSystemSyncURL</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">url</span></span>);</span>
-};</span>
-</pre><div id="methods-1" class="section"><h5><span class="secno">4.4.2.1 </span>Methods</h5><dl class="methods"><dt id="widl-LocalFileSystemSync-requestFileSystemSync-FileSystemSync-unsigned-short-type-unsigned-long-long-size"><code>requestFileSystemSync</code></dt><dd>
- <p>
- Requests a filesystem in which to store application data.
- </p>
- <p>
- If successful, this function <em class="rfc2119" title="must">must</em> give access to an
- origin-private filesystem, as defined above.
- </p>
-
- <table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">type</td><td class="prmType"><code><a>unsigned short</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">
- Whether the filesystem requested should be <a href="#dfn-persistent" class="internalDFN">persistent</a>,
- as defined above. Use one of <code>TEMPORARY</code> or
- <code>PERSISTENT</code>.
- </td></tr><tr><td class="prmName">size</td><td class="prmType"><code><a>unsigned long long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">
- This is an indicator of how much storage space, in bytes, the
- application expects to need.
- </td></tr></table><div><em>Return type: </em><code><a href="#idl-def-FileSystemSync" class="idlType"><code>FileSystemSync</code></a></code></div></dd><dt id="widl-LocalFileSystemSync-resolveLocalFileSystemSyncURL-EntrySync-DOMString-url"><code>resolveLocalFileSystemSyncURL</code></dt><dd>
- <p>
- Allows the user to look up the Entry for a file or directory
- referred to by a local URL.
- </p>
-
- <table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">url</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc">
- A URL referring to a local file in a filesystem accessable via
- this <acronym title="Application Programming
- Interface">API</acronym>.
- </td></tr></table><div><em>Return type: </em><code><a href="#idl-def-EntrySync" class="idlType"><code>EntrySync</code></a></code></div></dd></dl></div><div id="constants-1" class="section"><h5><span class="secno">4.4.2.2 </span>Constants</h5><dl class="constants"><dt id="widl-LocalFileSystemSync-PERSISTENT"><code>PERSISTENT</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
- Used for storage that should not be removed by the <a href="#dfn-user-agent" class="internalDFN">user
- agent</a> without application or user permission.
- </dd><dt id="widl-LocalFileSystemSync-TEMPORARY"><code>TEMPORARY</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
- Used for storage with no guarantee of persistence.
- </dd></dl></div>
- </div>
- </div>
- </div>
-
- <div id="shared-data-types" class="section">
- <!--OddPage--><h2><span class="secno">5. </span>Shared data types</h2>
- <div id="the-metadata-interface" class="section">
- <h3><span class="secno">5.1 </span>The <code>Metadata</code> interface</h3>
- <p>
- This interface supplies information about the state of a file or
- directory.
- </p>
- <pre class="idl"><span class="idlInterface" id="idl-def-Metadata">interface <span class="idlInterfaceID">Metadata</span> {
-<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>Date</a></span> <span class="idlAttrName"><a href="#widl-Metadata-modificationTime">modificationTime</a></span>;</span>
-<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long long</a></span> <span class="idlAttrName"><a href="#widl-Metadata-size">size</a></span>;</span>
[1277 lines skipped]
Received on Saturday, 19 April 2014 11:50:15 UTC