- From: Eric Uhrhane via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 16 Jul 2010 23:20:19 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/file-system
In directory hutz:/tmp/cvs-serv23622
Modified Files:
file-writer.html
Log Message:
Split FileWriter [BlobWriter] into two interfaces, now called FileSaver and
FileWriter.
Did lots of other cleanup, linkifying, and descriptions.
Index: file-writer.html
===================================================================
RCS file: /sources/public/2009/dap/file-system/file-writer.html,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -d -r1.14 -r1.15
--- file-writer.html 8 Jul 2010 18:21:31 -0000 1.14
+++ file-writer.html 16 Jul 2010 23:20:17 -0000 1.15
@@ -8,7 +8,7 @@
var respecConfig = {
specStatus: "ED",
shortName: "file-writer-api",
- publishDate: "2010-04-06",
+ //publishDate: "2010-04-06",
// previousPublishDate: "1977-03-15",
edDraftURI: "http://dev.w3.org/2009/dap/file-system/file-writer.html",
// lcEnd: "2009-08-05",
@@ -42,12 +42,13 @@
<ul>
<li> A <a>BlobBuilder</a> interface, which enables one to build a
<code>Blob</code> from a String.
- <li> A <a>BlobWriter</a> interface, which provides methods to write a
- <code>Blob</code> to a file, and an event model to obtain the results
- of those writes.</li>
- <li> A <a>BlobWriterSync</a> interface, which provides methods to
- write a <code>Blob</code> to a file synchronously from the Worker
- context.</li>
+ <li> A <a>FileSaver</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>FileWriter</a> interface, which expands on FileSaver to add
+ a richer set of output options.</li>
+ <li> A <a>FileWriterSync</a> interface, which provides methods to
+ write and modify files synchronously in a Web Worker.</li>
</ul>
</p>
</section>
@@ -63,9 +64,54 @@
<section id='conformance'>
<p>
This specification defines conformance criteria that apply to a single
- product: <dfn>user agents</dfn> that implement the interfaces that it
+ product: <a>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 MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD
+ NOT, RECOMMENDED, MAY, and OPTIONAL 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> [[!RFC2119]].
+ </p>
+
+ <p>
+ The following conformance classes are defined by this specification:
+ <dl>
+ <dt><dfn>conforming implementation</dfn></dt>
+ <dd>
+ <p>
+ A <dfn>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>
+ </section>
+
+ <section>
+ <h2>Terminology and Algorithms</h2>
+ <p>
+ The terms and algorithms <dfn>event handler attributes</dfn>, <dfn>event
+ handler event types</dfn>, <dfn>Function</dfn>, <dfn>task</dfn>,
+ <dfn>task source</dfn>, and <dfn>queue a task</dfn> are defined by the
+ HTML 5 specification [[!HTML5]].
+ </p>
+
+ <p>
+ This specification includes algorithms (steps) as part of the definition
+ of methods. Conforming implementations (referred to as <dfn>user
+ agents</dfn> from here on) MAY use other algorithms in the
+ implementation of these methods, provided the end result is the same.
+ </p>
</section>
<section class='informative'>
@@ -75,8 +121,8 @@
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 user agents can permit applications to write generated
- or downloaded files.
+ API through which <a>user agents</a> can permit applications to write
+ generated or downloaded files.
</p>
<p>
The [[!FILE-API]] defined interfaces for reading files, manipulation of
@@ -90,7 +136,7 @@
<section>
<h2>Examples</h2>
<p>
- Here is a simple function that writes a text file, given a BlobWriter:
+ Here is a simple function that writes a text file, given a FileWriter:
</p>
<pre class='example sh_javascript'>
function writeFile(writer) {
@@ -109,10 +155,13 @@
}
</pre>
<p>
- Here's an example of obtaining a <a>BlobWriter</a> from a HTML input
- element:
- <pre class='example sh_javascript'>
- var blobWriter = document.forms['downloadData']['fileChooser'].blobWriter;
+ Here's an example of obtaining and using a <a>FileSaver</a>:
+ </p>
+ <pre class='example sh_javascript'>
+ var bb = new BlobBuilder();
+ bb.append("Lorem ipsum");
+ var fileSaver = window.saveAs(bb.getBlob(), "test_file");
+ fileSaver.onwriteend = myOnWriteEnd;
</pre>
</p>
</section>
@@ -159,10 +208,11 @@
<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, the user agent MUST act as if
+ <code>endings</code> parameter, <a>user agents<a> MUST act as if
the user had specified a value of 'transparent'. If the user
- provides the <code>endings</code> parameter, the user agent MUST
- convert newlines as specified below. The possible values are:
+ provides the <code>endings</code> parameter, <a>user agents<a>
+ MUST convert newlines as specified below. The possible values
+ are:
</p>
<table class='simple'>
<tr><th>Value</th><th>Description</th></tr>
@@ -215,31 +265,41 @@
<section>
<h2>Constructor</h2>
<p>
- When the <a>BlobBuilder</a> constructor is invoked, the user agent MUST
- return a new <a>BlobBuilder</a> object.
+ When the <a>BlobBuilder</a> constructor is invoked, <a>user agents</a>
+ MUST return a new <a>BlobBuilder</a> object.
+ </p>
+ <p>
+ This constructor MUST be visible when the script's global object is
+ either a Window object or an object implementing the WorkerUtils
+ interface.
</p>
</section>
</section>
<section>
- <h2>The <a>BlobWriter</a> interface</h2>
+ <h2>The <a>FileSaver</a> interface</h2>
<p>
- This interface provides methods to write blobs to disk using
- progress events [[!PROGRESS-EVENTS]] and event handler attributes
- [[!DOM-LEVEL-3-EVENTS]]. It is desirable to write data to file systems
- asynchronously in the main thread of user agents. This interface
- provides such an asynchronous API, and is specified to be used within
- the context of the global object (Window [[!HTML5]]) as well as Web
- Workers (WorkerUtils [[!WEBWORKERS]]).
+ This interface provides methods to monitor the asynchronous writing of
+ blobs to disk using progress events [[!PROGRESS-EVENTS]] and <a>event
+ handler attributes</a>.
</p>
- <dl title='[NoInterfaceObject] interface BlobWriter' class='idl'>
+ <p>
+ This interface is specified to be used within the context of the global
+ object (Window [[!HTML5]]) and within Web Workers (WorkerUtils
+ [[!WEBWORKERS]]).
+ </p>
+ <dl title='[Constructor(in Blob data)] interface FileSaver' class='idl'>
<dt>void abort ()</dt>
<dd>
<p>
- When the <code>abort</code> method is called, the user agent MUST
- run the steps below:<!-->TODO: refs<-->
+ When the <code>abort</code> method is called, <a>user agents</a>
+ MUST run the steps below:<!-->TODO: refs<-->
<ol>
+ <li>If <code>readyState</code> is <code>DONE</code>, throw a
+ <code>FileException</code> with error code
+ <code>INVALID_STATE_ERR</code> and terminate this overall series
+ of steps.</li>
<li>Set readyState to DONE and result to null.</li>
- <li>Terminate any steps while processing a write method.</li>
+ <li>Terminate any steps having to do with writing a file.</li>
<li>Dispatch a progress event called error. Set the error
attribute to a FileError object with the appropriate code (in this
case, ABORT_ERR; see error conditions).</li>
@@ -248,6 +308,11 @@
<li>Stop dispatching any further progress events.</li>
</ol>
</p>
+ <dl class='exception' title='FileException'>
+ <dt>INVALID_STATE_ERR</dt>
+ <dd>A user called <code>abort</code> while <code>readyState</code>
+ was <code>DONE</code>.
+ </dl>
</dd>
<dt>const unsigned short INIT = 0</dt>
<dd>
@@ -259,14 +324,14 @@
</dd>
<dt>const unsigned short DONE = 2</dt>
<dd>
- The entire Blob has been written to the file, or a file error occurred
+ 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
- BlobWriter is no longer writing the blob.
+ FileSaver is no longer writing the blob.
</dd>
<dt>readonly attribute unsigned short readyState</dt>
<dd>
<p>
- The BlobWriter object can be in one of 3 states. The
+ The FileSaver object can be in one of 3 states. The
<a>readyState</a> attribute, on getting, MUST return the current
state, which MUST be one of the following values:
<ul>
@@ -318,12 +383,158 @@
Handler for writeend events.
</p>
</dd>
+ </dl>
+ <section>
+ <h2>The FileSaver Constructor</h2>
+ <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>FileSaver</a> contructor is called, the <a>user agent</a>
+ MUST return a new <a>FileSaver</a> object with <code>readyState</code>
+ set to <code>INIT</code>.
+ </p>
+ <p>
+ This constructor MUST be visible when the script's global object is
+ either a Window object or an object implementing the WorkerUtils
+ interface.
+ </p>
+ </section>
+ <section>
+ <h2>The FileSaver Task Source</h2>
+ <!-->
+ 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>FileSaver</a> interface enables asynchronous writes on
+ individual files by dispatching events to event handler methods. Unless
+ stated otherwise, the <a>task source</a> that is used in this
+ specification is the <a>FileSaver</a>. This <a>task source</a> is
+ used for any event <a>task</a> that is asynchronously dispatched, or for
+ event tasks that are queued for dispatching.
+ </p>
+ <p>
+ After its contructor has returned, a new FileSaver MUST 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, set
+ <code>readyState</code> to <code>DONE</code>.
+ Proceed to the error steps below.
+ <ol>
+ <li>Dispatch a progress event called <code>error</code>. Set
+ the <code>error</code> attribute; on getting the
+ <code>error</code> attribute MUST be a
+ <code>FileError</code> object with a valid error code that
+ indicates the kind of file error that has occurred.</li>
+ <li>Dispatch a progress event called <code>writeend</code>.</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, set
+ <code>readyState</code> 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>
+ <li>Terminate this overall set of steps.</li>
+ </ol>
+ </section>
+ <section>
+ <h2>Event Handler Attributes</h2>
+ <p>
+ The following are the <a>event handler attributes</a> (and their
+ corresponding <a>event handler event types</a>) that user agents MUST
+ support on <code><a>FileSaver</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><code>onwritestart</code></dfn></td>
+ <td><code><a>writestart</a></code></td>
+ </tr>
+ </tbody>
+ <tbody>
+ <tr>
+ <td><dfn><code>onprogress</code></dfn></td>
+ <td><code><a>progress</a></code></td>
+ </tr>
+ </tbody>
+ <tbody>
+ <tr>
+ <td><dfn><code>onwrite</code></dfn></td>
+ <td><code><a>write</a></code></td>
+ </tr>
+ </tbody>
+ <tbody>
+ <tr>
+ <td><dfn><code>onabort</code></dfn></td>
+ <td><code><a>abort</a></code></td>
+ </tr>
+ </tbody>
+ <tbody>
+ <tr>
+ <td><dfn><code>onerror</code></dfn></td>
+ <td><code><a>error</a></code></td>
+ </tr>
+ </tbody>
+ <tbody>
+ <tr>
+ <td><dfn><code>onwriteend</code></dfn></td>
+ <td><code><a>writeend</a></code></td>
+ </tr>
+ </tbody>
+ </table>
+ </section>
+ </section>
+ <section>
+ <h2>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 contructor-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>
+ </section>
+ <section>
+ <h2>The <a>FileWriter</a> interface</h2>
+ <p>
+ This interface expands on the <a>FileSaver</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 filessytem,
+ it should probably move to the <a
+ href="http://dev.w3.org/2009/dap/file-system/file-dir-sys.html">filesystem
+ spec</a>.
+ </div>
+ <dl title='[NoInterfaceObject] interface FileWriter : FileSaver'
+ class='idl'>
<dt>readonly attribute long long position</dt>
<dd>
<p>
The byte offset at which the next write to the file will occur.
This MUST be no greater than <code>length</code>.<br />
- A newly-created BlobWriter MUST have position set to 0.
+ A newly-created FileWriter MUST have position set to 0.
</p>
</dd>
<dt>readonly attribute long long length</dt>
@@ -337,50 +548,51 @@
<dt>void write ()</dt>
<dd>
<p>
- Write the supplied data to the file at <code>position</code>.
- When the <code>write</code> method is called, the user agent MUST run
- the steps below (unless otherwise indicated).
- <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, set
- <code>readyState</code> to <code>DONE</code>.
- Proceed to the error steps below.
- <ol>
- <li>Dispatch a progress event called <code>error</code>. Set
- the <code>error</code> attribute; on getting the
- <code>error</code> attribute MUST be a
- <code>FileError</code> object with a valid error code that
- indicates the kind of file
- error that has occurred.</li>
- <li>Dispatch a progress event called
- <code>writeend</code></li>
- <li>On getting, the <code>length</code> and
- <code>position</code> attributes SHOULD 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 SHOULD indicate the progress made
- in writing the file as of the last progress notification.
- </li>
- <li>When the data has been fully written, set
- <code>readyState</code> to <code>DONE</code>. Upon successful
- completion, <code>position</code> and <code>length</code> MUST
- indicate an increase of <code>data.size</code> over their
- pre-write states, indicating the change to the underlying file.
- </li>
- <li>Dispatch a progress event called <code>write</code></li>
- <li>Dispatch a progress event called <code>writeend</code></li>
- <li>Terminate this overall set of steps.</li>
- </ol>
+ Write the supplied data to the file at <code>position</code>. When
+ the <code>write</code> method is called, <a>user agents</a> MUST run
+ the steps below (unless otherwise indicated).
+ <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, set
+ <code>readyState</code> to <code>DONE</code>.
+ Proceed to the error steps below.
+ <ol>
+ <li>
+ Dispatch a progress event called <code>error</code>. Set
+ the <code>error</code> attribute; on getting the
+ <code>error</code> attribute MUST be a
+ <code>FileError</code> object with a valid error code that
+ indicates the kind of file
+ error that has occurred.</li>
+ <li>Dispatch a progress event called
+ <code>writeend</code></li>
+ <li>On getting, the <code>length</code> and
+ <code>position</code> attributes SHOULD 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 SHOULD indicate the progress
+ made in writing the file as of the last progress notification.
+ </li>
+ <li>When the data has been fully written, set
+ <code>readyState</code> to <code>DONE</code>. Upon successful
+ completion, <code>position</code> and <code>length</code> MUST
+ indicate an increase of <code>data.size</code> over their
+ pre-write states, indicating the change to the underlying file.
+ </li>
+ <li>Dispatch a progress event called <code>write</code></li>
+ <li>Dispatch a progress event called <code>writeend</code></li>
+ <li>Terminate this overall set of steps.</li>
+ </ol>
</p>
<dl class='parameters'>
<dt>Blob data</dt>
@@ -400,7 +612,7 @@
Seek sets the file position at which the next write will occur.
</p>
<p>
- Seek may not be called while the <a>BlobWriter</a> is in the
+ Seek may not be called while the <a>FileWriter</a> is in the
<code>WRITING</code> state.
</p>
<dl class='parameters'>
@@ -413,7 +625,7 @@
<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 />
- A newly-created BlobWriter MUST have position set to 0.
+ A newly-created FileWriter MUST have position set to 0.
</p>
</dd>
</dl>
@@ -429,8 +641,8 @@
Shortens the file to the length specified.
</p>
<p>
- When the <code>truncate</code> method is called, the user agent MUST
- run the steps below (unless otherwise indicated).
+ When the <code>truncate</code> method is called, <a>user agents</a>
+ MUST run the steps below (unless otherwise indicated).
</p>
<ol>
<li>If <code>readyState</code> is <code>WRITING</code>, throw a
@@ -496,28 +708,24 @@
</dl>
</dd>
</dl>
- <section>
- <h2>The BlobWriter Task Source</h2>
- <!-->
- 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>BlobWriter</a> interface enables asynchronous writes on
- individual files by dispatching events to event handler methods. Unless
- stated otherwise, the task source [[!HTML5]] that is used in this
- specification is the <a>BlobWriter</a>. This task source [[!HTML5]] is
- used for events tasks that are asynchronously dispatched, or for event
- tasks that are queued for dispatching.
- </p>
- </section>
</section>
<section>
- <h2>The <code>BlobWriterSync</code> interface</h2>
+ <h2>The <code>FileWriterSync</code> interface</h2>
<p>
- BlobWriterSync description
+ This interface lets users write, truncate, and append to files using
+ simple synchronous calls.
</p>
- <dl title='[NoInterfaceObject] interface BlobWriterSync' class='idl'>
+ <p>
+ This interface is specified to be used only within Web Workers
+ (WorkerUtils [[!WEBWORKERS]]).
+ </p>
+ <div class=issue>
+ Since this is intended to be used only with the sandboxed filessytem,
+ it should probably move to the <a
+ href="http://dev.w3.org/2009/dap/file-system/file-dir-sys.html">filesystem
+ spec</a>.
+ </div>
+ <dl title='[NoInterfaceObject] interface FileWriterSync' class='idl'>
<dt>readonly attribute long long position</dt>
<dd>
<p>
@@ -547,8 +755,16 @@
</dd>
</dl>
<dl class='exception' title='FileException'>
- <dt>TODO</dt>
- <dd>TODO</dd>
+ <dt>NO_MODIFICATION_ALLOWED_ERR</dt>
+ <dd>The user attempted to modify a read-only file.</dd>
+ <dt>NOT_FOUND_ERR</dt>
+ <dd>The path to the directory containing the file to be written does
+ not exist, or the file does not exist and offset is nonzero.</dd>
+ <dt>INVALID_STATE_ERR</dt>
+ <dd>At the time of the call, <code>readyState</code> was
+ <code>WRITING</code>.</dd>
+ <dt>SECURITY_ERR</dt>
+ <dd>The system has disallowed the write for security reasons.</dd>
</dl>
</dd>
<dt>void seek ()</dt>
@@ -604,8 +820,16 @@
</dd>
</dl>
<dl class='exception' title='FileException'>
- <dt>TODO</dt>
- <dd>TODO</dd>
+ <dt>NO_MODIFICATION_ALLOWED_ERR</dt>
+ <dd>The user attempted to modify a read-only file.</dd>
+ <dt>NOT_FOUND_ERR</dt>
+ <dd>The file to be truncated does not exist.</dd>
+ <dt>INVALID_STATE_ERR</dt>
+ <dd>At the time of the call, readyState was
+ <code>WRITING</code>.</dd>
+ <dt>SECURITY_ERR</dt>
+ <dd>The system has disallowed the truncation for security
+ reasons.</dd>
</dl>
</dd>
</dl>
@@ -624,18 +848,18 @@
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 NOT_FOUND_ERR
+ See <a>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 NOT_FOUND_ERR
+ See <a>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 NO_MODIFICATION_ALLOWED_ERR
+ See <a>NO_MODIFICATION_ALLOWED_ERR</a>.
</p>
<p>
User agents MAY determine that some files are unsafe for use within web
@@ -643,28 +867,28 @@
considered restricted by the underlying filesystem; attempts to write to
them may be considered a security violation. See the security
considerations.<br/>
- See SECURITY_ERR
+ See <a>SECURITY_ERR</a>.
</p>
<p>
A web application may attempt to initiate a write, seek, or truncate via
- a BlobWriter in the <a>BlobWriter-WRITING</a> state.<br/>
- See INVALID_STATE_ERR
+ a FileWriter in the <code>WRITING</code> state.<br/>
+ See <a>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 ABORT_ERR
+ See <a>ABORT_ERR</a>.
</p>
<p>
A web application may request unsupported line endings.
- See SYNTAX_ERR
+ See <a>SYNTAX_ERR</a>.
</p>
<section>
<h2>The FileError Interface</h2>
<p>
This interface extends the <a>FileError</a> interface described in
[[!FILE-API]] to add several new error codes. It is used to report
- errors asynchronously. The BlobWriter object's error attribute is a
+ 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>
@@ -688,7 +912,7 @@
</dl>
The <a>code</a> attribute MUST return one of the constants of the
<a>FileError</a> error, which MUST be the most appropriate code from the
- table below.
+ <a>Error Code Descriptions</a>.
</section>
<section>
<h2>The FileException exception</h2>
@@ -717,24 +941,24 @@
</dl>
The <a>code</a> field MUST return one of the constants of the
<a>FileException</a> error, which MUST be the most appropriate code from
- the table below.
+ the <a>Error Code Descriptions</a>.
</section>
<section>
- <h2>Error Code Descriptions</h2>
+ <h2><dfn>Error Code Descriptions</dfn></h2>
<table class='simple'>
<thead>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
</thead>
<tbody>
<tr>
- <td>NO_MODIFICATION_ALLOWED_ERR</td><td>7</td>
+ <td><dfn>NO_MODIFICATION_ALLOWED_ERR</dfn></td><td>7</td>
<td>User agents MUST 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>NOT_FOUND_ERR</td><td>8</td>
+ <td><dfn>NOT_FOUND_ERR</dfn></td><td>8</td>
<td>User agents MUST use this code if:
<ul>
<li>the directory containing the file to be written could
@@ -746,20 +970,20 @@
</td>
</tr>
<tr>
- <td>INVALID_STATE_ERR</td><td>11</td>
+ <td><dfn>INVALID_STATE_ERR</dfn></td><td>11</td>
<td>User agents MUST use this code if an application attempts to
- initiate a write, truncate, or seek using a <a>BlobWriter</a>
+ initiate a write, truncate, or seek using a <a>FileWriter</a>
which is already in the <a>WRITING</a> state.
</td>
</tr>
<tr>
- <td>SYNTAX_ERR</td><td>12</td>
+ <td><dfn>SYNTAX_ERR</dfn></td><td>12</td>
<td>User agents MUST use this code when an application attempts
to supply an invalid line ending specifier to the API.
</td>
</tr>
<tr>
- <td>SECURITY_ERR</td><td>18</td>
+ <td><dfn>SECURITY_ERR</dfn></td><td>18</td>
<td>
User agents MAY use this code if:
<ul>
@@ -775,7 +999,7 @@
</td>
</tr>
<tr>
- <td>ABORT_ERR</td><td>20</td>
+ <td><dfn>ABORT_ERR</dfn></td><td>20</td>
<td>User agents MUST use this code if the read operation was
aborted, typically with a call to <a>abort()</a>.
</td>
@@ -784,145 +1008,6 @@
</table>
</section>
</section>
- <section>
- <h2>Obtaining blob writers</h2>
- <p>
- This spec describes one way to obtain a BlobWriter. Not all <a>user
- agents</a> may implement this, and other methods may be provided by
- other specs.
- </p>
- <div class='issue'>
- <p>
- The group has not at this time reached consensus on the best manner in
- which to obtain access to a blob writer.
-
- Issues with an input control:
- <ol>
- <li>An unsupported input type falls back to a text area, which is
- ugly and unhelpful [suggested fix: use a new button type instead,
- which then would fall back to a button that could be hooked with
- JavaScript to do something useful].</li>
- <li>A BlobWriter can write a file multiple times; this differs from
- the "SaveAs" semantic, and may be unintuitive to users. Smart UI
- may help this, but may not completely obviate confusion. [suggested
- fix: add a "close" function to BlobWriter; until it's called, show
- the download manager and indicate that the file is active].
- </ol>
-
- One suggested alternative, a programmatic API that creates a
- BlobWriter, also has issues:
- <ol>
- <li>It makes the standard BlobWriter usage flow involve popping up a
- "SaveAs" dialog without user initiation.</li>
- <li>If the API pops up the SaveAs on write(), using multiple write
- calls to produce a file becomes annoying. If the API pops up on
- creating instead, it has the same rewrite semantic that was
- problematic with the input control.</li>
- </ol>
-
- Other suggested alternatives have had less discussion:
- <ol>
- <li>A completely new element type, e.g. <save>.</li>
- <li>A new command type, e.g. <command type='save'></li>
- <li>A rel value, e.g. <button rel='save'></li>
- </ol>
-
- <p>
- No differences in security have been noted between the two
- approaches.
- </p>
-
- <p>
- Feedback from the community is particularly welcome on this point.
- </p>
- </p>
- </div>
- <div class='issue'>
- This spec does not yet provide any way to obtain a BlobWriterSync. It
- may be useful for a BlobWriter to be passed via postMessage to a Worker.
- Perhaps Workers should be able to convert a BlobWriter to a
- BlobWriterSync at will? Note that we may want to invalidate any
- BlobWriter sent by postMessage or converted to a BlobWriterSync, to
- reduce problems of having the same underlying handle open in two places.
- </div>
- <section>
- <h2>Obtaining blob writers via HTML input element</h2>
- <p>
- A new HTML input element state is added with <code>type=saveas</code>,
- corresponding to the <code>File SaveAs</code> state.
- This functions similarly to the <code>File Upload</code> state,
- except that instead of presenting a File-Open picker and returning a
- list of <code>File</code> objects, it presents a File-Save-As picker and
- returns a single <a>BlobWriter</a>. Here is a description of an input
- element in the File SaveAs state.
- </p>
- <p>
- The input element represents write access to a selected file, embodied
- as a <a>BlobWriter</a>.
- </p>
- <p>
- If the element is mutable, the user agent should allow the user to
- change the selected file. The file can be an existing file in a
- filesystem [which is to be overwritten], or can be a new file.
- </p>
- <p>
- If the element is required and the list of
- selected files is empty, then the element is suffering from being
- missing.
- </p>
- <p>
- There must be no more than one file selected.
- </p>
- <p>
- A BlobWriter obtained from such an element MUST begin with
- <a>position</a> and <a>length</a> each set to 0, as no read access of
- any kind is granted by the user's selection of the file.
- </p>
- <p>
- Bookkeeping details
- <ol>
- <li>The following common input element content attribute applies to
- the element: <code>required</code>.
- <li>The following common input element IDL attribute applies to the
- element: <code>value</code>.</li>
- <li>A new IDL attribute <code>blobWriter</code> applies, which holds
- a reference to a <a>BlobWriter</a> object.
- <li>The <code>value</code> IDL attribute is in mode
- <code>filename</code>, with the exception that there is only a
- single selected file, <code>blobWriter</code>, not a list,
- <code>files</code>. This means that setting <code>value</code> on
- an input element in the File SaveAs state will clear
- <code>blobWriter</code> rather than <code>files</code>.</li>
- <li>The change event applies.</li>
- <li>The following content attributes must not be specified and do
- not apply to the element: <code>accept</code>, <code>alt</code>,
- <code>autocomplete</code>, <code>checked</code>,
- <code>formaction</code>, <code>formenctype</code>,
- <code>formmethod</code>, <code>formnovalidate</code>,
- <code>formtarget</code>,
- <code>height</code>, <code>list</code>, <code>max</code>,
- <code>maxlength</code>, <code>min</code>, <code>multiple</code>,
- <code>pattern</code>, <code>placeholder</code>,
- <code>readonly</code>, <code>size</code>, <code>src</code>,
- <code>step</code>, and <code>width</code>.</li>
- <li>The element's <code>value</code> attribute must be omitted.</li>
- <li>The following IDL attributes and methods do not apply to the
- element: <code>checked</code>, <code>list</code>,
- <code>selectedOption</code>, <code>selectionStart</code>,
- <code>selectionEnd</code>, <code>valueAsDate</code>, and
- <code>valueAsNumber</code> IDL attributes;
- <code>select()</code>, <code>setSelectionRange()</code>,
- <code>stepDown()</code>, and <code>stepUp()</code>
- methods.</li>
- <li>The input event does not apply.</li>
- </ol>
- </p>
-
- <div class='issue'>This section needs more polishing than most to bring
- it up to snuff as an actual specification.</div>
- <div class='issue'>TODO: Explore integration with drag-out.</div>
- </section>
- </section>
<section class='informative'>
<h2>Security Considerations</h2>
<section>
@@ -930,11 +1015,12 @@
<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 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 user agent. This has an impact on
- disk quota, IO bandwidth, and on processes that may require analysing
- the content of the file.
+ 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>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>
</section>
<section>
@@ -945,7 +1031,7 @@
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>BlobWriter</a> through a mechanism that also implies read access,
+ <a>FileWriter</a> through a mechanism that also implies read access,
those restrictions may be relaxed.
</p>
</section>
@@ -962,8 +1048,9 @@
<h2>Other Standard Techniques</h2>
<p>
Other parts of the download protection tool-chain such as flagging files
- as unsafe to open or refusing to create dangerous file names should
- naturally be applied.
+ 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>
</section>
</section>
@@ -971,7 +1058,8 @@
<h2>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 ReSpec.
+ 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>
</section>
</body>
Received on Friday, 16 July 2010 23:20:22 UTC