ghopp
/
server_playground
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Another abandoned server code base... this is kind of an ancestor of taskrambler.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
97 Commits
1 Branch
0 Tags
51 MiB
 
 
 
 
 
 
Tree: 2e46b5c249
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '2e46b5c249'
${ noResults }
server_playground/doc/www.w3.org/TR/2011/WD-file-writer-api-20110419/index.html

990 lines
85 KiB
Raw Blame History

<!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: Writer</title>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<link href="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 API: Writer</h1><h2 id="w3c-working-draft-19-april-2011">W3C Working Draft 19 April 2011</h2><dl><dt>This version:</dt><dd><a href="http://www.w3.org/TR/2011/WD-file-writer-api-20110419/">http://www.w3.org/TR/2011/WD-file-writer-api-20110419/</a></dd><dt>Latest published version:</dt><dd><a href="http://www.w3.org/TR/file-writer-api/">http://www.w3.org/TR/file-writer-api/</a></dd><dt>Latest editor's draft:</dt><dd><a href="http://dev.w3.org/2009/dap/file-system/file-writer.html">http://dev.w3.org/2009/dap/file-system/file-writer.html</a></dd>
<dt>Previous versions:</dt>
<dd><a href="http://www.w3.org/TR/2010/WD-file-writer-api-20101026/">http://www.w3.org/TR/2010/WD-file-writer-api-20101026/</a></dd>
<dd><a href="http://www.w3.org/TR/2010/WD-file-writer-api-20100406/">http://www.w3.org/TR/2010/WD-file-writer-api-20100406/</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>
&copy; 2011 <a href="http://www.w3.org/"><acronym title="World Wide Web
Consortium">W3C</acronym></a><sup>&reg;</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. W3C <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> for writing to files from web applications.
This API is designed to be used in conjunction with, and depends on
definitions in, other APIs and elements on the web platform. Most
relevant among these are [<cite><a class="bibref" rel="biblioentry" href="#bib-FILE-API">FILE-API</a></cite>] and [<cite><a class="bibref" rel="biblioentry" href="#bib-WEBWORKERS">WEBWORKERS</a></cite>].
</p>
<p>
This API includes:
</p><ul>
<li> A <a href="#idl-def-BlobBuilder" class="idlType"><code>BlobBuilder</code></a> interface, which enables one to build a
<code>Blob</code> from a String.
</li><li> A <a href="#idl-def-FileSaver" class="idlType"><code>FileSaver</code></a> interface, which provides methods to write a
<code>Blob</code> to a file, and an event model to monitor the
progress of those writes.</li>
<li> A <a href="#idl-def-FileWriter" class="idlType"><code>FileWriter</code></a> interface, which expands on FileSaver to add
a richer set of output options.</li>
<li> A <a href="#idl-def-FileWriterSync" class="idlType"><code>FileWriterSync</code></a> interface, which provides methods to
write and modify files synchronously in a Web Worker.</li>
</ul>
<p></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 W3C publications and the latest revision of this technical report can be found in the <a href="http://www.w3.org/TR/">W3C technical reports index</a> at http://www.w3.org/TR/.</em></p>
<p>This document represents the early consensus of the group on
the scope and features of the proposed File API: Writer. Issues and
editors notes in the document highlight some of
the points on which the group is still working and would
particularly like to get feedback.</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 W3C 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/Archives/Public/public-webapps/">archives</a>). All feedback is welcome.</p><p>Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.</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 W3C Patent Policy</a>. W3C 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/Consortium/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 W3C 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="#terminology-and-algorithms" class="tocxref"><span class="secno">2. </span>Terminology and Algorithms</a></li><li class="tocline"><a href="#introduction" class="tocxref"><span class="secno">3. </span>Introduction</a><ul class="toc"><li class="tocline"><a href="#examples" class="tocxref"><span class="secno">3.1 </span>Examples</a></li></ul></li><li class="tocline"><a href="#the-blobbuilder-interface" class="tocxref"><span class="secno">4. </span>The <code>BlobBuilder</code> interface</a><ul class="toc"><li class="tocline"><a href="#methods" class="tocxref"><span class="secno">4.1 </span>Methods</a></li><li class="tocline"><a href="#constructor" class="tocxref"><span class="secno">4.2 </span>Constructor</a></li></ul></li><li class="tocline"><a href="#the-filesaver-interface" class="tocxref"><span class="secno">5. </span>The <span class="idlType formerLink idlType"><code>FileSaver</code></span> interface</a><ul class="toc"><li class="tocline"><a href="#attributes" class="tocxref"><span class="secno">5.1 </span>Attributes</a></li><li class="tocline"><a href="#methods-1" class="tocxref"><span class="secno">5.2 </span>Methods</a></li><li class="tocline"><a href="#constants" class="tocxref"><span class="secno">5.3 </span>Constants</a></li><li class="tocline"><a href="#the-filesaver-constructor" class="tocxref"><span class="secno">5.4 </span>The FileSaver Constructor</a></li><li class="tocline"><a href="#the-filesaver-task-source" class="tocxref"><span class="secno">5.5 </span>The FileSaver Task Source</a></li><li class="tocline"><a href="#event-handler-attributes" class="tocxref"><span class="secno">5.6 </span>Event Handler Attributes</a></li></ul></li><li class="tocline"><a href="#the-filesaversync-interface" class="tocxref"><span class="secno">6. </span>The <code>FileSaverSync</code> interface</a></li><li class="tocline"><a href="#the-filewriter-interface" class="tocxref"><span class="secno">7. </span>The <span class="idlType formerLink idlType"><code>FileWriter</code></span> interface</a><ul class="toc"><li class="tocline"><a href="#attributes-1" class="tocxref"><span class="secno">7.1 </span>Attributes</a></li><li class="tocline"><a href="#methods-2" class="tocxref"><span class="secno">7.2 </span>Methods</a></li></ul></li><li class="tocline"><a href="#the-filewritersync-interface" class="tocxref"><span class="secno">8. </span>The <code>FileWriterSync</code> interface</a><ul class="toc"><li class="tocline"><a href="#attributes-2" class="tocxref"><span class="secno">8.1 </span>Attributes</a></li><li class="tocline"><a href="#methods-3" class="tocxref"><span class="secno">8.2 </span>Methods</a></li></ul></li><li class="tocline"><a href="#errors-and-exceptions" class="tocxref"><span class="secno">9. </span>Errors and Exceptions</a><ul class="toc"><li class="tocline"><a href="#the-fileerror-interface" class="tocxref"><span class="secno">9.1 </span>The FileError Interface</a><ul class="toc"><li class="tocline"><a href="#attributes-3" class="tocxref"><span class="secno">9.1.1 </span>Attributes</a></li><li class="tocline"><a href="#constants-1" class="tocxref"><span class="secno">9.1.2 </span>Constants</a></li></ul></li><li class="tocline"><a href="#the-fileexception-exception" class="tocxref"><span class="secno">9.2 </span>The FileException exception</a><ul class="toc"><li class="tocline"><a href="#fields" class="tocxref"><span class="secno">9.2.1 </span>Fields</a></li><li class="tocline"><a href="#constants-2" class="tocxref"><span class="secno">9.2.2 </span>Constants</a></li></ul></li><li class="tocline"><a href="#error-code-descriptions" class="tocxref"><span class="secno">9.3 </span><span>Error Code Descriptions</span></a></li></ul></li><li class="tocline"><a href="#security-considerations" class="tocxref"><span class="secno">10. </span>Security Considerations</a><ul class="toc"><li class="tocline"><a href="#basic-security-model" class="tocxref"><span class="secno">10.1 </span>Basic Security Model</a></li><li class="tocline"><a href="#write-only-files" class="tocxref"><span class="secno">10.2 </span>Write-Only Files</a></li><li class="tocline"><a href="#quotas" class="tocxref"><span class="secno">10.3 </span>Quotas</a></li><li class="tocline"><a href="#other-standard-techniques" class="tocxref"><span class="secno">10.4 </span>Other Standard Techniques</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 href="#dfn-user-agents" class="internalDFN">user agents</a> that implement the interfaces that it
contains.
</p>
<p>
Everything in this specification is normative except for examples and
sections marked as being informative.
</p>
<p>
The keywords <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="shall">shall</em>, <em class="rfc2119" title="shall not">shall not</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 document are to be
interpreted as described in <a href="http://www.ietf.org/rfc/rfc2119">Key words for use in RFCs to
Indicate Requirement Levels</a> [<cite><a class="bibref" rel="biblioentry" href="#bib-RFC2119">RFC2119</a></cite>].
</p>
<p>
The following conformance classes are defined by this specification:
</p><dl>
<dt><dfn id="dfn-conforming-implementation">conforming implementation</dfn></dt>
<dd>
<p>
A <dfn id="dfn-user-agent">user agent</dfn> is considered to be a conforming
implementation if it satisfies all of the must-, required- and
shall-level criteria in this specification that apply to
implementations.
</p>
</dd>
</dl>
<p></p>
</div>
<div id="terminology-and-algorithms" class="section">
<!--OddPage--><h2><span class="secno">2. </span>Terminology and Algorithms</h2>
<p>
The terms and algorithms <dfn id="dfn-event-handler-attributes">event handler attributes</dfn>, <dfn id="dfn-event-handler-event-types">event
handler event types</dfn>, <dfn id="dfn-function">Function</dfn>, <dfn id="dfn-task">task</dfn>,
<dfn id="dfn-task-source">task source</dfn>, and <dfn id="dfn-queue-a-task">queue a task</dfn> are defined by the
HTML 5 specification [<cite><a class="bibref" rel="biblioentry" href="#bib-HTML5">HTML5</a></cite>].
</p>
<p>
The term <dfn id="dfn-blob">Blob</dfn> is defined by the File API specification
[<cite><a class="bibref" rel="biblioentry" href="#bib-FILE-API">FILE-API</a></cite>].
</p>
<p>
The term <dfn id="dfn-arraybuffer">ArrayBuffer</dfn> is defined by the Typed Arrays
specification [<cite><a class="bibref" rel="biblioentry" href="#bib-TYPED-ARRAYS">TYPED-ARRAYS</a></cite>].
</p>
<p>
This specification includes algorithms (steps) as part of the definition
of methods. Conforming implementations (referred to as <dfn id="dfn-user-agents">user
agents</dfn> from here on) <em class="rfc2119" title="may">may</em> use other algorithms in the
implementation of these methods, provided the end result is the same.
</p>
</div>
<div class="informative section" id="introduction">
<!--OddPage--><h2><span class="secno">3. </span>Introduction</h2><p><em>This section is non-normative.</em></p>
<p>
Web applications are currently fairly limited in how they can write to
files. One can present a link for download, but creating and writing
files of arbitrary type, or modifying downloaded files on their way to
the disk, is difficult or impossible. This specification defines an
API through which <a href="#dfn-user-agents" class="internalDFN">user agents</a> can permit applications to write
generated or downloaded files.
</p>
<p>
The [<cite><a class="bibref" rel="biblioentry" href="#bib-FILE-API">FILE-API</a></cite>] defined interfaces for reading files, manipulation of
<a>Blobs</a> of data, and errors raised by file accesses. This
specification extends that work with a way to construct <a>Blobs</a> and
with synchronous and asynchronous file-writing interfaces. As with
reading, writing files on the main thread should happen asynchronously
to avoid blocking UI actions. Long-running writes provide status
information through delivery of progress events.
</p>
<div id="examples" class="section">
<h3><span class="secno">3.1 </span>Examples</h3>
<p>
Here is a simple function that writes a text file, given a FileWriter:
</p>
<pre class="example sh_javascript sh_sourceCode"><span class="sh_keyword">function</span> <span class="sh_function">writeFile</span><span class="sh_symbol">(</span>writer<span class="sh_symbol">)</span> <span class="sh_cbracket">{</span>
<span class="sh_keyword">function</span> <span class="sh_function">done</span><span class="sh_symbol">(</span>evt<span class="sh_symbol">)</span> <span class="sh_cbracket">{</span>
<span class="sh_function">alert</span><span class="sh_symbol">(</span><span class="sh_string">"Write completed."</span><span class="sh_symbol">);</span>
<span class="sh_cbracket">}</span>
<span class="sh_keyword">function</span> <span class="sh_function">error</span><span class="sh_symbol">(</span>evt<span class="sh_symbol">)</span> <span class="sh_cbracket">{</span>
<span class="sh_function">alert</span><span class="sh_symbol">(</span><span class="sh_string">"Write failed:"</span> <span class="sh_symbol">+</span> evt<span class="sh_symbol">);</span>
<span class="sh_cbracket">}</span>
<span class="sh_keyword">var</span> bb <span class="sh_symbol">=</span> <span class="sh_keyword">new</span> <span class="sh_function">BlobBuilder</span><span class="sh_symbol">();</span>
bb<span class="sh_symbol">.</span><span class="sh_function">append</span><span class="sh_symbol">(</span><span class="sh_string">"Lorem ipsum"</span><span class="sh_symbol">);</span>
writer<span class="sh_symbol">.</span>onwrite <span class="sh_symbol">=</span> done<span class="sh_symbol">;</span>
writer<span class="sh_symbol">.</span>onerror <span class="sh_symbol">=</span> error<span class="sh_symbol">;</span>
writer<span class="sh_symbol">.</span><span class="sh_function">write</span><span class="sh_symbol">(</span>bb<span class="sh_symbol">.</span><span class="sh_function">getBlob</span><span class="sh_symbol">());</span>
<span class="sh_cbracket">}</span></pre>
<p>
Here's an example of obtaining and using a <a href="#idl-def-FileSaver" class="idlType"><code>FileSaver</code></a>:
</p>
<pre class="example sh_javascript sh_sourceCode"><span class="sh_keyword">var</span> bb <span class="sh_symbol">=</span> <span class="sh_keyword">new</span> <span class="sh_function">BlobBuilder</span><span class="sh_symbol">();</span>
bb<span class="sh_symbol">.</span><span class="sh_function">append</span><span class="sh_symbol">(</span><span class="sh_string">"Lorem ipsum"</span><span class="sh_symbol">);</span>
<span class="sh_keyword">var</span> fileSaver <span class="sh_symbol">=</span> window<span class="sh_symbol">.</span><span class="sh_function">saveAs</span><span class="sh_symbol">(</span>bb<span class="sh_symbol">.</span><span class="sh_function">getBlob</span><span class="sh_symbol">(),</span> <span class="sh_string">"test_file"</span><span class="sh_symbol">);</span>
fileSaver<span class="sh_symbol">.</span>onwriteend <span class="sh_symbol">=</span> myOnWriteEnd<span class="sh_symbol">;</span></pre>
<p></p>
</div>
</div>
<div id="the-blobbuilder-interface" class="section">
<!--OddPage--><h2><span class="secno">4. </span>The <code>BlobBuilder</code> interface</h2>
<p>
BlobBuilder description
</p>
<pre class="idl"><span class="idlInterface" id="idl-def-BlobBuilder">[<span class="extAttr">Constructor</span>]
interface <span class="idlInterfaceID">BlobBuilder</span> {
<span class="idlMethod"> <span class="idlMethType"><a>Blob</a></span> <span class="idlMethName"><a href="#widl-BlobBuilder-getBlob">getBlob</a></span> (<span class="idlParam">optional <span class="idlParamType"><a>in DOMString</a></span> <span class="idlParamName">contentType</span></span>);</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-BlobBuilder-append">append</a></span> (<span class="idlParam"><span class="idlParamType"><a>in DOMString</a></span> <span class="idlParamName">text</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>in DOMString</a></span> <span class="idlParamName">endings</span></span>) raises (<span class="idlRaises"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></span>);</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-BlobBuilder-append">append</a></span> (<span class="idlParam"><span class="idlParamType"><a>in Blob</a></span> <span class="idlParamName">data</span></span>);</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-BlobBuilder-append">append</a></span> (<span class="idlParam"><span class="idlParamType"><a>in ArrayBuffer</a></span> <span class="idlParamName">data</span></span>);</span>
};</span>
</pre><div id="methods" class="section"><h3><span class="secno">4.1 </span>Methods</h3><dl class="methods"><dt id="widl-BlobBuilder-append"><code>append</code></dt><dd>
<p>
Appends the supplied text to the current contents of the
<code>BlobBuilder</code>, writing it as UTF-8, converting newlines as
specified in <code>endings</code>.
</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">text</td><td class="prmType"><code><a>in DOMString</a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc">
The data to write.
</td></tr><tr><td class="prmName">endings</td><td class="prmType"><code><a>in DOMString</a></code></td><td class="prmNullFalse">?</td><td class="prmOptTrue">?</td><td class="prmDesc">
<div class="issue">Can we do without endings? Any choice other
than "transparent" can be implemented by the app author, and
most file formats don't care about line endings. "Transparent"
would be handy for sharing certain types of text files with apps
outside the browser [e.g. Makefiles on a system where make is
expecting \n will have issues if they're written with \r\n]. Is
it worth it? Can this be worked around if we don't supply
it?</div>
<p>
This parameter specifies how strings containing <code>\n</code>
are to be written out. If the user does not provide the
<code>endings</code> parameter, <a href="#dfn-user-agents" class="internalDFN">user agents</a><a> <em class="rfc2119" title="must">must</em> act as if
the user had specified a value of 'transparent'. If the user
provides the <code>endings</code> parameter, </a><a href="#dfn-user-agents" class="internalDFN">user agents</a><a>
<em class="rfc2119" title="must">must</em> convert newlines as specified below. The possible values
are:
</a></p>
<table class="simple">
<tbody><tr><th>Value</th><th>Description</th></tr>
<tr>
<td>"transparent"</td>
<td>
Code points from the string <em class="rfc2119" title="must">must</em> remain unchanged.
</td>
</tr>
<tr>
<td>"native"</td>
<td>
Newlines <em class="rfc2119" title="must">must</em> be transformed to the default line-ending
representation of the underlying host filesystem. For
example, if the underlying filesystem is FAT32, newlines
would be transformed into <code>\r\n</code> pairs as the
text was appended to the state of the BlobBuilder.
</td>
</tr>
</tbody></table>
</td></tr></table>
<table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></td><td class="excDesc"></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt><code>append</code></dt><dd>
<p>
Appends the supplied <a href="#dfn-blob" class="internalDFN">Blob</a> to the current contents of the
<code>BlobBuilder</code>.
</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">data</td><td class="prmType"><code><a>in Blob</a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc">
The data to append.
</td></tr></table><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a>void</a></code></div></dd><dt><code>append</code></dt><dd>
<p>
Appends the supplied <a href="#dfn-arraybuffer" class="internalDFN">ArrayBuffer</a> to the current contents of the
<code>BlobBuilder</code>.
</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">data</td><td class="prmType"><code><a>in ArrayBuffer</a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc">
The data to append.
</td></tr></table><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a>void</a></code></div></dd>
<dt id="widl-BlobBuilder-getBlob"><code>getBlob</code></dt><dd>
<p>
Returns the current contents of the <code>BlobBuilder</code> as a
<code>Blob</code>.
</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">contentType</td><td class="prmType"><code><a>in DOMString</a></code></td><td class="prmNullFalse">?</td><td class="prmOptTrue">?</td><td class="prmDesc">
Sets the content type of the blob produced.
</td></tr></table><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a>Blob</a></code></div></dd></dl></div>
<div id="constructor" class="section">
<h3><span class="secno">4.2 </span>Constructor</h3>
<p>
When the <a href="#idl-def-BlobBuilder" class="idlType"><code>BlobBuilder</code></a> constructor is invoked, <a href="#dfn-user-agents" class="internalDFN">user agents</a>
<em class="rfc2119" title="must">must</em> return a new <a href="#idl-def-BlobBuilder" class="idlType"><code>BlobBuilder</code></a> object.
</p>
<p>
This constructor <em class="rfc2119" title="must">must</em> be visible when the script's global object is
either a Window object or an object implementing the WorkerUtils
interface.
</p>
</div>
</div>
<div id="the-filesaver-interface" class="section">
<!--OddPage--><h2><span class="secno">5. </span>The <a href="#idl-def-FileSaver" class="idlType"><code>FileSaver</code></a> interface</h2>
<p>
This interface provides methods to monitor the asynchronous writing of
blobs to disk using progress events [<cite><a class="bibref" rel="biblioentry" href="#bib-PROGRESS-EVENTS">PROGRESS-EVENTS</a></cite>] and <a href="#dfn-event-handler-attributes" class="internalDFN">event
handler attributes</a>.
</p>
<p>
This interface is specified to be used within the context of the global
object (Window [<cite><a class="bibref" rel="biblioentry" href="#bib-HTML5">HTML5</a></cite>]) and within Web Workers (WorkerUtils
[<cite><a class="bibref" rel="biblioentry" href="#bib-WEBWORKERS">WEBWORKERS</a></cite>]).
</p>
<pre class="idl"><span class="idlInterface" id="idl-def-FileSaver">[<span class="extAttr">Constructor(in Blob data)</span>]
interface <span class="idlInterfaceID">FileSaver</span> {
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-FileSaver-abort">abort</a></span> () raises (<span class="idlRaises"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></span>);</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileSaver-INIT">INIT</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-FileSaver-WRITING">WRITING</a></span> = <span class="idlConstValue">1</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileSaver-DONE">DONE</a></span> = <span class="idlConstValue">2</span>;</span>
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned short</a></span> <span class="idlAttrName"><a href="#widl-FileSaver-readyState">readyState</a></span>;</span>
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a href="#idl-def-FileError" class="idlType"><code>FileError</code></a></span> <span class="idlAttrName"><a href="#widl-FileSaver-error">error</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Function</a></span> <span class="idlAttrName"><a href="#widl-FileSaver-onwritestart">onwritestart</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Function</a></span> <span class="idlAttrName"><a href="#widl-FileSaver-onprogress">onprogress</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Function</a></span> <span class="idlAttrName"><a href="#widl-FileSaver-onwrite">onwrite</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Function</a></span> <span class="idlAttrName"><a href="#widl-FileSaver-onabort">onabort</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Function</a></span> <span class="idlAttrName"><a href="#widl-FileSaver-onerror">onerror</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Function</a></span> <span class="idlAttrName"><a href="#widl-FileSaver-onwriteend">onwriteend</a></span>;</span>
};</span>
</pre><div id="attributes" class="section"><h3><span class="secno">5.1 </span>Attributes</h3><dl class="attributes"><dt id="widl-FileSaver-error"><code>error</code> of type <span class="idlAttrType"><a href="#idl-def-FileError" class="idlType"><code>FileError</code></a></span>, readonly</dt><dd>
<p>
The last error that occurred on the <code>FileSaver</code>.
</p>
<div><em>No exceptions.</em></div></dd><dt id="widl-FileSaver-onabort"><code>onabort</code> of type <span class="idlAttrType"><a>Function</a></span></dt><dd>
<p>
Handler for abort events.
</p>
<div><em>No exceptions.</em></div></dd><dt id="widl-FileSaver-onerror"><code>onerror</code> of type <span class="idlAttrType"><a>Function</a></span></dt><dd>
<p>
Handler for error events.
</p>
<div><em>No exceptions.</em></div></dd><dt id="widl-FileSaver-onprogress"><code>onprogress</code> of type <span class="idlAttrType"><a>Function</a></span></dt><dd>
<p>
Handler for progress events.
</p>
<div><em>No exceptions.</em></div></dd><dt id="widl-FileSaver-onwrite"><code>onwrite</code> of type <span class="idlAttrType"><a>Function</a></span></dt><dd>
<p>
Handler for write events.
</p>
<div><em>No exceptions.</em></div></dd><dt id="widl-FileSaver-onwriteend"><code>onwriteend</code> of type <span class="idlAttrType"><a>Function</a></span></dt><dd>
<p>
Handler for writeend events.
</p>
<div><em>No exceptions.</em></div></dd><dt id="widl-FileSaver-onwritestart"><code>onwritestart</code> of type <span class="idlAttrType"><a>Function</a></span></dt><dd>
<p>
Handler for writestart events.
</p>
<div><em>No exceptions.</em></div></dd><dt id="widl-FileSaver-readyState"><code>readyState</code> of type <span class="idlAttrType"><a>unsigned short</a></span>, readonly</dt><dd>
<p>
The FileSaver object can be in one of 3 states. The
<code>readyState</code> attribute, on getting, <em class="rfc2119" title="must">must</em> return the
current state, which <em class="rfc2119" title="must">must</em> be one of the following values:
</p><ul>
<li><a>INIT</a></li>
<li><a>WRITING</a></li>
<li><a>DONE</a></li>
</ul>
<p></p>
<div><em>No exceptions.</em></div></dd></dl></div><div id="methods-1" class="section"><h3><span class="secno">5.2 </span>Methods</h3><dl class="methods"><dt id="widl-FileSaver-abort"><code>abort</code></dt><dd>
<p>
When the <code>abort</code> method is called, <a href="#dfn-user-agents" class="internalDFN">user agents</a>
<em class="rfc2119" title="must">must</em> run the steps below:
</p><ol>
<li>If <code>readyState</code> is <code>DONE</code> or
<code>INIT</code>, throw a <code>FileException</code> with error
code <code>INVALID_STATE_ERR</code> and terminate this overall
series of steps.</li>
<li>Terminate any steps having to do with writing a file.</li>
<li>Queue a task that will:
<ol>
<li>Set the <code>error</code> attribute to a FileError object
with the code <a href="#dfn-abort_err" class="internalDFN">ABORT_ERR</a>.</li>
<li>Set <code>readyState</code> to <code>DONE</code>.</li>
<li>Dispatch a progress event called error.</li>
<li>Dispatch a progress event called abort</li>
<li>Dispatch a progress event called writeend</li>
</ol></li>
<li>Stop dispatching any further progress events.</li>
<li>Terminate this overall set of steps.</li>
</ol>
<p></p>
<div><em>No parameters.</em></div><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>INVALID_STATE_ERR</code></td><td class="excCodeDesc">A user called <code>abort</code> while <code>readyState</code>
was <code>DONE</code>.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></div><div id="constants" class="section"><h3><span class="secno">5.3 </span>Constants</h3><dl class="constants"><dt id="widl-FileSaver-DONE"><code>DONE</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
The entire Blob has been written to the file, a file error occurred
during the write, or the write was aborted using <a>abort()</a>. The
FileSaver is no longer writing the blob.
</dd><dt id="widl-FileSaver-INIT"><code>INIT</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
The object has been constructed, but there is no pending write.
</dd><dt id="widl-FileSaver-WRITING"><code>WRITING</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
The blob is being written.
</dd></dl></div>
<div id="the-filesaver-constructor" class="section">
<h3><span class="secno">5.4 </span>The FileSaver Constructor</h3>
<p>
The <code>FileSaver(data)</code> constructor takes one argument: the
Blob of data to be saved to a file.
</p>
<p>
When the <a href="#idl-def-FileSaver" class="idlType"><code>FileSaver</code></a> constructor is called, the <a href="#dfn-user-agent" class="internalDFN">user agent</a>
<em class="rfc2119" title="must">must</em> return a new <a href="#idl-def-FileSaver" class="idlType"><code>FileSaver</code></a> object with <code>readyState</code>
set to <code>INIT</code>.
</p>
<p>
This constructor <em class="rfc2119" title="must">must</em> be visible when the script's global object is
either a Window object or an object implementing the WorkerUtils
interface.
</p>
</div>
<div id="the-filesaver-task-source" class="section">
<h3><span class="secno">5.5 </span>The FileSaver Task Source</h3>
<!--
TODO: Figure out how to do the references properly. Maybe just use raw
links to a reference section, as in the File API spec.
-->
<p>
The <a href="#idl-def-FileSaver" class="idlType"><code>FileSaver</code></a> interface enables asynchronous writes on
individual files by dispatching events to event handler methods. Unless
stated otherwise, the <a href="#dfn-task-source" class="internalDFN">task source</a> that is used in this
specification is the <a href="#idl-def-FileSaver" class="idlType"><code>FileSaver</code></a>. This <a href="#dfn-task-source" class="internalDFN">task source</a> is
used for any event <a href="#dfn-task" class="internalDFN">task</a> that is asynchronously dispatched, or for
event tasks that are queued for dispatching.
</p>
<p>
After its constructor has returned, a new FileSaver <em class="rfc2119" title="must">must</em> asynchronously
execute the following steps.
</p>
<ol>
<li>Set <code>readyState</code> to <code>WRITING</code>.</li>
<li>If an error occurs during file write, proceed to the error steps
below.
<ol>
<li>Queue a task that will:
<ol>
<li>Set the <code>error</code> attribute; on getting the
<code>error</code> attribute <em class="rfc2119" title="must">must</em> be a
<code>FileError</code> object with a valid error code that
indicates the kind of file error that has occurred.</li>
<li>Set readyState to <code>DONE</code>.</li>
<li>Dispatch a progress event called
<code>error</code>.</li>
<li>Dispatch a progress event called
<code>writeend</code>.</li>
</ol></li>
<li>Terminate this overall set of steps.</li>
</ol>
</li>
<li>Queue a task to dispatch a progress event called
<code>writestart</code>.</li>
<li>Make progress notifications.</li>
<li>When the data has been fully written, queue a task that will:
<ol>
<li>Set readyState to <code>DONE</code>.</li>
<li>Dispatch a progress event called <code>write</code></li>
<li>Dispatch a progress event called <code>writeend</code></li>
</ol>
</li>
<li>Terminate this overall set of steps.</li>
</ol>
</div>
<div id="event-handler-attributes" class="section">
<h3><span class="secno">5.6 </span>Event Handler Attributes</h3>
<p>
The following are the <a href="#dfn-event-handler-attributes" class="internalDFN">event handler attributes</a> (and their
corresponding <a href="#dfn-event-handler-event-types" class="internalDFN">event handler event types</a>) that user agents <em class="rfc2119" title="must">must</em>
support on <code><a href="#idl-def-FileSaver" class="idlType"><code>FileSaver</code></a></code> as DOM attributes:
</p>
<table class="simple">
<thead>
<tr>
<th><a>event handler attribute</a></th>
<th><a>event handler event type</a></th>
</tr>
</thead>
<tbody>
<tr>
<td><dfn id="dfn-onwritestart"><code>onwritestart</code></dfn></td>
<td><code><a>writestart</a></code></td>
</tr>
</tbody>
<tbody>
<tr>
<td><dfn id="dfn-onprogress"><code>onprogress</code></dfn></td>
<td><code><a>progress</a></code></td>
</tr>
</tbody>
<tbody>
<tr>
<td><dfn id="dfn-onwrite"><code>onwrite</code></dfn></td>
<td><code><a>write</a></code></td>
</tr>
</tbody>
<tbody>
<tr>
<td><dfn id="dfn-onabort"><code>onabort</code></dfn></td>
<td><code><a>abort</a></code></td>
</tr>
</tbody>
<tbody>
<tr>
<td><dfn id="dfn-onerror"><code>onerror</code></dfn></td>
<td><code><a>error</a></code></td>
</tr>
</tbody>
<tbody>
<tr>
<td><dfn id="dfn-onwriteend"><code>onwriteend</code></dfn></td>
<td><code><a>writeend</a></code></td>
</tr>
</tbody>
</table>
</div>
</div>
<div id="the-filesaversync-interface" class="section">
<!--OddPage--><h2><span class="secno">6. </span>The <code>FileSaverSync</code> interface</h2>
<div class="issue">
<p>
It seems like this should have a blocking constructor and no methods
or properties, if it's to follow the constructor-based model of the
asynchronous interface. A global method seems like it would be
cleaner, though. Is it important that they match? If so, the asynch
constructor could turn into a method instead.
</p>
<p>
It's been pointed out that a method name like "saveAs" is too short
and generic; any global symbol should be longer and more explicit in
order to avoid confusion and naming conflicts.
</p>
</div>
</div>
<div id="the-filewriter-interface" class="section">
<!--OddPage--><h2><span class="secno">7. </span>The <a href="#idl-def-FileWriter" class="idlType"><code>FileWriter</code></a> interface</h2>
<p>
This interface expands on the <a href="#idl-def-FileSaver" class="idlType"><code>FileSaver</code></a> interface to allow for
multiple write actions, rather than just saving a single Blob.
</p>
<div class="issue">
Since this is intended to be used only with the sandboxed filesystem,
it could potentially move to the <a href="http://dev.w3.org/2009/dap/file-system/file-dir-sys.html">filesystem
spec</a>.
</div>
<pre class="idl"><span class="idlInterface" id="idl-def-FileWriter">[<span class="extAttr">NoInterfaceObject</span>]
interface <span class="idlInterfaceID">FileWriter</span> : <span class="idlSuperclass"><a href="#idl-def-FileSaver" class="idlType"><code>FileSaver</code></a></span> {
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long long</a></span> <span class="idlAttrName"><a href="#widl-FileWriter-position">position</a></span>;</span>
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long long</a></span> <span class="idlAttrName"><a href="#widl-FileWriter-length">length</a></span>;</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-FileWriter-write">write</a></span> (<span class="idlParam"><span class="idlParamType"><a>Blob</a></span> <span class="idlParamName">data</span></span>) raises (<span class="idlRaises"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></span>);</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-FileWriter-seek">seek</a></span> (<span class="idlParam"><span class="idlParamType"><a>long long</a></span> <span class="idlParamName">offset</span></span>) raises (<span class="idlRaises"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></span>);</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-FileWriter-truncate">truncate</a></span> (<span class="idlParam"><span class="idlParamType"><a>unsigned long long</a></span> <span class="idlParamName">size</span></span>) raises (<span class="idlRaises"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></span>);</span>
};</span>
</pre><div id="attributes-1" class="section"><h3><span class="secno">7.1 </span>Attributes</h3><dl class="attributes"><dt id="widl-FileWriter-length"><code>length</code> of type <span class="idlAttrType"><a>unsigned long long</a></span>, readonly</dt><dd>
<p>
The length of the file. If the user does not have read access to the
file, this <em class="rfc2119" title="must">must</em> be the highest byte offset at which the user has
written.
</p>
<div><em>No exceptions.</em></div></dd><dt id="widl-FileWriter-position"><code>position</code> of type <span class="idlAttrType"><a>unsigned long long</a></span>, readonly</dt><dd>
<p>
The byte offset at which the next write to the file will occur.
This <em class="rfc2119" title="must">must</em> be no greater than <code>length</code>.<br>
A newly-created FileWriter <em class="rfc2119" title="must">must</em> have position set to 0.
</p>
<div><em>No exceptions.</em></div></dd></dl></div><div id="methods-2" class="section"><h3><span class="secno">7.2 </span>Methods</h3><dl class="methods"><dt id="widl-FileWriter-seek"><code>seek</code></dt><dd>
<p>
Seek sets the file position at which the next write will occur.
</p>
<p>
Seek may not be called while the <a href="#idl-def-FileWriter" class="idlType"><code>FileWriter</code></a> is in the
<code>WRITING</code> state.
</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">offset</td><td class="prmType"><code><a>long long</a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc">
<p>
An absolute byte offset into the file. If <code>offset</code>
is greater than <code>length</code>, <code>length</code> is used
instead. If <code>offset</code> is less than zero,
<code>length</code> is added to it, so that it is treated as an
offset back from the end of the file. If it is still less than
zero, zero is used.<br>
</p>
</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>INVALID_STATE_ERR</code></td><td class="excCodeDesc">A user called <code>seek</code> while <code>readyState</code>
was <code>WRITING</code>.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-FileWriter-truncate"><code>truncate</code></dt><dd>
<p>
Changes the length of the file to that specified. If shortening the
file, data beyond the new length <em class="rfc2119" title="must">must</em> be discarded. If extending
the file, the existing data <em class="rfc2119" title="must">must</em> be zero-padded up to the new
length.
</p>
<p>
When the <code>truncate</code> method is called, <a href="#dfn-user-agents" class="internalDFN">user agents</a>
<em class="rfc2119" title="must">must</em> run the steps below (unless otherwise indicated).
</p>
<ol>
<li>If <code>readyState</code> is <code>WRITING</code>, throw a
<code>FileException</code> with error code
<code>INVALID_STATE_ERR</code> and terminate this overall series of
steps.</li>
<li>Set <code>readyState</code> to <code>WRITING</code>.</li>
<li>If an error occurs during truncate, proceed to the error steps
below.
<ol>
<li>Queue a task that will:
<ol>
<li>Set the <code>error</code> attribute; on getting the
<code>error</code> attribute <em class="rfc2119" title="must">must</em> be a
<code>FileError</code> object with a valid error code that
indicates the kind of file error that has occurred.</li>
<li>Set readyState to <code>DONE</code>.</li>
<li>Dispatch a progress event called
<code>error</code>.</li>
<li>Dispatch a progress event called
<code>writeend</code></li>
</ol></li>
<li>On getting, the <code>length</code> and
<code>position</code> attributes <em class="rfc2119" title="should">should</em> indicate any
modification to the file.</li>
<li>Terminate this overall set of steps.</li>
</ol>
</li>
<li>Queue a task to dispatch a progress event called
<code>writestart</code>.</li>
<li>Upon successful completion:
<ul>
<li><code>length</code> <em class="rfc2119" title="must">must</em> be equal to <code>size</code>.</li>
<li><code>position</code> <em class="rfc2119" title="must">must</em> be the lesser of
<ul>
<li>its pre-truncate value,</li>
<li><code>size</code>.</li>
</ul>
</li>
<li>Queue a task that will:
<ol>
<li>Set readyState to <code>DONE</code>.</li>
<li>Dispatch a progress event called <code>write</code></li>
<li>Dispatch a progress event called
<code>writeend</code></li>
</ol></li>
<li>Terminate this overall set of steps.</li>
</ul>
</li>
</ol>
<p></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">size</td><td class="prmType"><code><a>unsigned long long</a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc">
The size to which the length of the file is to be adjusted,
measured in bytes.
</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>INVALID_STATE_ERR</code></td><td class="excCodeDesc">A user called <code>truncate</code> while
<code>readyState</code> was <code>WRITING</code>.
</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-FileWriter-write"><code>write</code></dt><dd>
<p>
Write the supplied data to the file at <code>position</code>. When
the <code>write</code> method is called, <a href="#dfn-user-agents" class="internalDFN">user agents</a> <em class="rfc2119" title="must">must</em> run
the steps below (unless otherwise indicated).
</p><ol>
<li>If <code>readyState</code> is <code>WRITING</code>, throw a
<code>FileException</code> with error code
<code>INVALID_STATE_ERR</code> and terminate this overall series
of steps.</li>
<li>Set <code>readyState</code> to <code>WRITING</code>.</li>
<li>If an error occurs during file write, proceed to the error
steps below.
<ol>
<li>Queue a task that will:
<ol>
<li>Set the <code>error</code> attribute; on getting the
<code>error</code> attribute <em class="rfc2119" title="must">must</em> be a
<code>FileError</code> object with a valid error code that
indicates the kind of file error that has occurred.</li>
<li>Set readyState to <code>DONE</code>.</li>
<li>Dispatch a progress event called
<code>error</code>.</li>
<li>Dispatch a progress event called
<code>writeend</code></li>
</ol></li>
<li>On getting, the <code>length</code> and
<code>position</code> attributes <em class="rfc2119" title="should">should</em> indicate any
fractional data successfully written to the file.</li>
<li>Terminate this overall set of steps.</li>
</ol>
</li>
<li>Queue a task to dispatch a progress event called
<code>writestart</code>.</li>
<li>Make progress notifications. On getting, while processing the
<code>write</code> method, the <code>length</code> and
<code>position</code> attributes <em class="rfc2119" title="should">should</em> indicate the progress
made in writing the file as of the last progress notification.
</li>
<li>Upon successful completion:
<ol>
<li><code>position</code> and <code>length</code> <em class="rfc2119" title="must">must</em>
indicate an increase of <code>data.size</code> over their
pre-write states, indicating the change to the underlying
file.</li>
<li>Queue a task that will:
<ol>
<li>Set readyState to <code>DONE</code>.</li>
<li>Dispatch a progress event called
<code>write</code></li>
<li>Dispatch a progress event called
<code>writeend</code></li>
</ol></li>
<li>Terminate this overall set of steps.</li>
</ol>
</li></ol>
<p></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">data</td><td class="prmType"><code><a>Blob</a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc">
The blob to write.
</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>INVALID_STATE_ERR</code></td><td class="excCodeDesc">A user called <code>write</code> while <code>readyState</code>
was <code>WRITING</code>.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></div>
</div>
<div id="the-filewritersync-interface" class="section">
<!--OddPage--><h2><span class="secno">8. </span>The <code>FileWriterSync</code> interface</h2>
<p>
This interface lets users write, truncate, and append to files using
simple synchronous calls.
</p>
<p>
This interface is specified to be used only within Web Workers
(WorkerUtils [<cite><a class="bibref" rel="biblioentry" href="#bib-WEBWORKERS">WEBWORKERS</a></cite>]).
</p>
<div class="issue">
Since this is intended to be used only with the sandboxed filesystem,
it could potentially move to the <a href="http://dev.w3.org/2009/dap/file-system/file-dir-sys.html">filesystem
spec</a>.
</div>
<pre class="idl"><span class="idlInterface" id="idl-def-FileWriterSync">[<span class="extAttr">NoInterfaceObject</span>]
interface <span class="idlInterfaceID">FileWriterSync</span> {
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long long</a></span> <span class="idlAttrName"><a href="#widl-FileWriterSync-position">position</a></span>;</span>
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long long</a></span> <span class="idlAttrName"><a href="#widl-FileWriterSync-length">length</a></span>;</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-FileWriterSync-write">write</a></span> (<span class="idlParam"><span class="idlParamType"><a>Blob</a></span> <span class="idlParamName">data</span></span>) raises (<span class="idlRaises"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></span>);</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-FileWriterSync-seek">seek</a></span> (<span class="idlParam"><span class="idlParamType"><a>long long</a></span> <span class="idlParamName">offset</span></span>) raises (<span class="idlRaises"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></span>);</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-FileWriterSync-truncate">truncate</a></span> (<span class="idlParam"><span class="idlParamType"><a>unsigned long long</a></span> <span class="idlParamName">size</span></span>) raises (<span class="idlRaises"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></span>);</span>
};</span>
</pre><div id="attributes-2" class="section"><h3><span class="secno">8.1 </span>Attributes</h3><dl class="attributes"><dt id="widl-FileWriterSync-length"><code>length</code> of type <span class="idlAttrType"><a>unsigned long long</a></span>, readonly</dt><dd>
<p>
The length of the file. If the user does not have read access to
the file, this <em class="rfc2119" title="must">must</em> be the highest byte offset at which the user has
written.
</p>
<div><em>No exceptions.</em></div></dd><dt id="widl-FileWriterSync-position"><code>position</code> of type <span class="idlAttrType"><a>unsigned long long</a></span>, readonly</dt><dd>
<p>
The byte offset at which the next write to the file will occur.
This <em class="rfc2119" title="must">must</em> be no greater than <code>length</code>.
</p>
<div><em>No exceptions.</em></div></dd></dl></div><div id="methods-3" class="section"><h3><span class="secno">8.2 </span>Methods</h3><dl class="methods"><dt id="widl-FileWriterSync-seek"><code>seek</code></dt><dd>
<p>
Seek sets the file position at which the next write will occur.
</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">offset</td><td class="prmType"><code><a>long long</a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc">
An absolute byte offset into the file. If <code>offset</code>
is greater than <code>length</code>, <code>length</code> is used
instead. If <code>offset</code> is less than zero,
<code>length</code> is added to it, so that it is treated as an
offset back from the end of the file. If it is still less than
zero, zero is used.
</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>INVALID_STATE_ERR</code></td><td class="excCodeDesc">A user called <code>seek</code> while <code>readyState</code>
was <code>WRITING</code>.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-FileWriterSync-truncate"><code>truncate</code></dt><dd>
<p>
Changes the length of the file to that specified. If shortening the
file, data beyond the new length <em class="rfc2119" title="must">must</em> be discarded. If extending
the file, the existing data <em class="rfc2119" title="must">must</em> be zero-padded up to the new
length.
</p>
<p>
Upon successful completion:
</p><ul>
<li><code>length</code> <em class="rfc2119" title="must">must</em> be equal to <code>size</code>.</li>
<li><code>position</code> <em class="rfc2119" title="must">must</em> be the lesser of
<ul>
<li>its pre-truncate value,</li>
<li><code>size</code>.</li>
</ul>
</li>
</ul>
<p></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">size</td><td class="prmType"><code><a>unsigned long long</a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc">
The size to which the length of the file is to be adjusted,
measured in bytes.
</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>NO_MODIFICATION_ALLOWED_ERR</code></td><td class="excCodeDesc">The user attempted to modify a read-only file.</td></tr><tr><td class="excCodeName"><code>NOT_FOUND_ERR</code></td><td class="excCodeDesc">The file to be truncated does not exist.</td></tr><tr><td class="excCodeName"><code>SECURITY_ERR</code></td><td class="excCodeDesc">The system has disallowed the truncation for security
reasons.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-FileWriterSync-write"><code>write</code></dt><dd>
<p>
Write the supplied data to the file at <code>position</code>.
Upon completion, <code>position</code> will increase by
<code>data.size</code>.
</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">data</td><td class="prmType"><code><a>Blob</a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc">
The blob to write.
</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>NO_MODIFICATION_ALLOWED_ERR</code></td><td class="excCodeDesc">The user attempted to modify a read-only file.</td></tr><tr><td class="excCodeName"><code>NOT_FOUND_ERR</code></td><td class="excCodeDesc">The path to the directory containing the file to be written does
not exist, or the file does not exist and offset is nonzero.</td></tr><tr><td class="excCodeName"><code>INVALID_STATE_ERR</code></td><td class="excCodeDesc">At the time of the call, <code>readyState</code> was
<code>WRITING</code>.</td></tr><tr><td class="excCodeName"><code>SECURITY_ERR</code></td><td class="excCodeDesc">The system has disallowed the write for security reasons.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></div>
</div>
<div id="errors-and-exceptions" class="section">
<!--OddPage--><h2><span class="secno">9. </span>Errors and Exceptions</h2>
<p>
Error conditions can occur when attempting to write files. The list
below of potential error conditions is informative, with links to
normative descriptions of error codes:
</p>
<p>
The directory containing the file being written may not exist at the
time one of the asynchronous write methods or synchronous write methods
is called. This may be due to it having been moved or deleted after a
reference to it was acquired (e.g. concurrent modification with another
application).<br>
See <a href="#dfn-not_found_err" class="internalDFN">NOT_FOUND_ERR</a>.
</p>
<p>
The file being written may have been removed. If the file is not there,
writing to an offset other than zero is not permitted.<br>
See <a href="#dfn-not_found_err" class="internalDFN">NOT_FOUND_ERR</a>.
</p>
<p>
A file may be unwritable. This may be due to permission problems that
occur after a reference to a file has been acquired (e.g. concurrent
lock with another application).<br>
See <a href="#dfn-no_modification_allowed_err" class="internalDFN">NO_MODIFICATION_ALLOWED_ERR</a>.
</p>
<p>
User agents <em class="rfc2119" title="may">may</em> determine that some files are unsafe for use within web
applications. Additionally, some file and directory structures may be
considered restricted by the underlying filesystem; attempts to write to
them may be considered a security violation. See the security
considerations.<br>
See <a href="#dfn-security_err" class="internalDFN">SECURITY_ERR</a>.
</p>
<p>
A web application may attempt to initiate a write, seek, or truncate via
a FileWriter in the <code>WRITING</code> state.<br>
See <a href="#dfn-invalid_state_err" class="internalDFN">INVALID_STATE_ERR</a>.
</p>
<p>
During the writing of a file, the web application may itself wish to
abort (see abort()) the call to an asynchronous write method.<br>
See <a href="#dfn-abort_err" class="internalDFN">ABORT_ERR</a>.
</p>
<p>
A web application may request unsupported line endings.
See <a href="#dfn-syntax_err" class="internalDFN">SYNTAX_ERR</a>.
</p>
<div id="the-fileerror-interface" class="section">
<h3><span class="secno">9.1 </span>The FileError Interface</h3>
<p>
This interface extends the <a href="#idl-def-FileError" class="idlType"><code>FileError</code></a> interface described in
[<cite><a class="bibref" rel="biblioentry" href="#bib-FILE-API">FILE-API</a></cite>] to add several new error codes. It is used to report
errors asynchronously. The FileWriter object's error attribute is a
FileError object, and is accessed asynchronously through the onerror
event handler when error events are generated.
</p>
<pre class="idl"><span class="idlInterface" id="idl-def-FileError">interface <span class="idlInterfaceID">FileError</span> {
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileError-NOT_FOUND_ERR">NOT_FOUND_ERR</a></span> = <span class="idlConstValue">1</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileError-SECURITY_ERR">SECURITY_ERR</a></span> = <span class="idlConstValue">2</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileError-ABORT_ERR">ABORT_ERR</a></span> = <span class="idlConstValue">3</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileError-NOT_READABLE_ERR">NOT_READABLE_ERR</a></span> = <span class="idlConstValue">4</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileError-ENCODING_ERR">ENCODING_ERR</a></span> = <span class="idlConstValue">5</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileError-NO_MODIFICATION_ALLOWED_ERR">NO_MODIFICATION_ALLOWED_ERR</a></span> = <span class="idlConstValue">6</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileError-INVALID_STATE_ERR">INVALID_STATE_ERR</a></span> = <span class="idlConstValue">7</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileError-SYNTAX_ERR">SYNTAX_ERR</a></span> = <span class="idlConstValue">8</span>;</span>
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned short</a></span> <span class="idlAttrName"><a href="#widl-FileError-code">code</a></span>;</span>
};</span>
</pre><div id="attributes-3" class="section"><h4><span class="secno">9.1.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-FileError-code"><code>code</code> of type <span class="idlAttrType"><a>unsigned short</a></span>, readonly</dt><dd> <div><em>No exceptions.</em></div></dd></dl></div><div id="constants-1" class="section"><h4><span class="secno">9.1.2 </span>Constants</h4><dl class="constants"><dt id="widl-FileError-ABORT_ERR"><code>ABORT_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileError-ENCODING_ERR"><code>ENCODING_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileError-INVALID_STATE_ERR"><code>INVALID_STATE_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileError-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileError-NOT_READABLE_ERR"><code>NOT_READABLE_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileError-NO_MODIFICATION_ALLOWED_ERR"><code>NO_MODIFICATION_ALLOWED_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileError-SECURITY_ERR"><code>SECURITY_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileError-SYNTAX_ERR"><code>SYNTAX_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd></dl></div>
The <a>code</a> attribute <em class="rfc2119" title="must">must</em> return one of the constants of the
<a href="#idl-def-FileError" class="idlType"><code>FileError</code></a> error, which <em class="rfc2119" title="must">must</em> be the most appropriate code from the
<a href="#dfn-error-code-descriptions" class="internalDFN">Error Code Descriptions</a>.
</div>
<div id="the-fileexception-exception" class="section">
<h3><span class="secno">9.2 </span>The FileException exception</h3>
This interface extends the <a href="#idl-def-FileException" class="idlType"><code>FileException</code></a> interface described in
[<cite><a class="bibref" rel="biblioentry" href="#bib-FILE-API">FILE-API</a></cite>] to add several new error codes.
Any errors that need to be reported synchronously, including all that
occur during use of the synchronous write methods for Web Workers
[<cite><a class="bibref" rel="biblioentry" href="#bib-WEBWORKERS">WEBWORKERS</a></cite>] are reported using the FileException exception.
<pre class="idl"><span class="idlException" id="idl-def-FileException">exception <span class="idlExceptionID">FileException</span> {
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileException-NOT_FOUND_ERR">NOT_FOUND_ERR</a></span> = <span class="idlConstValue">1</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileException-SECURITY_ERR">SECURITY_ERR</a></span> = <span class="idlConstValue">2</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileException-ABORT_ERR">ABORT_ERR</a></span> = <span class="idlConstValue">3</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileException-NOT_READABLE_ERR">NOT_READABLE_ERR</a></span> = <span class="idlConstValue">4</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileException-ENCODING_ERR">ENCODING_ERR</a></span> = <span class="idlConstValue">5</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileException-NO_MODIFICATION_ALLOWED_ERR">NO_MODIFICATION_ALLOWED_ERR</a></span> = <span class="idlConstValue">6</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileException-INVALID_STATE_ERR">INVALID_STATE_ERR</a></span> = <span class="idlConstValue">7</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileException-SYNTAX_ERR">SYNTAX_ERR</a></span> = <span class="idlConstValue">8</span>;</span>
<span class="idlField"> <span class="idlFieldType"><a>unsigned short</a></span> <span class="idlFieldName"><a href="#widl-FileException-code">code</a></span>;</span>
};</span>
</pre><div id="fields" class="section"><h4><span class="secno">9.2.1 </span>Fields</h4><dl class="fields"><dt id="widl-FileException-code"><code>code</code> of type <span class="idlFieldType"><a>unsigned short</a></span></dt><dd> </dd></dl></div><div id="constants-2" class="section"><h4><span class="secno">9.2.2 </span>Constants</h4><dl class="constants"><dt id="widl-FileException-ABORT_ERR"><code>ABORT_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileException-ENCODING_ERR"><code>ENCODING_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileException-INVALID_STATE_ERR"><code>INVALID_STATE_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileException-NOT_READABLE_ERR"><code>NOT_READABLE_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileException-NO_MODIFICATION_ALLOWED_ERR"><code>NO_MODIFICATION_ALLOWED_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileException-SECURITY_ERR"><code>SECURITY_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileException-SYNTAX_ERR"><code>SYNTAX_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd></dl></div>
The <a>code</a> field <em class="rfc2119" title="must">must</em> return one of the constants of the
<a href="#idl-def-FileException" class="idlType"><code>FileException</code></a> error, which <em class="rfc2119" title="must">must</em> be the most appropriate code from
the <a href="#dfn-error-code-descriptions" class="internalDFN">Error Code Descriptions</a>.
</div>
<div id="error-code-descriptions" class="section">
<h3><span class="secno">9.3 </span><dfn id="dfn-error-code-descriptions">Error Code Descriptions</dfn></h3>
<table class="simple">
<thead>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
</thead>
<tbody>
<tr>
<td><dfn id="dfn-no_modification_allowed_err">NO_MODIFICATION_ALLOWED_ERR</dfn></td><td>7</td>
<td>User agents <em class="rfc2119" title="must">must</em> use this code when attempting to write to a
file which cannot be modified due to the state of the
underlying filesystem.
</td>
</tr>
<tr>
<td><dfn id="dfn-not_found_err">NOT_FOUND_ERR</dfn></td><td>8</td>
<td>User agents <em class="rfc2119" title="must">must</em> use this code if:
<ul>
<li>the directory containing the file to be written could
not be found at the time the write was processed.</li>
<li>the file to be written does not exist at the time the
write was processed, and an <code>offset</code> other than
zero is specified.</li>
</ul>
</td>
</tr>
<tr>
<td><dfn id="dfn-invalid_state_err">INVALID_STATE_ERR</dfn></td><td>11</td>
<td>User agents <em class="rfc2119" title="must">must</em> use this code if an application attempts to
initiate a write, truncate, or seek using a <a href="#idl-def-FileWriter" class="idlType"><code>FileWriter</code></a>
which is already in the <a>WRITING</a> state.
</td>
</tr>
<tr>
<td><dfn id="dfn-syntax_err">SYNTAX_ERR</dfn></td><td>12</td>
<td>User agents <em class="rfc2119" title="must">must</em> use this code when an application attempts
to supply an invalid line ending specifier to the API.
</td>
</tr>
<tr>
<td><dfn id="dfn-security_err">SECURITY_ERR</dfn></td><td>18</td>
<td>
User agents <em class="rfc2119" title="may">may</em> use this code if:
<ul>
<li> it is determined that certain files are unsafe for
access within a Web application</li>
<li>it is determined that too many write calls are being
made on file resources</li>
<li>it is determined that the file has changed on disk since
the user selected it</li>
</ul>
This is a security error code to be used in situations not
covered by any other error codes.
</td>
</tr>
<tr>
<td><dfn id="dfn-abort_err">ABORT_ERR</dfn></td><td>20</td>
<td>User agents <em class="rfc2119" title="must">must</em> use this code if the read operation was
aborted, typically with a call to <a>abort()</a>.
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="informative section" id="security-considerations">
<!--OddPage--><h2><span class="secno">10. </span>Security Considerations</h2><p><em>This section is non-normative.</em></p>
<div id="basic-security-model" class="section">
<h3><span class="secno">10.1 </span>Basic Security Model</h3>
<p>
Most of the security issues pertaining to writing to a file on the
user's drive are the same as those involved in downloading arbitrary
files from the Internet. The primary difference [in the case of
FileWriter] stems from the fact that the file may be continuously
written and re-written, at least until such a time as it is deemed
closed by the <a href="#dfn-user-agent" class="internalDFN">user agent</a>. This has an impact on disk quota, IO
bandwidth, and on processes that may require analysing the content of
the file.
</p>
</div>
<div id="write-only-files" class="section">
<h3><span class="secno">10.2 </span>Write-Only Files</h3>
<p>
When a user grants an application write access to a file, it doesn't
necessarily imply that the app should also receive read access to that
file or any of that file's metadata [including length]. This
specification describes a way in which that information can be kept
secret for write-only files. If the application has obtained a
<a href="#idl-def-FileWriter" class="idlType"><code>FileWriter</code></a> through a mechanism that also implies read access,
those restrictions may be relaxed.
</p>
</div>
<div id="quotas" class="section">
<h3><span class="secno">10.3 </span>Quotas</h3>
<p>
Where quotas are concerned, <a href="#dfn-user-agents" class="internalDFN">user agents</a> may wish to monitor the
size of the file(s) being written and possibly interrupt the script and
warn the user if certain limits of file size, remaining space, or disk
bandwidth are reached.
</p>
</div>
<div id="other-standard-techniques" class="section">
<h3><span class="secno">10.4 </span>Other Standard Techniques</h3>
<p>
Other parts of the download protection tool-chain such as flagging files
as unsafe to open, refusing to create dangerous file names, and making
sure that the mime type of a file matches its extension should naturally
be applied.
</p>
</div>
</div>
<div class="appendix section" id="acknowledgements">
<!--OddPage--><h2><span class="secno">A. </span>Acknowledgements</h2>
<p>
Thanks to Arun Ranganathan for his File API, Opera for theirs, and Robin
Berjon both for his work on various file APIs and for <a href="http://dev.w3.org/2009/dap/ReSpec.js/documentation.html">ReSpec</a>.
</p>
</div>
<div id="references" class="appendix section"><!--OddPage--><h2><span class="secno">B. </span>References</h2><div id="normative-references" class="section"><h3><span class="secno">B.1 </span>Normative references</h3><dl class="bibliography"><dt id="bib-FILE-API">[FILE-API]</dt><dd>Arun Ranganathan. <a href="http://www.w3.org/TR/2009/WD-FileAPI-20091117/"><cite>File API.</cite></a> 17 November 2009. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2009/WD-FileAPI-20091117/">http://www.w3.org/TR/2009/WD-FileAPI-20091117/</a>
</dd><dt id="bib-HTML5">[HTML5]</dt><dd>Ian Hickson; David Hyatt. <a href="http://www.w3.org/TR/2010/WD-html5-20100304/"><cite>HTML 5.</cite></a> 4 March 2010. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2010/WD-html5-20100304/">http://www.w3.org/TR/2010/WD-html5-20100304/</a>
</dd><dt id="bib-PROGRESS-EVENTS">[PROGRESS-EVENTS]</dt><dd>Charles McCathieNevile. <a href="http://www.w3.org/TR/2008/WD-progress-events-20080521"><cite>Progress Events 1.0.</cite></a> 21 May 2008. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2008/WD-progress-events-20080521">http://www.w3.org/TR/2008/WD-progress-events-20080521</a>
</dd><dt id="bib-RFC2119">[RFC2119]</dt><dd>S. Bradner. <a href="http://www.ietf.org/rfc/rfc2119.txt"><cite>Key words for use in RFCs to Indicate Requirement Levels.</cite></a> March 1997. Internet RFC 2119. URL: <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>
</dd><dt id="bib-TYPED-ARRAYS">[TYPED-ARRAYS]</dt><dd>Vladimir Vukicevic, Kenneth Russell. <a href="https://cvs.khronos.org/svn/repos/registry/trunk/public/webgl/doc/spec/TypedArray-spec.html"><cite>Typed Arrays</cite></a> Khronos Working Draft. (Work in progress.) URL: <a href="https://cvs.khronos.org/svn/repos/registry/trunk/public/webgl/doc/spec/TypedArray-spec.html">https://cvs.khronos.org/svn/repos/registry/trunk/public/webgl/doc/spec/TypedArray-spec.html</a>
</dd><dt id="bib-WEBWORKERS">[WEBWORKERS]</dt><dd>Ian Hickson. <a href="http://www.w3.org/TR/2009/WD-workers-20091222/"><cite>Web Workers.</cite></a> 22 December 2009. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2009/WD-workers-20091222/">http://www.w3.org/TR/2009/WD-workers-20091222/</a>
</dd></dl></div><div id="informative-references" class="section"><h3><span class="secno">B.2 </span>Informative references</h3><p>No informative references.</p></div></div></body></html>