2009/dap/file-system file-writer.html,1.14,1.15

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. &lt;save&gt;.</li>
-            <li>A new command type, e.g. &lt;command type='save'&gt;</li>
-            <li>A rel value, e.g. &lt;button rel='save'&gt;</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