- From: Eric Uhrhane via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 08 Jul 2010 00:52:19 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/file-system
In directory hutz:/tmp/cvs-serv6594
Modified Files:
file-dir-sys.html
Log Message:
Rolling in lots of feedback dating back to April: many small tweaks, a better
introduction+use cases, simpler requestFileSystem, more examples, some
reordering, etc.
Index: file-dir-sys.html
===================================================================
RCS file: /sources/public/2009/dap/file-system/file-dir-sys.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -d -r1.8 -r1.9
--- file-dir-sys.html 28 Jun 2010 21:36:26 -0000 1.8
+++ file-dir-sys.html 8 Jul 2010 00:52:17 -0000 1.9
@@ -47,10 +47,86 @@
<section class='informative'>
<h2>Introduction</h2>
<p>
- The filesystem API is intended to be minimal in extent, but sufficiently
- powerful that easy-to-use libraries may be built on top of it.
+ This API is intended to satisfy client-side-storage use cases not
+ well served by databases. These are generally applications that involve
+ large binary blobs and/or share data with applications outside of the
+ browser.
+ </p>
+ <p>
+ It is intended to be minimal in extent, but sufficiently powerful that
+ easy-to-use libraries may be built on top of it.
</p>
<section>
+ <h2>Use Cases</h2>
+ <ol>
+ <li>Persistent uploader
+ <ul>
+ <li>When a file or directory is selected for upload, it copies it
+ into a local sandbox and uploads a chunk at a time.</li>
+ <li>It can restart uploads after browser crashes, network
+ interruptions, etc.</li>
+ </ul>
+ </li>
+ <li>Video game or other app with lots of media assets
+ <ul>
+ <li>It downloads one or several large tarballs, and expands them
+ locally into a directory structure.</li>
+ <li>The same download should work on any operating system.</li>
+ <li>It can manage prefetching just the next-to-be-needed assets in
+ the background, so going to the next game level or activating a new
+ feature doesn't require waiting for a download.</li>
+ <li>It uses those assets directly from its local cache, by direct
+ file reads or by handing local URIs to image or video tags, WebGL
+ asset loaders, etc.</li>
+ <li>The files may be of arbitrary binary format.</li>
+ <li>On the server side, a compressed tarball will often be much
+ smaller than a collection of separately-compressed files. Also, 1
+ tarball instead of 1000 little files will involve fewer seeks, all
+ else being equal.</li>
+ </ul>
+ </li>
+
+ <li>Audio/Photo editor with offline access or local cache for speed
+ <ul>
+ <li>The data blobs are potentially quite large, and are
+ read-write.</li>
+ <li>It may want to do partial writes to files (ovewriting just the
+ ID3/EXIF tags, for example).</li>
+ <li>The ability to organize project files by creating directories
+ would be useful.</li>
+ <li>Edited files should be accessable by client-side applications
+ [iTunes, Picasa].
+ </ul>
+ </li>
+
+ <li>Offline video viewer
+ <ul>
+ <li>It downloads large files (>1GB) for later viewing.</li>
+ <li>It needs efficient seek + streaming.</li>
+ <li>It must be able to hand a URI to the video tag.</li>
+ <li>It should enable access to partly-downloaded files e.g. to let
+ you watch the first episode of the DVD even if your download didn't
+ complete before you got on the plane.</li>
+ <li>It should be able to pull a single episode out of the middle of
+ a download and give just that to the video tag.</li>
+ </ul>
+ </li>
+
+ <li>Offline Web Mail Client
+ <ul>
+ <li>Downloads attachments and stores them locally.</li>
+ <li>Caches user-selected attachments for later upload.</li>
+ <li>Needs to be able to refer to cached attachments and image
+ thumbnails for display and upload.</li>
+ <li>Should be able to trigger the UA's download manager just as if
+ talking to a server.</li>
+ <li>Should be able to upload an email with attachments as a
+ multipart post, rather than sending a file at a time in an XHR.</li>
+ </ul>
+ </li>
+ </ol>
+ </section>
+ <section>
<h2>Examples</h2>
<pre class='example sh_javascript'>
function useAsyncFS(fs) {
@@ -67,40 +143,61 @@
// In the DOM or worker context:
- requestTemporaryFilesystem(1024 * 1024, function(fs) {
+ requestFileSystem(false, 1024 * 1024, function(fs) {
useAsyncFS(fs);
}
// In a worker:
- var tempFS = requestTemporaryFilesystem(1024 * 1024);
+ var tempFS = requestFileSystem(false, 1024 * 1024);
var logFile = tempFS.root.getFile("logFile", tempFS.root.CREATE);
- writeDataToLogFile(logFile.createWriter());
-
- // In a device:
-
- filesystems(function(list) {
- var fs = list[0];
- useAsyncFS(fs);
- })
+ var writer = logFile.createWriter();
+ writer.seek(writer.length);
+ writeDataToLogFile(writer);
</pre>
</section>
</section>
<section>
<h2>Data Persistence and accessing the API</h2>
- <p>
- <a>Filesystem</a> and <a>FilesystemSync</a> objects returned by
- <code>requestTemporaryFilesystem</code> and
- <code>requestPersistentFilesystem</code>
- MUST have the following properties:
+ <section class='informative'>
+ <h2>Temporary vs. Persistent Storage</h2>
+ <p>
+ An application can request temporary or persistent storage space.
+ Temporary storage may be easier to get, at the UA's discretion [looser
+ quota restrictions, available without prompting the user], but the
+ data stored there may be deleted at the UA's convenience, e.g. to deal
+ with a shortage of disk space.
+ </p>
+ <p>
+ Conversely, once persistent storage has been granted, data stored
+ there by the application should not be deleted by the UA without user
+ intervention. The application may of course delete it at will. The
+ UA should require permission from the user before granting persistent
+ storage space to the application.
+ </p>
+ <p>
+ This API specifies the standard origin isolation in a filesystem
+ context, along with persistence of data across invocations.
+ Applications will likely use temporary storage for caching, and if
+ it's still around from a previous session, it is often useful.
+ Persistent data, on the other hand, is useless if you can't access it
+ again the next time you're invoked. However, even with persistent
+ data, the user may delete it manually [either through the UA or via
+ direct filesystem operations].
+ </p>
+ </section>
+ <section>
+ <h2>Restrictions</h2>
+ <a>FileSystem</a> and <a>FileSystemSync</a> objects returned by
+ <code>requestFileSystem</code> MUST have the following properties:
<ul>
<li>The filesystems accessible by any origin MUST be disjoint from
those accessible by any other origin.</li>
<li>If
<ol>
<li> an application in a given origin requests a persistent
- filesystem more than once;</li>
+ filesystem on multiple occasions;</li>
<li> each request is granted;</li>
<li> and data from an earlier request still exists in the first
filesystem at the time of a subsequent request.</li>
@@ -111,7 +208,7 @@
<li>If
<ol>
<li> an application in a given origin requests a temporary
- filesystem more than once;</li>
+ filesystem on multiple occasions;</li>
<li> each request is granted;</li>
<li> and data from an earlier request still exists in the first
filesystem at the time of a subsequent request.</li>
@@ -124,40 +221,6 @@
<li>Data stored in a persistent filesystem SHOULD NOT be deleted by
the UA, other than in response to a removal API call, without explicit
authorization from the user.</li> </ul>
- </p>
- <section class='informative'>
- <p>
- An application can request temporary or persistent storage space.
- Temporary storage may be easier to get, at the UA's discretion [looser
- quota restrictions, available without prompting the user], but the
- data stored there may be deleted at the UA's convenience, e.g. to deal
- with a shortage of disk space.
- </p>
- <p>
- Conversely, once persistent storage has been granted, data stored
- there by the application should not be deleted by the UA without user
- intervention. The application may of course delete it at will. The
- UA should require permission from the user before granting persistent
- storage space to the application.
- </p>
- <p>
- This API specifies the standard origin isolation in a filesystem
- context, along with persistence of data across invocations.
- Applications will likely use temporary storage for caching, and if
- it's still around from a previous session, it is often useful.
- Persistent data, on the other hand, is useless if you can't access it
- again the next time you're invoked. However, even with persistent
- data, the user may delete it manually [either through the UA or via
- direct filesystem operations].
- </p>
- <p>
- As with any other client-side storage, filesystem access allows for
- cookie-resurrection attacks. UAs should present the option of
- clearing it when the user clears any other origin-specific storage,
- blocking access to it when cookies are blocked, etc. This is
- especially important if temporary storage space is permitted by
- default without explicit user permission.
- </p>
</section>
<section class='informative'>
<h2>Security Considerations</h2>
@@ -167,7 +230,8 @@
that must be dealt with. Risks to the user include:
<ul>
<li>Denial of service by filling a local disk or using up IO
- bandwidth</li>
+ bandwidth. This can be mitigated in part through quota
+ limitations.</li>
<li>Theft or erasure of private data. This is mitigated by limiting
the scope of access to the local filesystem to a chroot-like,
origin-specific sandbox.</li>
@@ -182,9 +246,20 @@
of filesystem access that the user doesn't connect the two
events.</li>
</ul>
+ This may be mitigated by restricting file creation/rename to
+ non-executable extensions, and by making sure the execute bit is
+ not set on any file created or modified via the API.
</li>
</ul>
</p>
+ <p>
+ As with any other client-side storage, filesystem access allows for
+ cookie-resurrection attacks. UAs will likely wish to present the
+ option of clearing it when the user clears any other origin-specific
+ storage, blocking access to it when cookies are blocked, etc. This is
+ especially important if temporary storage space is permitted by
+ default without explicit user permission.
+ </p>
</section>
<section>
<h2>Obtaining access to file system entry points</h2>
@@ -197,57 +272,35 @@
[[!WEBWORKERS]].
</p>
<section>
- <h2>Using <code>LocalFilesystem</code></h2>
- <div class='idl' title='Window implements LocalFilesystem'></div>
+ <h2>Using <code>LocalFileSystem</code></h2>
+ <div class='idl' title='Window implements LocalFileSystem'></div>
<div class='idl' title='WorkerGlobalScope implements
- LocalFilesystem'></div> <dl title='[Supplemental, NoInterfaceObject]
- interface LocalFilesystem' class='idl'>
- <dt>void requestTemporaryFilesystem ()</dt>
+ LocalFileSystem'></div> <dl title='[Supplemental, NoInterfaceObject]
+ interface LocalFileSystem' class='idl'>
+ <dt>void requestFileSystem ()</dt>
<dd>
<p>
- Requests a filesystem in which to store temporary data.
+ Requests a filesystem in which to store application data.
</p>
<p>
If successful, this function MUST give access to an
- origin-private temporary filesystem, as defined above.
+ origin-private filesystem, as defined above.
</p>
<dl class='parameters'>
- <dt>long long size</dt>
- <dd>
- This is an indicator of how much storage space, in bytes, the
- application expects to need.
- </dd>
- <dt>FilesystemCallback successCallback</dt>
- <dd>
- The callback that is called when the <a>user agent</a> provides
- a temporary filesystem.
- </dd>
- <dt>optional ErrorCallback errorCallback</dt>
+ <dt>boolean persistent</dt>
<dd>
- A callback that is called when errors happen, or when the
- request to obtain the filesystem is denied.
+ Whether the filesystem requested should be persistent, as
+ defined above.
</dd>
- </dl>
- </dd>
- <dt>void requestPersistentFilesystem ()</dt>
- <dd>
- <p>
- Requests a filesystem in which to store persistent data.
- </p>
- <p>
- If successful, this function MUST give access to an
- origin-private persistent filesystem, as defined above.
- </p>
- <dl class='parameters'>
<dt>long long size</dt>
<dd>
This is an indicator of how much storage space, in bytes, the
application expects to need.
</dd>
- <dt>FilesystemCallback successCallback</dt>
+ <dt>FileSystemCallback successCallback</dt>
<dd>
The callback that is called when the <a>user agent</a> provides
- a persistent filesystem.
+ a filesystem.
</dd>
<dt>optional ErrorCallback errorCallback</dt>
<dd>
@@ -256,7 +309,7 @@
</dd>
</dl>
</dd>
- <dt>void resolveLocalFilesystemURI ()</dt>
+ <dt>void resolveLocalFileSystemURI ()</dt>
<dd>
<p>
Allows the user to look up the Entry for a file or directory
@@ -283,43 +336,26 @@
</dl>
</section>
<section>
- <h2>Using <code>LocalFilesystemSync</code></h2>
+ <h2>Using <code>LocalFileSystemSync</code></h2>
<div class='idl' title='WorkerGlobalScope implements
- LocalFilesystemSync'></div>
+ LocalFileSystemSync'></div>
<dl title='[Supplemental, NoInterfaceObject] interface
- LocalFilesystemSync' class='idl'>
- <dt>FilesystemSync requestTemporaryFilesystemSync ()</dt>
+ LocalFileSystemSync' class='idl'>
+ <dt>FileSystemSync requestFileSystemSync ()</dt>
<dd>
<p>
- Requests a filesystem in which to store temporary data.
+ Requests a filesystem in which to store application data.
</p>
<p>
If successful, this function MUST give access to an
- origin-private temporary filesystem, as defined above.
+ origin-private filesystem, as defined above.
</p>
<dl class='parameters'>
- <dt>long long size</dt>
+ <dt>boolean persistent</dt>
<dd>
- This is an indicator of how much storage space, in bytes, the
- application expects to need.
+ Whether the filesystem requested should be persistent, as
+ defined above.
</dd>
- </dl>
- <dl class='exception' title='FileException'>
- <dt>SECURITY_ERR</dt>
- <dd>The application does not have permission to access the
- filesystem interface.</dd>
- </dl>
- </dd>
- <dt>FilesystemSync requestPersistentFilesystemSync ()</dt>
- <dd>
- <p>
- Requests a filesystem in which to store persistent data.
- </p>
- <p>
- If successful, this function MUST give access to an
- origin-private persistent filesystem, as defined above.
- </p>
- <dl class='parameters'>
<dt>long long size</dt>
<dd>
This is an indicator of how much storage space, in bytes, the
@@ -332,7 +368,7 @@
filesystem interface.</dd>
</dl>
</dd>
- <dt>EntrySync resolveLocalFilesystemSyncURI ()</dt>
+ <dt>EntrySync resolveLocalFileSystemSyncURI ()</dt>
<dd>
<p>
Allows the user to look up the Entry for a file or directory
@@ -358,71 +394,70 @@
</dd>
</dl>
</section>
- <section>
- <h2>Requesting asynchronous filesystem accessors from the
- <a>Device</a> interface</h2>
- <p>
- The <a>Device</a> interface is typically exposed on the
- <code>navigator.device</code> object, as defined in
- [[!CORE-DEVICE]].
- </p>
- <div class='idl' title='Device implements DeviceFilesystem'></div>
- <dl title='[Supplemental, NoInterfaceObject] interface
- DeviceFilesystem' class='idl'>
- <dt>void filesystems ()</dt>
- <dd>
- <p>
- Requests a list of file systems available on the device.
- </p>
- <dl class='parameters'>
- <dt>FilesystemsCallback successCallback</dt>
- <dd>
- The callback that is called when the <a>user agent</a> provides
- a list of available file systems.
- </dd>
- <dt>optional ErrorCallback errorCallback</dt>
- <dd>
- A callback that is called when errors happen, or when the
- request to obtain a list of file systems is denied.
- </dd>
- </dl>
- </dd>
- <dt>void resolveLocalFilesystemURI ()</dt>
- <dd>
- <p>
- Allows the user to look up the Entry for a file or directory
- referred to by a local URI.
- </p>
- <dl class='parameters'>
- <dt>DOMString uri</dt>
- <dd>
- A URI referring to a local file in a filesystem accessable via
- this API.
- </dd>
- <dt>EntryCallback successCallback</dt>
- <dd>
- A callback that is called to report the Entry to which the
- supplied URI refers.
- </dd>
- <dt>optional ErrorCallback errorCallback</dt>
- <dd>
- A callback that is called when errors happen.
- </dd>
- </dl>
- </dd>
- </dl>
- </section>
</section>
</section>
<section>
+ <h2>Shared data types</h2>
+ <section>
+ <h2>The <code>Metadata</code> interface</h2>
+ <p>
+ This interface supplies information about the state of a file or
+ directory.
+ </p>
+ <dl title='[NoInterfaceObject] interface Metadata' class='idl'>
+ <dt>readonly attribute Date modificationTime</dt>
+ <dd>
+ This is the time at which the file or directory was last modified.
+ </dd>
+ </dl>
+ </section>
+ <section>
+ <h2>The <code>Flags</code> interface</h2>
+ <p>
+ This interface is used to supply arguments to methods that look up or
+ create files or directories.
+ </p>
+ <dl title='[NoInterfaceObject] interface Metadata' class='idl'>
+ <dt>attribute boolean CREATE</dt>
+ <dd>
+ Used to indicate that the user wants to create a file or directory
+ if it was not previously there.
+ </dd>
+ <dt>attribute boolean EXCLUSIVE</dt>
+ <dd>
+ By itself, EXCLUSIVE MUST have no effect.
+ Used with CREATE, it causes getFile and getDirectory to fail if the
+ target path already exists.
+ </dd>
+ </dl>
+ <section class='informative'>
+ <h2>Examples</h2>
+ <pre class='example sh_javascript'>
+ // Get the data directory, creating it if it doesn't exist.
+ dataDir = fsSync.root.getDirectory("data", {CREATE: true});
+
+ // Create the lock file, if and only if it doesn't exist.
+ try {
+ lockFile = dataDir.getFile("lockfile.txt",
+ {CREATE: true, EXCLUSIVE: true});
+ } catch (ex) {
+ // It already exists, or something else went wrong.
+ ...
+ }
+ </pre>
+ </section>
+ </section>
+ </section>
+
+ <section>
<h2>The asynchronous filesystem interface</h2>
<section>
- <h2>The <code>Filesystem</code> interface</h2>
+ <h2>The <code>FileSystem</code> interface</h2>
<p>
This interface represents a file system.
</p>
- <dl title='[NoInterfaceObject] interface Filesystem' class='idl'>
+ <dl title='[NoInterfaceObject] interface FileSystem' class='idl'>
<dt>readonly attribute DOMString name</dt>
<dd>
This is the name of the file system. The specifics of naming
@@ -441,29 +476,23 @@
<p>
An abstract interface representing entries in a file system, each of
which may be a <a>File</a> or <a>DirectoryEntry</a>.
- <div class='issue'>
- Some have requested support for archive files. I've not required
- that, but I've left space for it by not ruling out having both
- isFile and isDirectory be true. I welcome comments on this
- approach.
- </div>
</p>
<dl title='[NoInterfaceObject] interface Entry' class='idl'>
- <dt>readonly attribute bool isFile</dt>
+ <dt>readonly attribute boolean isFile</dt>
<dd>
Entry is a file.
</dd>
- <dt>readonly attribute bool isDirectory</dt>
+ <dt>readonly attribute boolean isDirectory</dt>
<dd>
Entry is a directory.
</dd>
- <dt>void getModificationTime ()</dt>
+ <dt>void getMetadata ()</dt>
<dd>
<p>
- Look up when this entry was last modified.
+ Look up metadata about this entry.
</p>
<dl class='parameters'>
- <dt>DateCallback successCallback</dt>
+ <dt>MetadataCallback successCallback</dt>
<dd>
A callback that is called with the time of the last
modification.
@@ -484,7 +513,7 @@
<code>/</code> separated irrespective of the convention used by the
underlying file system.
</dd>
- <dt>readonly attribute Filesystem filesystem</dt>
+ <dt>readonly attribute FileSystem filesystem</dt>
<dd>
The file system on which the entry resides.
</dd>
@@ -544,19 +573,29 @@
</dd>
</dl>
</dd>
- <dt>DOMString toURI ()</dt>
+ <dt>DOMString toURI (optional DOMString mimeType)</dt>
<dd>
<p>
Returns a URI that can be used to identify this entry.
Unlike the URN defined in [[!FILE-API]], it has no specific
expiration; as it describes a location on disk, it should be valid
at least as long as that location exists.
+
+ Users may supply <code>mimeType</code> in order to simulate the
+ optional mime-type header associated with HTTP downloads.
</p>
+ <dl class='parameters'>
+ <dt>optional DOMString mimeType</dt>
+ <dd>
+ For a FileEntry, the mime type to be used to interpret the file,
+ when loaded through this URI.
+ </dd>
+ </dl>
<div class='issue'>
<p>
- We should probably spec out at least the URI format, if not the
- scheme as well, so that these can be edited and manipulated
- easily.
+ Do we want to spec out the URI format/scheme? It would be quite
+ nice if these could be edited and manipulated easily, as with
+ normal filesystem paths.
</p>
</div>
</dd>
@@ -602,17 +641,6 @@
</p>
<dl title='[NoInterfaceObject] interface DirectoryEntry : Entry'
class='idl'>
- <dt>const unsigned short CREATE = 1</dt>
- <dd>
- Used to indicate that the user wants to create a file or directory
- if it was not previously there.
- </dd>
- <dt>const unsigned short EXCLUSIVE = 2</dt>
- <dd>
- By itself, EXCLUSIVE MUST have no effect.
- Used with CREATE, it causes getFile and getDirectory to fail if the
- target path already exists.
- </dd>
<dt>DirectoryReader createReader ()</dt>
<dd>
<p>
@@ -627,21 +655,21 @@
<dl class='parameters'>
<dt>DOMString path</dt>
<dd>
- The relative path from this DirectoryEntry to the file to be
- looked up or created.
+ The <a>relative path</a> from this DirectoryEntry to the
+ file to be looked up or created. It is an error to attempt
+ to create a file whose immediate parent does not yet exist.
</dd>
- <dt>optional unsigned short options</dt>
+ <dt>optional Flags options</dt>
<dd>
<ul>
- <li>If CREATE and EXCLUSIVE are both specified [options is set
- to (CREATE|EXCLUSIVE)] and the path already exists,
- getFile MUST fail.</li>
- <li>If CREATE is specified, the path doesn't exist, and no
+ <li>If CREATE and EXCLUSIVE are both true, and the path
+ already exists, getFile MUST fail.</li>
+ <li>If CREATE is true, the path doesn't exist, and no
other error occurs, getFile MUST create it as a zero-length
file and return a corresponding FileEntry.</li>
- <li>If CREATE is not specified and the path doesn't exist,
+ <li>If CREATE is not true and the path doesn't exist,
getFile MUST fail.</li>
- <li>If CREATE is not specified and the path exists, but is a
+ <li>If CREATE is not true and the path exists, but is a
directory, getFile MUST fail.</li>
<li>Otherwise, if no other error occurs, getFile MUST
return a FileEntry corresponding to path.</li>
@@ -666,22 +694,21 @@
<dl class='parameters'>
<dt>DOMString path</dt>
<dd>
- The relative path from this DirectoryEntry to the directory to
- be looked up or created. It is an error to attempt to create a
- directory whose immediate parent does not yet exist.
+ The <a>relative path</a> from this DirectoryEntry to the
+ directory to be looked up or created. It is an error to attempt
+ to create a directory whose immediate parent does not yet exist.
</dd>
- <dt>optional unsigned short options</dt>
+ <dt>optional Flags options</dt>
<dd>
<ul>
- <li>If CREATE and EXCLUSIVE are both specified [options is set
- to (CREATE|EXCLUSIVE)] and the path already exists,
- getDirectory MUST fail.</li>
- <li>If CREATE is specified, the path doesn't exist, and no
+ <li>If CREATE and EXCLUSIVE are both true and the path already
+ exists, getDirectory MUST fail.</li>
+ <li>If CREATE is true, the path doesn't exist, and no
other error occurs, getDirectory MUST create and return
a corresponding DirectoryEntry.</li>
- <li>If CREATE is not specified and the path doesn't exist,
+ <li>If CREATE is not true and the path doesn't exist,
getDirectory MUST fail.</li>
- <li>If CREATE is not specified and the path exists, but is a
+ <li>If CREATE is not true and the path exists, but is a
file, getDirectory MUST fail.</li>
<li>Otherwise, if no other error occurs, getDirectory MUST
return a DirectoryEntry corresponding to path.</li>
@@ -766,20 +793,20 @@
Several calls in this API are asynchronous, and use callbacks.
</p>
<section>
- <h2>The <code>FilesystemsCallback</code> interface</h2>
+ <h2>The <code>FileSystemsCallback</code> interface</h2>
<p>
When <code>filesystems()</code> succeeds, the following callback is
made:
</p>
<dl title='[NoInterfaceObject, Callback=FunctionOnly] interface
- FilesystemsCallback' class='idl'>
+ FileSystemsCallback' class='idl'>
<dt>void handleEvent ()</dt>
<dd>
<p>
The list of file systems was successfully obtained.
</p>
<dl class='parameters'>
- <dt>Filesystem[] filesystems</dt>
+ <dt>FileSystem[] filesystems</dt>
<dd>
The array of file systems.
</dd>
@@ -789,21 +816,20 @@
</section>
<section>
- <h2>The <code>FilesystemCallback</code> interface</h2>
+ <h2>The <code>FileSystemCallback</code> interface</h2>
<p>
- When <code>requestTemporaryFilesystem()</code> or
- <code>requestPersistentFilesystem</code> succeeds, the following
+ When <code>requestFileSystem()</code> succeeds, the following
callback is made:
</p>
<dl title='[NoInterfaceObject, Callback=FunctionOnly] interface
- FilesystemsCallback' class='idl'>
+ FileSystemsCallback' class='idl'>
<dt>void handleEvent ()</dt>
<dd>
<p>
The file system was successfully obtained.
</p>
<dl class='parameters'>
- <dt>Filesystem filesystem</dt>
+ <dt>FileSystem filesystem</dt>
<dd>
The file systems to which the app is granted access.
</dd>
@@ -842,16 +868,18 @@
</section>
<section>
- <h2>The <code>DateCallback</code> interface</h2>
+ <h2>The <code>MetadataCallback</code> interface</h2>
<p>
- This interface is the callback used to look up timestamps.
+ This interface is the callback used to look up file and directory
+ metadata.
</p>
<dl title='[NoInterfaceObject, Callback=FunctionOnly] interface
- DateCallback' class='idl'>
- <dt>void handleEvent (Date date)</dt>
+ MetadataCallback' class='idl'>
+ <dt>void handleEvent (Metadata metadata)</dt>
<dd>
<p>
- Used to supply a Date as a response to a user query.
+ Used to supply file or directory metadata as a response to a
+ user query.
</p>
</dd>
</dl>
@@ -898,11 +926,11 @@
<section>
<h2>The synchronous filesystem interface</h2>
<section>
- <h2>The <code>FilesystemSync</code> interface</h2>
+ <h2>The <code>FileSystemSync</code> interface</h2>
<p>
This interface represents a file system.
</p>
- <dl title='[NoInterfaceObject] interface FilesystemSync' class='idl'>
+ <dl title='[NoInterfaceObject] interface FileSystemSync' class='idl'>
<dt>readonly attribute DOMString name</dt>
<dd>
This is the name of the file system. The specifics of naming
@@ -929,25 +957,25 @@
</div>
</p>
<dl title='[NoInterfaceObject] interface EntrySync' class='idl'>
- <dt>readonly attribute bool isFile</dt>
+ <dt>readonly attribute boolean isFile</dt>
<dd>
EntrySync is a file.
</dd>
- <dt>readonly attribute bool isDirectory</dt>
+ <dt>readonly attribute boolean isDirectory</dt>
<dd>
EntrySync is a directory.
</dd>
- <dt>Date getModificationTime ()</dt>
+ <dt>Metadata getMetadata ()</dt>
<dd>
<p>
- Look up when this entry was last modified.
+ Look up metadata about this entry.
</p>
<dl class='exception' title='FileException'>
<dt>NOT_FOUND_ERR</dt>
<dd>The entry no longer exists.</dd>
<dt>INVALID_STATE_ERR</dt>
- <dd>This FilesystemSync is no longer for some reason other than it
- having been deleted.</dd>
+ <dd>This FileSystemSync is no longer valid for some reason other
+ than it having been deleted.</dd>
<dt>SECURITY_ERR</dt>
<dd>The <a>user agent</a> determined that it was not safe to carry
out this action.</dd>
@@ -963,7 +991,7 @@
<code>/</code> separated irrespective of the convention used by the
underlying file system.
</dd>
- <dt>readonly attribute FilesystemSync filesystem</dt>
+ <dt>readonly attribute FileSystemSync filesystem</dt>
<dd>
The file system on which the entry resides.
</dd>
@@ -1042,19 +1070,31 @@
out this action.</dd>
</dl>
</dd>
- <dt>DOMString toURI ()</dt>
+ <dt>DOMString toURI (optional DOMString mimeType)</dt>
<dd>
<p>
Returns a URI that can be used to identify this entry.
Unlike the URN defined in [[!FILE-API]], it has no specific
expiration; as it describes a location on disk, it should be valid
at least as long as that location exists.
+
+ Users may supply <code>mimeType</code> in order to simulate the
+ optional mime-type header associated with HTTP downloads.
</p>
+ <dl class='parameters'>
+ <dt>optional DOMString mimeType</dt>
+ <dd>
+ For a FileEntry, the mime type to be used to interpret the file,
+ when loaded through this URI.
+ </dd>
+ </dl>
<div class='issue'>
<p>
- We should probably spec out at least the URI format, if not the
- scheme as well, so that these can be edited and manipulated
- easily.
+ If we use the same opaque URI scheme as in [[!FILE-API]], users
+ won't be able to edit and generate URIs themselves. On the other
+ hand, it would prevent us from having to go to all the trouble of
+ designing a new scheme, and it would simplify the use of the two
+ APIs together.
</p>
</div>
</dd>
@@ -1092,17 +1132,6 @@
</p>
<dl title='[NoInterfaceObject] interface DirectoryEntrySync : EntrySync'
class='idl'>
- <dt>const unsigned short CREATE = 1</dt>
- <dd>
- Used to indicate that the user wants to create a file or directory
- if it was not previously there.
- </dd>
- <dt>const unsigned short EXCLUSIVE = 2</dt>
- <dd>
- By itself, EXCLUSIVE MUST have no effect.
- Used with CREATE, it causes getFile and getDirectory to fail if the
- target path already exists.
- </dd>
<dt>DirectoryReaderSync createReader ()</dt>
<dd>
<p>
@@ -1125,21 +1154,21 @@
<dl class='parameters'>
<dt>DOMString path</dt>
<dd>
- The relative path from this DirectoryEntrySync to the file to be
- looked up or created.
+ The <a>relative path</a> from this DirectoryEntrySync to the
+ file to be looked up or created. It is an error to attempt
+ to create a directory whose immediate parent does not yet exist.
</dd>
<dt>optional unsigned short options</dt>
<dd>
<ul>
- <li>If CREATE and EXCLUSIVE are both specified [options is set
- to (CREATE|EXCLUSIVE) and the path already exists,
- getFile MUST fail.</li>
- <li>If CREATE is specified, the path doesn't exist, and no
+ <li>If CREATE and EXCLUSIVE are both true and the path
+ already exists, getFile MUST fail.</li>
+ <li>If CREATE is true, the path doesn't exist, and no
other error occurs, getFile MUST create it as a zero-length
file and return a corresponding FileEntry.</li>
- <li>If CREATE is not specified and the path doesn't exist,
+ <li>If CREATE is not true and the path doesn't exist,
getFile MUST fail.</li>
- <li>If CREATE is not specified and the path exists, but is a
+ <li>If CREATE is not true and the path exists, but is a
directory, getFile MUST fail.</li>
<li>Otherwise, if no other error occurs, getFile MUST
return a FileEntrySync corresponding to path.</li>
@@ -1173,22 +1202,21 @@
<dl class='parameters'>
<dt>DOMString path</dt>
<dd>
- The relative path from this DirectoryEntrySync to the directory
- to be looked up or created. It is an error to attempt to create
- a directory whose immediate parent does not yet exist.
+ The <a>relative path</a> from this DirectoryEntrySync to the
+ directory to be looked up or created. It is an error to attempt
+ to create a directory whose immediate parent does not yet exist.
</dd>
<dt>optional unsigned short options</dt>
<dd>
<ul>
- <li>If CREATE and EXCLUSIVE are both specified [options is set
- to (CREATE|EXCLUSIVE) and the path already exists,
- getDirectory MUST fail.</li>
- <li>If CREATE is specified, the path doesn't exist, and no
+ <li>If CREATE and EXCLUSIVE are both true and the path already
+ exists, getDirectory MUST fail.</li>
+ <li>If CREATE is true, the path doesn't exist, and no
other error occurs, getDirectory MUST create and return
a corresponding DirectoryEntry.</li>
- <li>If CREATE is not specified and the path doesn't exist,
+ <li>If CREATE is not true and the path doesn't exist,
getDirectory MUST fail.</li>
- <li>If CREATE is not specified and the path exists, but is a
+ <li>If CREATE is not true and the path exists, but is a
file, getDirectory MUST fail.</li>
<li>Otherwise, if no other error occurs, getDirectory MUST
return a DirectoryEntrySync corresponding to path.</li>
@@ -1491,24 +1519,41 @@
<p>
Case-insensitivity SHOULD respect the locale of the user.
</p>
+ <div class='issue'>
+ We could choose the user or the author; I think the user's probably
+ the better way to go. There are still situations in which you can get
+ into trouble, but matching the locale of the user's computer should
+ avoid many of the most common conflicts.
+ </div>
</section>
<section>
<h2>Directories</h2>
<p>
+ A <dfn>relative path</dfn> describes how to get from a particular
+ directory to a file or directory. All paths presented to this API are
+ relative paths. All methods that accept paths are on
+ <a>DirectoryEntry</a> or <a>DirectoryEntrySync</a> objects; the paths
+ are interpreted as being relative to the directories represented by
+ these objects.
+ </p>
+ <p>
+ As all paths are relative, paths MUST NOT start with '/'.
+ </p>
+ <p>
The directory separator is '/', regardless of the directory separator
used by the underlying system, if any.
</p>
<p>
'.', when used where it is legal to use a directory name, refers to the
- current directory. Thus 'foo/./bar' is equivalent to 'foo/bar', and
- './foo' is equivalent to 'foo'.
+ currently-referenced directory. Thus 'foo/./bar' is equivalent to
+ 'foo/bar', and './foo' is equivalent to 'foo'.
</p>
<p>
'..', when used where it is legal to use a directory name, refers to the
- parent of the current directory. Thus, 'foo/..' refers to the directory
- containing 'foo', and '../foo' refers to an element named 'foo' in the
- parent of the directory on whose DirectoryEntry or DirectoryEntrySync
- the method receiving the path is being called.
+ parent of the currently-referenced directory. Thus, 'foo/..' refers to
+ the directory containing 'foo', and '../foo' refers to an element named
+ 'foo' in the parent of the directory on whose DirectoryEntry or
+ DirectoryEntrySync the method receiving the path is being called.
</p>
<p>
Directories MUST NOT be made to contain more than 5000 entries.
@@ -1567,14 +1612,6 @@
</p>
</section>
</section>
- <section class='informative'>
- <h2>Use Cases</h2>
- <div class='issue'>
- TODO; I'll pull these out of the various emails on the relevant mailing
- lists soon. Here's <a
- href="http://lists.w3.org/Archives/Public/public-webapps/2009OctDec/0424.html">one</a>.
- </div>
- </section>
<section class='appendix'>
<h2>Acknowledgements</h2>
<p>
Received on Thursday, 8 July 2010 00:52:21 UTC