- From: Robin Berjon via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 09 Dec 2009 18:08:19 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/file-system
In directory hutz:/tmp/cvs-serv27945
Added Files:
file-dir-sys.html
Removed Files:
Overview.html
Log Message:
very rough early draft of Directory
--- NEW FILE: file-dir-sys.html ---
<!DOCTYPE html>
<html>
<head>
<title>File API: Directories and System</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
<script src='../ReSpec.js/js/respec.js' class='remove'></script>
<script class='remove'>
var respecConfig = {
specStatus: "ED",
shortName: "file-dir-sys-api",
// publishDate: "2009-08-06",
// previousPublishDate: "1977-03-15",
edDraftURI: "http://dev.w3.org/2009/dap/file-system/file-dir-sys.html",
// lcEnd: "2009-08-05",
noIDLIn: true,
editors: [
{ name: "Robin Berjon",
url: "http://berjon.com/",
company: "Vodafone",
companyURL: "http://vodafone.com/" },
],
};
</script>
<script src='../common/config.js' class='remove'></script>
</head>
<body>
<section id='abstract'>
This specification defines an <acronym title='Application Programming Interface'>API</acronym>
to navigate file system hierarchies.
<!--
XXX
explain how it fits with File API and Writer
-->
</section>
<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 contains.
</p>
<div class='issue'>
<p>
If different user agents obtain navigators in different ways we will need
to add more classes, or some way to handle the variability.
</p>
</div>
</section>
<section class='informative'>
<h2>Introduction</h2>
<p>
...
</p>
<section>
<h2>Examples</h2>
<pre class='example sh_javascript'>
...
</pre>
</section>
</section>
<section>
<h2>Obtaining access to file system entry points</h2>
<p>
There are several ways in which a file system entry point can be obtained. Not all <a>user agents</a>
may in fact implement all of them.
</p>
<section class='informative'>
<h2>Security Considerations</h2>
<div class='issue'>
<p>
These are just preliminary notes (like much of the rest of this API).
</p>
<p>
It is obviously dangerous to let browsers provide access to the user's real FS, and should
only be done in trusted application.
</p>
<p>
The virtual <code>localFS</code> should have a quota. It also shouldn't be implemented by storing its
contents directly to the disk (even hidden inside a supposedly hard to find profile directory) as a user
could find such content by chance (for instance through a search) or just by being nosy, and the files
contained therein could potentially be extremely dangerous. Rather, the virtual file systems should be
hidden from normal access by the user. A simple example of an implementation strategy would be to use
a typical archive format (e.g. Zip) without its expected file extension.
</p>
</div>
</section>
<section>
<h2>Requesting navigators 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>
<p class='issue'>
This is missing a way to be notified of FSs being mounted or unmounted.
</p>
<div class='idl' title='Device implements DeviceFS'></div>
<dl title='[Supplemental, NoInterfaceObject] interface DeviceFS' class='idl'>
<dt>PendingOp fileSystems ()</dt>
<dd>
<p>
Requests a list of file systems available on the device.
</p>
<dl class='parameters'>
<dt>FileSystemsCB successCB</dt>
<dd>
The callback that is called when the user agent provides a list of available file
systems.
</dd>
<dt>optional ErrorCB errCB</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>
</dl>
</section>
<section>
<h2>Using <code>localFS</code></h2>
<div class='idl' title='Window implements WindowLocalFS'></div>
<dl title='[Supplemental, NoInterfaceObject] interface WindowLocalFS' class='idl'>
<dt>readonly attribute Directory localFS</dt>
<dd>
The root directory of the virtual file system.
</dd>
</dl>
<div class='issue'>
<p>
A number of things need to be copied from WebStorage's localStorage.
</p>
<p>
Obvious this is subject to the same authorisation process as localStorage, quotas, etc.
</p>
</div>
<p>
The <code>localFS</code> attribute points to a <a>Directory</a> object that is the root
of the file system (its <code>parent</code> is <code>null</code>). Its owner <a>FileSystem</a>
has a <code>name</code> of "localFS", and has both <code>caseSensitive</code> and
<code>casePreserving</code> set to <code>true</code>.
</p>
</section>
</section>
<section>
<h2>The <code>FileSystem</code> interface</h2>
<p>
This interface represents a file system.
</p>
<dl title='[NoInterfaceObject] interface FileSystem' class='idl'>
<dt>readonly attribute DOMString name</dt>
<dd>
The name of the file system. Implementation-dependent but required to be unique
across the list of exposed file systems.
</dd>
<dt>readonly attribute Directory root</dt>
<dd>
The root directory of the file system.
</dd>
<dt>readonly attribute boolean caseSensitive</dt>
<dd>
Whether the file system is sensitive to case or not.
</dd>
<dt>readonly attribute boolean casePreserving</dt>
<dd>
Whether the file system preserves case information or not.
</dd>
<dt>Entry resolveURI ()</dt>
<dd>
<p>
Given a URI, will return an <a>Entry</a> in the <a>FileSystem</a> if one exists that
matches, <code>null</code> otherwise.
</p>
<p class='note'>
There is no requirement for the URI to be a <code>file</code> URI. For instance, if the
file system is a WebDAV system it may be an HTTP URI.
</p>
<dl class='parameters'>
<dt>DOMString uri</dt>
<dd>
The URI to resolve.
</dd>
</dl>
</dd>
</dl>
</section>
<section>
<h2>The <code>Entry</code> interface</h2>
<p>
An abstract interface representing entries in a file system each of which may be
a <a>File</a> or <a>Directory</a>.
</p>
<dl title='[NoInterfaceObject] interface Entry' class='idl'>
<dt>const unsigned short DIRECTORY = 1</dt>
<dd>
Entry is a directory.
</dd>
<dt>const unsigned short FILE = 2</dt>
<dd>
Entry is a file.
</dd>
<dt>readonly attribute unsigned short type</dt>
<dd>
The type of the entry.
</dd>
<dt>readonly attribute DOMString name</dt>
<dd>
The name of the entry, excluding the path leading to it.
</dd>
<dt>readonly attribute DOMString fullPath</dt>
<dd>
The full path from the root to the entry. Paths are always <code>/</code> separated
irrespective of the convention used by the underlying file system.
</dd>
<dt>readonly attribute Directory? parent</dt>
<dd>
The parent of the entry. If the entry is the root directory, then this is null.
</dd>
<dt>readonly attribute FileSystem fileSystem</dt>
<dd>
The file system on which the entry resides.
</dd>
<dt>Entry moveTo ()</dt>
<dd>
<p>
Move an entry to a different location on the file system. It is an error to try to move
an entry inside itself at any depth if it is a directory, or to move it into its parent
if a name different from its current one isn't provided.
</p>
<dl class='parameters'>
<dt>Directory parent</dt>
<dd>
The directory to which to move the entry.
</dd>
<dt>optional DOMString newName</dt>
<dd>
The new name of the entry. Defaults to its current one if unspecified.
</dd>
</dl>
</dd>
<dt>Entry copyTo (Directory parent, DOMString newName)</dt>
<dd>
<p>
Copy an entry to a different location on the file system. It is an error to try to copy
an entry inside itself at any depth if it is a directory, or to copy it into its parent
if a name different from its current one isn't provided.
</p>
<dl class='parameters'>
<dt>Directory parent</dt>
<dd>
The directory to which to move the entry.
</dd>
<dt>optional DOMString newName</dt>
<dd>
The new name of the entry. Defaults to its current one if unspecified.
</dd>
</dl>
</dd>
<dt>DOMString toURI ()</dt>
<dd>
<p>
Returns a URI that can be used to reference this entry.
</p>
</dd>
</dl>
</section>
<section>
<h2>The <code>Directory</code> interface</h2>
<p>
This interface represents a directory on a file system.
</p>
<dl title='[NoInterfaceObject] interface Directory : Entry' class='idl'>
<dt>readonly attribute Entry[] entries</dt>
<dd>
An array of entries contained in this directory.
</dd>
<dt>FileEntry file ()</dt>
<dd>
<p>
Creates a new empty file. It is an error to create a file with a name that already exists in
the list of entries.
</p>
<dl class='parameters'>
<dt>DOMString name</dt>
<dd>
The name of the file to create.
</dd>
<dt>optional DOMString mediaType</dt>
<dd>
The media type of the file to create.
</dd>
</dl>
</dd>
<dt>Directory directory ()</dt>
<dd>
<p>
Creates a new empty directory. It is an error to create a directory with a name that already exists in
the list of entries.
</p>
<dl class='parameters'>
<dt>DOMString name</dt>
<dd>
The name of the directory to create.
</dd>
</dl>
</dd>
<dt>void remove ()</dt>
<dd>
<p>
Remove this directory. It is an error to remove a directory if <code>recurse</code> isn't
specified and it is not empty.
</p>
<dl class='parameters'>
<dt>optional boolean recurse</dt>
<dd>
Whether to recursively remove the contents of directory. Defaults to <code>false</code>.
</dd>
</dl>
</dd>
</dl>
<dt>Blob zip ()</dt>
<dd>
<p>
Returns a blob that contains a Zip archive of the directory's content. This blob can then be
saved to a file (e.g. as a widget).
</p>
<dl class='parameters'>
<dt>optional boolean compression</dt>
<dd>
Whether the contents of the directory should be compressed or simply stored in the Zip
archive. Defaults to <code>true</code>.
</dd>
<dt>optional boolean includeSelf</dt>
<dd>
Whether the root of the Zip archive will contain the directory, or directly its content.
Defaults to <code>true</code>.
</dd>
</dl>
</dd>
</section>
<section>
<h2>The <code>FileEntry</code> interface</h2>
<p>
This interface represents a file on a file system.
</p>
<dl title='[NoInterfaceObject] interface FileEntry : Entry' class='idl'>
<dt>WritableBlob blob ()</dt>
<dd>
<p>
Returns a blob representing the content of the file. This can be read using <code>FileReader</code>
and written to using <code>FileWriter</code>.
</p>
</dd>
<dt>PendingOp save ()</dt>
<dd>
<p>
Saves a blob to the file, making it its current content. Note that implementation may track changes
made to the blob and only modify the file based on those changes rather than overwriting it entirely.
</p>
<dl class='parameters'>
<dt>Blob blob</dt>
<dd>
The data to save.
</dd>
<dt>SaveCB successCB</dt>
<dd>
A callback indicating that the save was successful.
</dd>
<dt>optional ErrorCB errorCB</dt>
<dd>
A callback indicating that there was an error saving the content to file.
</dd>
</dl>
</dd>
<dt>PendingOp save ()</dt>
<dd>
<p>
Saves text to the file, making it its current content.
</p>
<dl class='parameters'>
<dt>DOMString text</dt>
<dd>
The text to save to the file.
</dd>
<dt>SaveCB successCB</dt>
<dd>
A callback indicating that the save was successful.
</dd>
<dt>optional ErrorCB errorCB</dt>
<dd>
A callback indicating that there was an error saving the content to file.
</dd>
<dt>optional DOMString encoding</dt>
<dd>
The desired encoding for saving to the file. Defaults to "UTF-8".
</dd>
<dt>optional DOMString endings</dt>
<dd>
The desired line ending handling for the file. Defaults to <code>transparent</code>.
</dd>
</dl>
</dd>
<dt>void remove ()</dt>
<dd>
<p>
Removes this file from the file system.
</p>
</dd>
</dl>
</section>
<section>
<h2>Callbacks</h2>
<p>
Several calls in this API are asynchronous, and use callbacks.
</p>
<section>
<h2>The <code>FileSystemsCB</code> interface</h2>
<p>
When <code>fileSystems()</code> succeeds, the following callback is made:
</p>
<dl title='[NoInterfaceObject, Callback=FunctionOnly] interface FileSystemsCB' class='idl'>
<dt>void onSuccess ()</dt>
<dd>
<p>
The list of file systems was successfully obtained.
</p>
<dl class='parameters'>
<dt>FileSystem[] fileSystems</dt>
<dd>
The array of file systems.
</dd>
</dl>
</dd>
</dl>
</section>
<section>
<h2>The <code>SaveCB</code> interface</h2>
<p>
When <code>save()</code> succeeds, the following callback is made:
</p>
<dl title='[NoInterfaceObject, Callback=FunctionOnly] interface SaveCB' class='idl'>
<dt>void onSuccess ()</dt>
<dd>
<p>
The file was successfully saved.
</p>
</dd>
</dl>
</section>
<section>
<h2>The <code>ErrorCB</code> interface</h2>
<p>
When an error occurs, the following callback is made:
</p>
<dl title='[NoInterfaceObject, Callback=FunctionOnly] interface ErrorCB' class='idl'>
<dt>void onError ()</dt>
<dd>
<p>
There was an error with the request. Details are provided by the <a>FSError</a>
parameter.
</p>
<dl class='parameters'>
<dt>FSError err</dt>
<dd>
The error that was generated.
</dd>
</dl>
</dd>
</dl>
</section>
<section>
<h2>The <code>FSError</code> interface</h2>
<p>
The error is defined as follows:
</p>
<dl title='[NoInterfaceObject] interface FSError' class='idl'>
<dt>const unsigned short DENIED_ERR = 1</dt>
<dd>
The request to was denied.
</dd>
<dt>readonly attribute unsigned short code</dt>
<dd>
The code specifying the type of this error.
</dd>
</dl>
</section>
</section>
</section>
<section class='appendix'>
<h2>Acknowledgements</h2>
<p>
Many thanks to OMTP BONDI who provided input for this API, based on an initial effort by Opera,
and to Arun for his excellent work on the File API.
</p>
</section>
</body>
</html>
--- Overview.html DELETED ---
Received on Wednesday, 9 December 2009 18:08:29 UTC