W3C home > Mailing lists > Public > public-dap-commits@w3.org > April 2014

CVS 2009/dap/file-system/pub/FileSystem

From: CVS User abarsto <cvsmail@w3.org>
Date: Sat, 19 Apr 2014 11:50:12 +0000
Message-Id: <E1WbTme-00088Z-H4@roscoe.w3.org>
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 (&gt;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

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 20:52:38 UTC