- From: Eric Uhrhane via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 10 Mar 2010 02:39:22 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/file-system
In directory hutz:/tmp/cvs-serv6631
Modified Files:
file-writer.html
Log Message:
Rolling in initial feedback.
Index: file-writer.html
===================================================================
RCS file: /sources/public/2009/dap/file-system/file-writer.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- file-writer.html 6 Mar 2010 01:55:32 -0000 1.2
+++ file-writer.html 10 Mar 2010 02:39:20 -0000 1.3
@@ -92,7 +92,6 @@
}
var bb = new BlobBuilder();
- bb.encoding = "UTF-16LE";
bb.appendText("Lorem ipsum");
writer.onwrite = done;
writer.onerror = error;
@@ -107,24 +106,14 @@
<p>
BlobBuilder description
</p>
+ <div class='issue'>Can we do without endings? Any choice other than
+ "transparent" can be implemented by the app author, and most file
+ formats don't care about line endings. "Transparent" would be handy for
+ sharing certain types of text files with apps outside the browser [e.g.
+ Makefiles on a system where make is expecting \n will have issues if
+ they're written with \r\n]. Is it worth it? Can this be worked around
+ if we don't supply it?</div>
<dl title='[Constructor] interface BlobBuilder' class='idl'>
- <dt>attribute DOMString encoding</dt>
- <dd>
- <p>
- The encoding that is used to write the <code>String</code> to the
- <code>Blob</code>. The default value is <code>UTF-8</code>. Changing
- <code>encoding</code> affects only subsequent calls to
- <code>appendText</code>, and has no effect on the current contents of
- the <code>Blob</code>.
- </p>
- <div class='issue'>
- <p>What encodings should we require beyond UTF-8, if
- any--UTF-16LE, UTF-16BE? ISO-8859-1? We probably want to avoid
- anything with a BOM, as it makes repeated appendText calls and Blob
- concatenation awkward.
- </p>
- </div>
- </dd>
<dt>attribute DOMString endings</dt>
<dd>
<p>
@@ -178,12 +167,12 @@
<code>Blob</code>.
</p>
</dd>
- <dt>void appendText ()</dt>
+ <dt>void append ()</dt>
<dd>
<p>
Appends the supplied text to the current contents of the
- <code>BlobBuilder</code>, converting to binary according to the
- current state of <code>encoding</code> and <code>endings</code>.
+ <code>BlobBuilder</code>, writing it as UTF-8, taking into account the
+ current state of <code>endings</code>.
</p>
<dl class='parameters'>
<dt>in DOMString text</dt>
@@ -193,12 +182,11 @@
</dl>
<dl class='exception' title='FileException'>
<dt>ENCODING_ERR</dt>
- <dd>The value of <a>encoding</a> does not correspond to a supported
- encoding, or the value of <a>endings</a> does not correspond to a
- supported policy.</dd>
+ <dd>The value of <a>endings</a> does not correspond to a supported
+ policy.</dd>
</dl>
</dd>
- <dt>void appendBlob ()</dt>
+ <dt>void append ()</dt>
<dd>
<p>
Appends the supplied <a>Blob</a> to the current contents of the
@@ -212,6 +200,13 @@
</dl>
</dd>
</dl>
+ <section>
+ <h2>Constructor</h2>
+ <p>
+ When the <a>BlobBuilder</a> constructor is invoked, the user agent must
+ return a new <a>BlobBuilder</a> object.
+ </p>
+ </section>
</section>
<section>
<h2>The <a>FileWriter</a> interface</h2>
@@ -337,7 +332,7 @@
<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>INIT</code>.</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.
@@ -356,20 +351,21 @@
<li>Terminate this overall set of steps.</li>
</ol>
</li>
- <li>If no error has occurred, set <code>readyState</code> to
- <code>WRITING</code>.</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.</li>
+ 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>
@@ -390,23 +386,73 @@
<p>
Seek sets the file position at which the next write will occur.
</p>
+ <p>
+ Seek may not be called while the <a>FileWriter</a> is in the
+ <code>WRITING</code> state.
+ </p>
<dl class='parameters'>
<dt>long long position</dt>
<dd>
+ <p>
An absolute byte offset into the file. If <code>position</code>
is greater than <code>length</code>, <code>length</code> is used
instead. If <code>position</code> is less than zero,
<code>length</code> is added to it, so that it is treated as an
offset back from the end of the file. If it is still less than
zero, zero is used.
+ </p>
</dd>
</dl>
+ <dl class='exception' title='FileException'>
+ <font color=red>TODO: Specify error codes here; refer to
+ DOMException, File API, and anywhere else we'll be trying to
+ match.</font>
+ </dl>
</dd>
<dt>void truncate ()</dt>
<dd>
<p>
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).
+ </p>
+ <ol>
+ <li>If <code>readyState</code> is <code>WRITING</code>, throw a
+ <code>FileException</code> with error code
+ <code>INVALID_STATE_ERR</code> and terminate this overall series of
+ steps.</li>
+ <li>Set <code>readyState</code> to <code>WRITING</code>.</li>
+ <li>If an error occurs during truncate, 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
+ modification to the file.</li>
+ <li>Terminate this overall set of steps.</li>
+ </ol>
+ </li>
+ <li>Queue a task to dispatch a progress event called
+ <code>writestart</code>.</li>
+ <li>When the file has been truncated, set
+ <code>readyState</code> to <code>DONE</code>. Upon successful
+ completion, <code>position</code> and <code>length</code> MUST
+ be 0.
+ </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>long long size</dt>
<dd>
@@ -415,6 +461,11 @@
this has no effect.
</dd>
</dl>
+ <dl class='exception' title='FileException'>
+ <dt>INVALID_STATE_ERR</dt>
+ <dd>A user called <code>truncate</code> while
+ <code>readyState</code> was <code>WRITING</code>.
+ </dl>
</dd>
</dl>
<section>
@@ -424,12 +475,12 @@
links to a reference section, as in the File API spec.
<-->
<p>
- The <a>FileWriter</a> interface enables asynchronous reads 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>FileWriter</a>. This task source [[!HTML5]] is used for events
- tasks that are asynchronously dispatched, or for event tasks that are
- queued for dispatching.
+ The <a>FileWriter</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>FileWriter</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>
@@ -468,9 +519,6 @@
</dd>
</dl>
<dl class='exception' title='FileException'>
- <font color=red>TODO: Specify error codes here; refer to
- DOMException, File API, and anywhere else we'll be trying to
- match.</font>
</dl>
</dd>
<dt>void seek ()</dt>
@@ -489,6 +537,8 @@
zero, zero is used.
</dd>
</dl>
+ <dl class='exception' title='FileException'>
+ </dl>
</dd>
<dt>void truncate ()</dt>
<dd>
@@ -503,6 +553,8 @@
this has no effect.
</dd>
</dl>
+ <dl class='exception' title='FileException'>
+ </dl>
</dd>
</dl>
</section>
@@ -542,8 +594,8 @@
See SECURITY_ERR
</p>
<p>
- A web application may attempt to initiate a write via a FileWriter in
- the <a>FileWriter-WRITING</a> state.<br/>
+ A web application may attempt to initiate a write, seek, or truncate via
+ a FileWriter in the <a>FileWriter-WRITING</a> state.<br/>
See INVALID_STATE_ERR
</p>
<p>
@@ -552,7 +604,7 @@
See ABORT_ERR
</p>
<p>
- A web application may request an unsupported encoding.
+ A web application may request unsupported line endings.
See ENCODING_ERR
</p>
<section>
@@ -655,8 +707,8 @@
<ul>
<li> it is determined that certain files are unsafe for
access within a Web application</li>
- <li>it is determined that too many read calls are being made
- on file resources</li>
+ <li>it is determined that too many write calls are being
+ made on file resources</li>
<li>it is determined that the file has changed on disk since
the user selected it</li>
</ul>
@@ -673,7 +725,7 @@
<tr>
<td>ENCODING_ERR</td><td>26</td>
<td>User agents MUST use this code when an application requests
- conversion of text using an unsupported encoding.
+ conversion of text using an unsupported line ending specifier.
</td>
</tr>
</tbody>
@@ -684,20 +736,92 @@
<h2>Obtaining file writers</h2>
<p>
This spec describes one way to obtain a FileWriter. Not all <a>user
- agents</a> may implement this, and other methods may be provided by
+ agents</a> may implement this, and other methods may be provided by
other specs.
</p>
<section>
<h2>Obtaining file writers via HTML input element</h2>
- A new HTML input element is added with <code>type=saveas</code>. This
- functions similarly to the element of <code>type=file</code>, except
- that instead of presenting a File-Open picker and returning a list of
- <a>File</a> objects, it presents a File-Save-As picker and returns a
- single <a>FileWriter</a>.
+ <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 <a>File</a> objects, it presents a File-Save-As picker and
+ returns a single <a>FileWriter</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 FileWriter.
+ </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 FileWriter 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>fileWriter</code> applies, which holds
+ a reference to a <a>FileWriter</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>fileWriter</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>fileWriter</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>
- <div class='issue'>TODO: Think about fallback for older browsers that
- don't support it; is <input type=file writable> better than
- <input type=saveas>?</div>
+ </section>
+ <section class='informative'>
+ Here's an example of obtaining a <a>FileWriter</a> from a HTML input
+ element:
+ <div class='example sh_javascript'>
+ var fileWriter = document.forms['downloadData']['fileChooser'].fileWriter;
+ </div>
</section>
</section>
<section class='informative'>
Received on Wednesday, 10 March 2010 02:39:25 UTC