- From: Eric Uhrhane via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 28 Apr 2010 01:41:32 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/file-system
In directory hutz:/tmp/cvs-serv587
Modified Files:
file-writer.html
Log Message:
I've rolled in feedback from the Device APIs and Policy WG [1], the WebApps WG [2], and some private communications [reporting typo-level errors] and posted a new draft [3]. In addition to trivial fixes, I also took care of the following issues:
>From Anne van Kesteren:
> I think the exception on append() should move to setting the endings attribute.
> I.e. when setting endings to an unsupported value it > throws. It should throw
> a SYNTAX_ERR exception. That would be most compatible with similar attributes
> in HTML5. (Attributes limited to a known set of values.)
I've changed to SYNTAX_ERR, and the exception is now thrown where the bad value is supplied.
For Dmitry Titov:
I cut the ending options to just two: transparent and native. I've left in the issue that we may want to drop ending conversion entirely, but I've yet to hear consensus for that.
For Dmitry Titov and Kinuko Yasuda:
I've converted the endings attribute to a parameter to append().
For Robin Berjon:
Fixed up or added normative references top DOM3 events and progress events.
Clarified the description about what happens when the user requests an unsupported ending conversion type.
For Darin Fisher and Jonas Sicking:
Added a contentType parameter to BlobBuilder.
For Kinuko Yasuda:
Added notes about obtaining a FileWriterSync.
The big unresolved issue at present is how one obtains a FileWriter for its basic use (that is, where one is not using the FileSystem API [4]).
[1] http://lists.w3.org/Archives/Public/public-device-apis/2010Mar/0072.html [whole thread]
[2] http://lists.w3.org/Archives/Public/public-webapps/2010JanMar/0910.html [see later in the thread]
[3] http://dev.w3.org/2009/dap/file-system/file-writer.html
[4] http://dev.w3.org/2009/dap/file-system/file-dir-sys.html
Index: file-writer.html
===================================================================
RCS file: /sources/public/2009/dap/file-system/file-writer.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -d -r1.8 -r1.9
--- file-writer.html 12 Apr 2010 12:56:02 -0000 1.8
+++ file-writer.html 28 Apr 2010 01:41:30 -0000 1.9
@@ -6,7 +6,7 @@
<script src='../ReSpec.js/js/respec.js' class='remove'></script>
<script class='remove'>
var respecConfig = {
- specStatus: "FPWD",
+ specStatus: "ED",
shortName: "file-writer-api",
publishDate: "2010-04-06",
// previousPublishDate: "1977-03-15",
@@ -97,7 +97,7 @@
}
var bb = new BlobBuilder();
- bb.appendText("Lorem ipsum");
+ bb.append("Lorem ipsum");
writer.onwrite = done;
writer.onerror = error;
writer.write(bb.getBlob());
@@ -118,84 +118,79 @@
<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 endings</dt>
- <dd>
- <p>
- How strings containing <code>\n</code> are to be written out.
- Changing <code>endings</code> affects only subsequent calls to
- <code>appendText</code>, and has no effect on the current contents
- of the <code>Blob</code>. The possible values are:
- </p>
- <table class='simple'>
- <tr><th>Value</th><th>Description</th></tr>
- <tr>
- <td>"transparent"</td>
- <td>
- Code points from the string remain untouched. This is the
- default value.
- </td>
- </tr>
- <tr>
- <td>"native"</td>
- <td>
- Line-endings are handled according to the platform's preference.
- </td>
- </tr>
- <tr>
- <td>"lf"</td>
- <td>
- A <code>LF</code> is used. This is used in Unix, Linux, and OSX
- systems.
- </td>
- </tr>
- <tr>
- <td>"cr"</td>
- <td>
- A <code>CR</code> is used. This is the same as was used in
- antique Macintosh systems.
- </td>
- </tr>
- <tr>
- <td>"crlf"</td>
- <td>
- A <code>CRLF</code> pair is used. This is the same as on
- Microsoft Windows systems.
- </td>
- </tr>
- </table>
- </dd>
<dt>Blob getBlob ()</dt>
<dd>
<p>
Returns the current contents of the <code>BlobBuilder</code> as a
<code>Blob</code>.
</p>
+ <dl class='parameters'>
+ <dt>in optional DOMString contentType</dt>
+ <dd>
+ Sets the content type of the blob produced.
+ </dd>
+ </dl>
+ <div class=issue>
+ The content type of the blob is a proposed property relevant only
+ if [[!FILE-API]] adopts it. See <a
+ href="http://lists.w3.org/Archives/Public/public-webapps/2010JanMar/0910.html">discussion</a>.
+ </div>
</dd>
<dt>void append ()</dt>
<dd>
<p>
Appends the supplied text to the current contents of the
- <code>BlobBuilder</code>, writing it as UTF-8, taking into account the
- current state of <code>endings</code>.
+ <code>BlobBuilder</code>, writing it as UTF-8, converting newlines as
+ specified in <code>endings</code>.
</p>
<dl class='parameters'>
<dt>in DOMString text</dt>
<dd>
The data to write.
</dd>
+ <dt>in optional DOMString endings</dt>
+ <dd>
+ <p>
+ This parementer 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
+ 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:
+ </p>
+ <table class='simple'>
+ <tr><th>Value</th><th>Description</th></tr>
+ <tr>
+ <td>"transparent"</td>
+ <td>
+ Code points from the string MUST remain unchanged.
+ </td>
+ </tr>
+ <tr>
+ <td>"native"</td>
+ <td>
+ Newlines MUST be transformed to the default line-ending
+ representation of the underlying host filesystem. For
+ example, if the underlying filesystem is FAT32, newlines
+ would be transformed into <code>\r\n</code> pairs as the
+ text was appended to the state of the BlobBuilder.
+ </td>
+ </tr>
+ </table>
+ </dd>
+ <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>
<dl class='exception' title='FileException'>
- <dt>ENCODING_ERR</dt>
- <dd>The value of <a>endings</a> does not correspond to a supported
- policy.</dd>
+ <dt>SYNTAX_ERR</dt>
+ <dd>The user supplied an unsupported value for <a>endings</a>.
+ </dd>
</dl>
</dd>
<dt>void append ()</dt>
@@ -215,7 +210,7 @@
<section>
<h2>Constructor</h2>
<p>
- When the <a>BlobBuilder</a> constructor is invoked, the user agent must
+ When the <a>BlobBuilder</a> constructor is invoked, the user agent MUST
return a new <a>BlobBuilder</a> object.
</p>
</section>
@@ -224,12 +219,12 @@
<h2>The <a>FileWriter</a> interface</h2>
<p>
This interface provides methods to write blobs to disk using
- progress events and event handler attributes [DOM3Events]. 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]]).
+ 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]]).
</p>
<dl title='[NoInterfaceObject] interface FileWriter' class='idl'>
<dt>void abort ()</dt>
@@ -322,7 +317,8 @@
<dd>
<p>
The byte offset at which the next write to the file will occur.
- This MUST be no greater than <code>length</code>.
+ This MUST be no greater than <code>length</code>.<br />
+ A newly-created FileWriter MUST have position set to 0.
</p>
</dd>
<dt>readonly attribute long long length</dt>
@@ -405,19 +401,20 @@
<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>
+ <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.<br />
+ A newly-created FileWriter MUST have position set to 0.
+ </p>
</dd>
</dl>
<dl class='exception' title='FileException'>
<dt>INVALID_STATE_ERR</dt>
- <dd>A user called <code>write</code> while <code>readyState</code>
+ <dd>A user called <code>seek</code> while <code>readyState</code>
was <code>WRITING</code>.
</dl>
</dd>
@@ -457,8 +454,21 @@
<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.
+ completion:
+ <ul>
+ <li><code>length</code> MUST be the lesser of
+ <ul>
+ <li>its pre-truncate value,</li>
+ <li><code>size</code>.</li>
+ </ul>
+ </li>
+ <li><code>position</code> MUST be the lesser of
+ <ul>
+ <li>its pre-truncate value,</li>
+ <li><code>size</code>.</li>
+ </ul>
+ </li>
+ </ul>
</li>
<li>Dispatch a progress event called <code>write</code></li>
<li>Dispatch a progress event called <code>writeend</code></li>
@@ -553,8 +563,9 @@
</dd>
</dl>
<dl class='exception' title='FileException'>
- <dt>TODO</dt>
- <dd>TODO</dd>
+ <dt>INVALID_STATE_ERR</dt>
+ <dd>A user called <code>seek</code> while <code>readyState</code>
+ was <code>WRITING</code>.
</dl>
</dd>
<dt>void truncate ()</dt>
@@ -568,6 +579,23 @@
The size to which the file is truncated, measured in bytes. If
<code>size</code> is greater than or equal to <code>length</code>,
this has no effect.
+ <p>
+ Upon successful completion:
+ <ul>
+ <li><code>length</code> MUST be the lesser of
+ <ul>
+ <li>its pre-truncate value,</li>
+ <li><code>size</code>.</li>
+ </ul>
+ </li>
+ <li><code>position</code> MUST be the lesser of
+ <ul>
+ <li>its pre-truncate value,</li>
+ <li><code>size</code>.</li>
+ </ul>
+ </li>
+ </ul>
+ </p>
</dd>
</dl>
<dl class='exception' title='FileException'>
@@ -624,7 +652,7 @@
</p>
<p>
A web application may request unsupported line endings.
- See ENCODING_ERR
+ See SYNTAX_ERR
</p>
<section>
<h2>The FileError Interface</h2>
@@ -642,14 +670,14 @@
<dd> </dd>
<dt>const unsigned short INVALID_STATE_ERR = 11</dt>
<dd> </dd>
+ <dt>const unsigned short SYNTAX_ERR = 12</dt>
+ <dd> </dd>
<dt>const unsigned short SECURITY_ERR = 18</dt>
<dd> </dd>
<dt>const unsigned short ABORT_ERR = 20</dt>
<dd> </dd>
<dt>const unsigned short NOT_READABLE_ERR = 24</dt>
<dd> </dd>
- <dt>const unsigned short ENCODING_ERR = 26</dt>
- <dd> </dd>
<dt>readonly attribute unsigned short code</dt>
<dd> </dd>
</dl>
@@ -671,14 +699,14 @@
<dd> </dd>
<dt>const unsigned short INVALID_STATE_ERR = 11</dt>
<dd> </dd>
+ <dt>const unsigned short SYNTAX_ERR = 12</dt>
+ <dd> </dd>
<dt>const unsigned short SECURITY_ERR = 18</dt>
<dd> </dd>
<dt>const unsigned short ABORT_ERR = 20</dt>
<dd> </dd>
<dt>const unsigned short NOT_READABLE_ERR = 24</dt>
<dd> </dd>
- <dt>const unsigned short ENCODING_ERR = 26</dt>
- <dd> </dd>
<dt>unsigned short code</dt>
<dd> </dd>
</dl>
@@ -720,6 +748,12 @@
</td>
</tr>
<tr>
+ <td>SYNTAX_ERR</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>
User agents MAY use this code if:
@@ -741,12 +775,6 @@
aborted, typically with a call to <a>abort()</a>.
</td>
</tr>
- <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 line ending specifier.
- </td>
- </tr>
</tbody>
</table>
</section>
@@ -760,13 +788,58 @@
</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 file writer. Issues have been noted concerning the <code>type=saveas</code>
- approach, and it has been suggested that an API call to prompt for download directly
- would introduce no security risk not already present in the browser stack. Feedback from
- the community is particularly welcome on this point.
+ The group has not at this time reached consensus on the best manner in
+ which to obtain access to a file 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 FileWriter 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 FileWriter; 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
+ FileWriter, also has issues:
+ <ol>
+ <li>It makes the standard FileWriter 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 FileWriterSync. It
+ may be useful for a FileWriter to be passed via postMessage to a Worker.
+ Perhaps Workers should be able to convert a FileWriter to a
+ FileWriterSync at will? Note that we may want to invalidate any
+ FileWriter sent by postMessage or converted to a FileWriterSync, to
+ reduce problems of having the same underlying handle open in two places.
+ </div>
<section>
<h2>Obtaining file writers via HTML input element</h2>
<p>
Received on Wednesday, 28 April 2010 01:41:34 UTC