- 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