1. Goals
This specification documents the types and operations made available by web browsers to script when a hierarchy of files and directories are dragged and dropped onto a page or selected using form elements, or equivalent user actions.
This is heavily based upon earlier drafts of [file-system-api] which defines similar types in the context of a sandboxed file system, including operations for creating and modifying files and directories, but which has not been broadly adopted by web browsers.
2. Concepts
2.1. Names and Paths
A name is a string which:
-
does not contain '/' (U+002F SOLIDUS)
-
does not contain NUL (U+0000)
-
does not contain '\' (U+005C REVERSE SOLIDUS)
-
is not '.' (U+002E FULL STOP)
-
is not '..' (U+002E FULL STOP, U+002E FULL STOP)
A path segment is a name, '.' (U+002E FULL STOP) or '..' (U+002E FULL STOP, U+002E FULL STOP).
A relative path is a string consisting of one or more path segments joined by '/' (U+002F SOLIDUS) that does not start with '/' (U+002F SOLIDUS).
An absolute path is a string consisting of '/' (U+002F SOLIDUS) followed by zero or more path segments joined by '/' (U+002F SOLIDUS).
A path is either a relative path or an absolute path.
A valid path is a USVString
which is a path.
2.2. Files and Directories
A file consists of binary data and a name (a non-empty name).
A directory consists of a name (a name) and an ordered list of members. Each member is either a file or a directory. Each member of a directory must have a distinct non-empty name.
A root directory is a directory that is not a member of a directory. A root directory's name is empty.
The parent of a file or directory is the directory it is a member of. A root directory has no parent.
A file system consists of a name and a root which is an associated root
directory. The name of a file system is a USVString
which is implementation defined but is unique to the file system. A root directory is associated with exactly one file system.
2.3. Entries
An entry is either a file entry or a directory entry.
An entry has an name (a name) and a full path (an absolute path).
An entry also has a root, which is an associated root directory.
The file system of an entry is the file system associated with the entry's root.
2.4. Directory Reader
A directory reader consists of an associated directory entry, an associated directory (initially null), a reading flag (initially unset), a done flag (initially unset), and a reader error (initially null).
3. Algorithms
To resolve a relative path with abspath (an absolute path) and path (an absolute path, a relative path, or the empty string), run the following steps which return an absolute path:
-
If path is an absolute path, return path.
-
Let abspath segments be the result of strictly splitting abspath on '/' (U+002F SOLIDUS).
-
Let path segments be the result of strictly splitting path on '/' (U+002F SOLIDUS).
-
For each segment in path segments, switch on segment:
- empty string
- Continue.
- '.' (U+002E FULL STOP)
- Continue.
- '..' (U+002E FULL STOP, U+002E FULL STOP)
- Remove the last member of abspath segments unless it is the only member.
- Otherwise
- Append segment to abspath segments.
-
Return abspath segments joined by '/' (U+002F SOLIDUS).
To evaluate a path with directory (an root directory) and path (an absolute path), run the following steps which return a file, directory, or failure.
-
Let segments be the result of strictly splitting path on '/' (U+002F SOLIDUS).
-
Remove the first entry from segments.
-
For each segment in segments, switch on segment:
- empty string
- Continue.
- '.' (U+002E FULL STOP)
- Continue.
- '..' (U+002E FULL STOP, U+002E FULL STOP)
- Let directory be directory’s parent, or directory if none.
- Otherwise
- Run these substeps:
4. The File
Interface
partial interface File {readonly attribute USVString ; };
webkitRelativePath
The webkitRelativePath
attribute of the File
interface
must return the relative path of the file, or the empty string if
not specified.
5. HTML: Forms
partial interface HTMLInputElement {attribute boolean ;
webkitdirectory readonly attribute FrozenArray <FileSystemEntry >; };
webkitEntries
When an input
element’s type
attribute is in the File
Upload state, the rules in this section apply.
The webkitdirectory
attribute is a boolean
attribute that indicates whether the user is to be allowed to select a
directory rather than a file or files. When specified, the behavior on
the selection of a directory is as if all files with that directory as
an ancestor were selected. In addition, the webkitRelativePath
property of each File
is set to a relative path starting from (and including) the selected directory
to the file.
The webkitEntries
IDL attribute allows scripts to
access the element’s selected entries. On getting, if the IDL
attribute applies, it must return an array of FileSystemEntry
objects that represent the current selected files (including
directories, if permitted). If the IDL attribute does not apply, then
it must instead return null.
6. HTML: Drag and drop
During a drag-and-drop operation, file and directory items are associated with entries. Each entry is a member of a root directory unique to the drag data store.
Additionally, each directory item is represented in the drag
data store item list as a File. If it is accessed via getAsFile()
a zero-length File
is returned.
partial interface DataTransferItem {FileSystemEntry ?(); };
webkitGetAsEntry
The webkitGetAsEntry()
method must run the
following steps when invoked:
-
If the
DataTransferItem
object is not in the read/write mode or the read-only mode, return null and abort these steps. -
If the drag data item kind is not File, then return null and abort these steps.
-
Return a new
FileSystemEntry
object representing the entry.
7. Files and Directories
callback =
ErrorCallback void (DOMException );
err
An ErrorCallback
function is used for operations that may return an
error asynchronously.
7.1. The FileSystemEntry
Interface
interface {
FileSystemEntry readonly attribute boolean ;
isFile readonly attribute boolean ;
isDirectory readonly attribute USVString ;
name readonly attribute USVString ;
fullPath readonly attribute FileSystem ;
filesystem void getParent (optional FileSystemEntryCallback ,
successCallback optional ErrorCallback ); };
errorCallback
An FileSystemEntry
has an associated entry.
The isFile
attribute of the FileSystemEntry
interface must return true if the entry is a file entry and
false otherwise.
The isDirectory
attribute of the FileSystemEntry
interface must return true if the entry is a directory entry and false otherwise.
The name
attribute of the FileSystemEntry
interface must return the name of the entry.
The fullPath
attribute of the FileSystemEntry
interface must return the full path of the entry.
The filesystem
attribute of the FileSystemEntry
interface must return the file system of
the entry.
The getParent(successCallback, errorCallback)
method, when invoked, must run the following
steps:
-
Queue a task to perform the following substeps:
-
Let path be the result of running the steps to resolve a relative path with the entry's full path and '..'.
-
Let item be the result of running the steps to evaluate a path with the entry's root and path.
-
If item is failure, invoke errorCallback (if given) with a newly created "
NotFoundError
"DOMException
, and terminate these steps. -
Let entry be a new directory entry with item’s name as name and path as full path.
-
Invoke successCallback with a new
FileSystemDirectoryEntry
object associated with entry.
-
7.2. The FileSystemDirectoryEntry
Interface
interface :
FileSystemDirectoryEntry FileSystemEntry {FileSystemDirectoryReader createReader ();void getFile (optional USVString ?,
path optional FileSystemFlags ,
options optional FileSystemEntryCallback ,
successCallback optional ErrorCallback );
errorCallback void getDirectory (optional USVString ?,
path optional FileSystemFlags ,
options optional FileSystemEntryCallback ,
successCallback optional ErrorCallback ); };
errorCallback dictionary {
FileSystemFlags boolean =
create false ;boolean =
exclusive false ; };callback =
FileSystemEntryCallback void (FileSystemEntry );
entry
A FileSystemDirectoryEntry
's associated entry is a directory
entry.
The createReader()
method, when invoked, must run the following steps:
-
Let reader be a new directory reader associated with the directory entry's directory.
-
Return a newly created
FileSystemDirectoryReader
object associated with reader.
The getFile(path, options, successCallback, errorCallback)
method, when
invoked, must run the following steps:
-
Queue a task to run the following substeps:
-
If path is undefined or null let path be the empty string.
-
If path is not a valid path, invoke errorCallback (if given) with a newly created "
TypeMismatchError
"DOMException
, and terminate these steps. -
If options’s
create
member is true, invoke errorCallback (if given) with a newly created "SecurityError
"DOMException
, and terminate these steps. -
Let path be the result of running the steps to resolve a relative path with the directory entry's full path and path.
-
Let item be the result of running the steps to evaluate a path with the directory entry's root and path.
-
If item is failure, invoke errorCallback (if given) with a newly created "
NotFoundError
"DOMException
, and terminate these steps. -
If item is not a file, invoke errorCallback (if given) with a newly created "
TypeMismatchError
"DOMException
, and terminate these steps. -
Let entry be a new file entry with item’s name as name and path as full path.
-
Invoke successCallback (if given) with a new
FileSystemFileEntry
object associated with entry.
-
The getDirectory(path, options, successCallback, errorCallback)
method, when
invoked, must run the following steps:
-
Queue a task to run the following substeps:
-
If path is undefined or null let path be the empty string.
-
If path is not a valid path, invoke errorCallback (if given) with a newly created "
TypeMismatchError
"DOMException
, and terminate these steps. -
If options’s
create
member is true, invoke errorCallback (if given) with a newly created "SecurityError
"DOMException
, and terminate these steps. -
Let path be the result of running the steps to resolve a relative path with the directory entry's full path and path.
-
Let item be the result of running the steps to evaluate a path with the directory entry's root and path.
-
If item is failure, invoke errorCallback (if given) with a newly created "
NotFoundError
"DOMException
, and terminate these steps. -
If item is not a directory, invoke errorCallback (if given) with a newly created "
TypeMismatchError
"DOMException
, and terminate these steps. -
Let entry be a new directory entry with item’s name as name and path as full path.
-
invoke successCallback (if given) with a new
FileSystemDirectoryEntry
associated with entry.
-
7.3. The FileSystemDirectoryReader
Interface
interface {
FileSystemDirectoryReader void (
readEntries FileSystemEntriesCallback ,
successCallback optional ErrorCallback ); };
errorCallback callback =
FileSystemEntriesCallback void (sequence <FileSystemEntry >);
entries
A FileSystemDirectoryReader
has an associated directory reader.
The readEntries(successCallback, errorCallback)
method, when invoked, must run the following
steps:
-
If the directory reader's reading flag is set, queue a task to invoke errorCallback with a newly created "
InvalidStateError
"DOMException
, and terminate these steps. -
If the directory reader's reader error is not null, queue a task to invoke errorCallback (if given) with reader error, and terminate these steps.
-
If the directory reader's done flag is set, queue a task to invoke successCallback with an empty sequence and terminate these steps.
-
Set the directory reader's reading flag.
-
Queue a task to perform the following substeps:
-
Clear the directory reader's reading flag.
-
Let dir be the directory reader's directory.
-
If dir is null, run these substeps:
-
Let dir be the result of running the steps to evaluate a path with the entry's root and full path.
-
If dir is failure, set the directory reader's reader error to a newly created "
NotFoundError
"DOMException
, invoke errorCallback (if given) with reader error, and terminate these steps. -
Set the directory reader's directory to dir.
-
-
Let entries be a non-zero number of entries from the dir that have not yet been produced by this directory reader, if any.
-
If the previous step failed (for example, the directory was deleted or permission is denied), then set the directory reader's reader error to an appropriate
DOMException
, invoke errorCallback (if given) with reader error, and terminate these steps. -
If entries is empty, set the directory reader's done flag.
-
invoke successCallback with entries.
-
7.4. The FileSystemFileEntry
Interface
interface :
FileSystemFileEntry FileSystemEntry {void file (FileCallback ,
successCallback optional ErrorCallback ); };
errorCallback callback =
FileCallback void (File );
file
A FileSystemFileEntry
's associated entry is a file entry.
The file(successCallback, errorCallback)
method, when invoked, must run the following
steps:
-
Queue a task to perform the following substeps:
-
Let item be the result of running the steps to evaluate a path with the file entry's root and full path.
-
If item is failure, invoke errorCallback (if given) with a newly created "
NotFoundError
"DOMException
, and terminate these steps. -
If item is a directory, invoke errorCallback (if given) with a newly created "
TypeMismatchError
"DOMException
, and terminate these steps. -
invoke successCallback with a new
File
object representing item.
-
7.5. The FileSystem
Interface
interface {
FileSystem readonly attribute USVString ;
name readonly attribute FileSystemDirectoryEntry ; };
root
A FileSystem
has an associated file system.
The name
attribute of the FileSystem
interface must return the name of the file system.
The root
attribute of the FileSystem
interface must
return a FileSystemDirectoryEntry
associated with the root of the file system.
8. Acknowledgements
This specification is based heavily on the work of Eric Uhrhane in [file-system-api], which introduced the FileSystemEntry
types.
Thanks to Tab Atkins, Jr. for creating and maintaining Bikeshed, the specification authoring tool used to create this document.
And thanks to Ali Alabbas, Philip Jägenstedt, Marijn Kruisselbrink, Olli Pettay, and Kent Tamura for suggestions, reviews, and other feedback.