Copyright © 2008 Opera Software ASA. All rights reserved.
This document is a proposal from Opera Software, submitted to the WebAPI working group as a proposed base for the work item currently called "file upload API". In the event of this draft being accepted as a basis for the Working Group drafts, Opera Software will offer Copyright and any other Intellectual Property Rights in accordance with standard practice under the W3C's Royalty-Free Patent Policy.
This document describes an interface for an abstract File I/O interface
where web applications can interact with a file system, without any prior
knowledge about the underlying filesystem. This interface can be used for
e.g. an image preview before submitting a form or for saving a drawing from a
canvas painting web application locally.
Traditionally, web applications have had little to no access to resources residing on the local filesystem. The ECMAScript interfaces for file I/O specifies a sandboxed file system, where a widget or other trusted component can gain access to the local file system.
The File I/O interfaces in this specification represent an abstract filesystem, without knowledge of the underlying filesystem's path separators, conventions for setting file properties such as read/write permissions.
The interfaces provide methods for opening files, writing to them, creating files and directories, moving or deleting them, and so forth.
There are several known issues in this specification. The usage of RFC2119 terminology needs to be tighter, processing requirements are not properly defined everywhere, exceptions are poorly handled at the moment, some terms are used but not defined, and so forth.
In order to work with files, an application first has to acquire a mountpoint. A mountpoint is either a reference to a file or folder on a disk, or an abstract reference to a set of files which might not necessarily be within the same folder.
FileSystem
interfaceIn a context where the FileSystem interface is
made available to applications, the interface is instantiated as
opera.io.filesystem. When present, this object provides
attributes and methods for acquiring access to files and folders on the local
filesystem.
interface FileSystem {
readonly attribute File mountPoints;
File mountSystemDirectory(in DOMString location);
File mountSystemDirectory(in DOMString location,
in DOMString name);
void removeMountPoint(in File mountpoint);
void removeMountPoint(in DOMString name);
void browseForDirectory(in DOMString name,
in DOMString defaultLocation,
in function callback);
void browseForDirectory(in DOMString name,
in DOMString defaultLocation,
in function callback,
in Boolean persistent);
void browseForFile(in DOMString name,
in DOMString defaultLocation,
in function callback);
void browseForFile(in DOMString name,
in DOMString defaultLocation,
in function callback,
in Boolean persistent);
void browseForFile(in DOMString name,
in DOMString defaultLocation,
in function callback,
in Boolean persistent,
in Boolean multiple);
void browseForSave(in DOMString filename,
in DOMString defaultLocation,
in function callback,
in Boolean persistent);
}FileSystem
attributes and methodsmountPoints
attribute of type File, readonlyThe mountPoints attribute, of type
File is a file object that contains a collection of
File objects representing the other currently
mounted directories.
mountSystemDirectory() methodThe mountSystemDirectory() method is used to
mount predefined directories that the application should normally have access
to, such as the application folder, or the application's private storage
folder.
The mountSystemDirectory() method takes a
DOMString argument, location, which expresses the location of the
system directory. Additionally, an optional name argument may be
specified, which will correspond to the
mountpoint_name of a mountpoint protocol URL. If
this argument is missing, it is assumed to be present, with the same value as
the location argument.
If the mountSystemDirectory() method is called,
and it does not specify a valid mountpoint, the call to the method will result
in no action, and the return value will be null. When the
function is called, and its call results in a valid mountpoint being created,
the function returns a reference to the newly mounted file object.
removeMountPoint() methodThe removeMountPoint method takes a
File argument of an object which is a
mountpoint or a DOMString with the name of a mountpoint. When
called, the user agent must mark the mountpoint as not persistent,
must remove the mountpoint from the list of mountpoints, and must
finally return nothing.
If the mountpoint being removed is not a current
mountpoint, a general error is thrown. (A more sane exception
should be implemented)
browseForDirectory() methodThe browseForDirectory() is used to acquire
access to a sandboxed file system resource on the user's system. When invoked,
the method should present the user with a directory chooser dialog.
On implementations where the user-visible file system representation consists
of a single folder, and implementation may just display a
confirmation dialog asking the user whether the user wants to allow
access.
The first argument to browseForDirectory() is a
DOMString with the desired name of the mountpoint. This argument
will correspond to the mountpoint_name of a
mountpoint protocol URL. If the type of the argument is wrong, or the value of
the string specified is not permissible as a name for a mountpoint, a generic
error is thrown.
The second argument to browseForDirectory() is a
DOMString representing the default location in which the dialog should start.
The locations themselves are case-insensitive strings such as 'Photos',
'Documents', 'Music', 'Images', but other, system-specific strings may also
exist. In the case that the string specified is not supported by the system,
the browseForDirectory() method is expected to start
in what corresponds to the user's home directory, or last directory, depending
on the conventions of the operating system the application is running.
The third argument to browseForDirectory(), a
function, must called when the user has successfully navigated to a
directory, and selected/approved the folder selection. This function is called
with the newly acquired mountpoint represented as a
File object. In the case that a user cancels the
dialog, the callback is called, but the argument to the function
should be null.
The last argument to browseForDirectory is a
Boolean argument determining whether the mountpoint is to be
made persistent across restarts of the application. If this argument is
missing, it is assumed to be present, with a default value of
false. If the argument is true then the
File object must be marked as persistent.
A call to browseForDirectory() should be
ignored if the call does not happen as a direct result of direct user
interaction. User interaction is defined as being any non-synthetic click,
mousedown, mouseup or key event, similar to how a heuristic pop-up blocker
prohibits opening popups except when as a result of direct user
interaction. If browseForDirectory() is called
without such interaction, the call should be ignored entirely by the
underlying runtime.
After successfully calling and selecting a valid directory, the
File object acquired from
browseForDirectory() must be made available
in the mountPoints File
object.
Further, after successfully mounting, the files contained within the
mountpoint must be available through the
mountpoint protocol.
When attempting to create a mountpoint with a name that is previously in
use, a GENERIC_ERR exception is thrown.
browseForFile() methodThe browseForFile() method takes three arguments,
plus two optional arguments, and is used to allow the user to browse for a
single directory.
The return value, and first four arguments for
browseForFile() are the same as for
browseForDirectory(). The
browseForFile() method also follows the same
restrictions on when the method can be called, and returns the same errors as
the browseForDirectory() method.
The fifth, optional, argument to browseForFile()
is an Array of content types that should be shown in the file chooser dialog,
and that should be selectable in a dropdown of file types to be filtered.
It's an open issue what should be in this array exactly.
browseForSave() methodThe browseForSave() method is used to select a
file for saving. When called, the function returns void.
The first argument to browseForSave() is a
DOMString with the suggested default file name for saving. The second and
third arguments specifies, as for the other browseFor*() methods,
a suggested default location to save the file in, and the callback to call
once the user has selected a file for saving. If the forth argument
is true then the File object
must be marked persistent.
When the user has successfully selected a file to save, the callback
is called with a File as argument. This file object
may or may not exist on disk (i.e. have it's exists
attribute set or not), depending on whether the user chose an existing file or
created a new one in the dialog.
File interfaceThe File interface represents objects in a
virtual filesystem, and can represent either a file or a folder. A
file object consists of a number of properties, and methods for working on
these objects
File objects that are marked as
persistent must persist across restarts of the application.
interface File {
readonly attribute File parent; // Null if this is the mountpoint
readonly attribute Boolean readOnly;
readonly attribute Boolean exists;
readonly attribute Boolean isFile;
readonly attribute Boolean isDirectory;
readonly attribute Boolean isArchive;
readonly attribute Object metaData;
attribute Date created;
attribute Date modified;
readonly attribute DOMString name;
readonly attribute DOMString path;
readonly attribute DOMString nativePath;
readonly attribute Integer fileSize;
readonly attribute Integer length;
readonly attribute Integer maxPathLength;
FileStream open(in File file, in DOMString mode);
FileStream open(in File file, in DOMString mode, in Boolean async);
FileStream open(in DOMString file, in DOMString mode);
FileStream open(in DOMString file, in DOMString mode, in Boolean async);
File copyTo(in File path);
File copyTo(in File path, in Boolean overwrite);
File copyTo(in File path, in Boolean overwrite, in Function onCompleteCallback);
File copyTo(in DOMString path);
File copyTo(in DOMString path, in Boolean overwrite);
File copyTo(in DOMString path, in Boolean overwrite, in Function onCompleteCallback);
File moveTo(in File path);
File moveTo(in File path, in Boolean overwrite);
File moveTo(in File path, in Boolean overwrite, in Function onCompleteCallback);
File moveTo(in DOMString path);
File moveTo(in DOMString path, in Boolean overwrite);
File moveTo(in DOMString path, in Boolean overwrite, in Function onCompleteCallback);
File createDirectory(in File directory);
File createDirectory(in DOMString directory);
Boolean deleteDirectory(in DOMString directory)
Boolean deleteDirectory(in DOMString directory, in Boolean recursive)
Boolean deleteDirectory(in File directory)
Boolean deleteDirectory(in File directory, in Boolean recursive)
void deleteFile(in File file);
void deleteFile(in DOMString file);
void refresh();
File resolve(in DOMString path);
DOMString toString();
}File interfaceparent attribute, of type
File, readonlyThe parent attribute contains a pointer to the
parent file object. Normally, this object will have the attribute
isDirectory set to true, but in the
case where it also represents an archive file in the zip format (or other
supported formats, this object will in addition have the
isArchive attribute set to true. In the case
that the File object is the same object as the
mountPoints attribute of the
FileSystem object, the value will be
null.
For other file references that does not naturally have a parent, the value will also be null.
readOnly attribute, of
type Boolean, readonlyThe readonly attribute determines whether a
File object is writable. If the file is writable,
the value of the attribute must be false, otherwise it
must be true.
exists attribute, of
type Boolean, readonlyIf the file reference held by the File object
exists as an object on disk, the value of this attribute must be
true, otherwise the value must be false.
isFile attribute, of
type Boolean, readonlyIf the object referenced by the File object
is a file, the value of this attribute will be true, otherwise
false. This also applies to files that can be treated as an
archive, such as a zip file.
isDirectory attribute, of
type Boolean, readonlyIf the object referenced by the File object is a
directory, the value of this attribute will be true, otherwise
false. File that has the isArchive
attribute set, such as zip files will also have this attribute set.
isArchive attribute, of
type Boolean, readonlyIf the File object being referenced is an archive
type file, i.e. a zip file, the value of this attribute will be
true, otherwise the value of this attribute will be false.
Files where this attribute is true, are treatable both as directories, or
as files: It is thus possible to resolve files inside the archive directly for
opening, or the stream is openable using the open()
method.
metaData attribute, of type
Object, readonlyThe metaData attribute is an Object
that holds various metatdata connected to the file. Normally, the value of
this attribute will be null.
created attribute, of type
DateThe created attribute is a
Date object corresponding to the File object's
creation time. The value of the object should not be null if creation
date of the file or directory is missing, but may fall back to using
another appropriate date.
Assigning a Date object to the
created date should, if possible set the creation
date for the file. If setting this date is not possible, assigning a date to
the created attribute in question should fail
silently.
modified attribute, of type
DateThe modified attribute is a
Date object corresponding to the File object's
creation time. The value of the object should not be null if creation
date of the file or directory is missing, but may fall back to using
another appropriate date.
Assigning a Date object to the
modified date should, if possible set the creation
date for the file. If setting this date is not possible, assigning a
modification date to the modified attribute in
question should fail silently.
name attribute, of type
DOMString, readonlyThe name attribute is the URL encoded file name
of the file or directory represented by the File
object.
If the File object is a directory, the value of
the name attribute will be that of the directory
itself.
path attribute, of type
DOMString, readonlyThe path attribute is a URL encoded
DOMString holding the path of the file as represented in the
context of the sandboxed file system representation. The path is absolute,
beginning with a slash, and the name of the mountpoint.
The path attribute must include the name
of the file or the folder itself.
nativePath attribute, of
type DOMString, readonlyThe nativePath attribute is a
DOMString with a system-specific representation of the complete
path (including filename) of the object on disk.
Unlike other path references, the nativePath
should not be URL encoded, and resolving this native path
should not work in any method that resolves path or
file names.
For File objects mounted using
mountSystemDirectory()
nativePath will be the empty string.
fileSize attribute, of
type DOMString, readonlyIf the object referenced by a File object is a
file, i.e. the value of the isFile attribute is
true, the value of the fileSize
attribute will represent the file size, in bytes, of the
File object.
When the File object in question is not a file,
meaning that isFile is false, the value
of fileSize is 0.
length attribute, of
type DOMString, readonlyThe length attribute represents the number of
files and folders contained within a File object
that has its isDirectory attribute set to
true.
For objects that has isDirectory set to
false, the value must always be 0.
Note that the length attribute is not
dynamically updated, and should initially be 0 before
refresh() is called on the object, with the notable
exception of the File object in the
mountPoints attribute.
maxPathLength
attribute, of type unsigned int, readonlyThe maxPathLength attribute is a number
representing the maximum number of characters that can be used in a
pathname of files contained within a File object.
open() methodThe open() method is used to open a file
stream for reading and writing. Upon a successful call to open, a new
FileStream object is returned, allowing an
application to read contents from and write contents to a file.
The open() method takes three arguments. The
first argument should be either a DOMString
path reference, or a File object, or null. In
the case that the value is null, a call to open
open() must attempt to open
the file object on which the call itself was made.
The second argument to open() is a DOMString,
describing the file mode to use when opening the file. Valid modes are:
Should these be bit fields or enums instead of strings?
FileStream's
position attribute to the end of the file.FileStream's
position attribute to the end of the file.The third, optional Boolean argument to
open() determines whether the file is opened in
synchronous or asynchronous mode.
If a file is successfully opened, the call to
open() must return a
FileStream object.
If opening of the file fails, a number of exceptions may be thrown:
open() to be invoked, for instance if the file is
a directory.File object is not permitted.Other, generic or specific exceptions may be thrown, depending on external circumstances, such as an out-of-memory situation.
copyTo() methodThe copyTo() method is used to copy a file from
one location to another. The function has one mandatory argument, either a
DOMString with the URL encoded path of the desired destination, or
File object representing the desired location.
The second, optional argument to copyTo is a
boolean attribute telling whether the destination file should be overwritten
in the case that the destination file already exists. The default value of
this attribute is false. When the destination file exists, and
the value of this attribute is false, the
copyTo() operation must fail with a
GENERAL_ERR exception.
When copyTo() is successfully invoked, and a
copy operation takes place, the call will return a
File object with a reference to the new file.
The third, optional argument to copyTo() is a
function that is called when the copyTo() operation is complete.
moveTo() methodThe moveTo() method is used to move a file from
one location to another. The function has one mandatory argument, either a
DOMString with the URL encoded path of the desired destination, or
File object representing the desired
destination.
The second, optional argument to moveTo() is a
boolean attribute telling whether the destination file should be overwritten
in the case that the destination file already exists. The default value of
this attribute is false. When the destination file exists, and
the value of this attribute is false, the
moveTo() operation must fail with a
GENERAL_ERR exception.
The third, optional argument to moveTo() is a
function that is called when the copyTo() operation is complete.
When moveTo() is successfully invoked, and a
copy operation takes place, the call will return a
File object with a reference to the new file.
The call semantics are unclear at this point.
createDirectory()
methodThe createDirectory() method is used to create
new directories.
The first argument must either be a File
object acquired using a resolve() operation, or a
DOMString with a properly URL encoded path for the directory.
The UA must attempt to create all the parent directories needed to create the desired directory. If some of these directories are pre-existing, the UA must not delete these directories.
If the UA, after a successful invocation of the method, is able to
create the desired directory, the method must return a
File object referencing the freshly created
directory.
If creating the directory fails, an system-dependent exception should be thrown. What these errors are may vary from system to system, and as such are not specified further.
Perhaps we just should throw "DIRECTORY_CREATION_FAILED_ERR"?
deleteDirectory()
methodThe deleteDirectory() method is used to delete a
File object with the
isDirectory attribute set to true, and the
isFile attribute set to false.
The first argument to the file must be either a valid
File object, or a
DOMString with a URL encoded path to the
directory.
The second, optional argument to the method is a Boolean
which, when set to true means that the UA should try to
recursively delete the directory with all its descendants. When this attribute
is true, the UA should recursively delete all the files and folders
contained within the file. In this case, failure to delete a single file or
folder is not considered a fatal error, and the UA should
continue with the operation until as many files as possible are deleted.
The return value for deleteDirectory() is of type
Boolean. If deletion of the resource is successful, and the UA is
able to delete the resource itself, including any descendant files and
directories, the return value is true, otherwise, the return
value is false.
deleteFile() methodThe deleteFile() method is used to delete a
single File whose value for
isFile is true. When invoked, the
method always returns void.
Should an exception be thrown or a boolean be returned for failure cases?
refresh() methodThe refresh() method takes no arguments, and
returns no value. When the method is invoked on a
File where the value of the isDirectory
attribute is true, the length is
updated, and the object is populated with File
objects available through accessing the object as an array using numerical
indices.
resolve() methodThe resolve() method is used to acquire a
reference to a file or folder in the form of a File
object on disk, thus making it possible to manipulate the contents of this
file or folder. In the case that the resource does not previously exist,
acquiring this File reference, later operations may
be used to create the resource.
The resolve() method takes a
DOMString argument which is a URL escaped path, and returns a
File object.
When invoked with a correct argument, the
resolve() method must return a reference
either to an existing File object, meaning one where
the value of the exists is true, or a new file where
the value of the attribute is false.
toString() methodIn the context of a File object, the object's
toString() method should return the file's
complete absolute path (including filename), URL encoded.
FileStream
interfaceThe FileStream interface represents a
File object opened for reading and/or writing, and
defines methods and attributes for doing this work.
interface FileStream {
attribute unsigned Integer position;
readonly attribute unsigned Integer bytesAvailable;
readonly attribute Boolean eof;
attribute DOMString encoding; // default "UTF-8"
void close();
DOMString read(in Integer length);
DOMString read(in Integer length ,in DOMString charset);
DOMString readLine();
DOMString readLine(in DOMString charset);
ByteArray readBytes(in Integer length);
ByteArray readBytes(in Integer length, in Integer offset);
DOMString readBase64(in Integer length);
void write(in DOMString string);
void write(in DOMString string, in DOMString charset);
void writeLine(in DOMString string);
void writeLine(in DOMString string, in DOMString charset);
void writeBytes(in ByteArray bytes);
void writeBytes(in ByteArray bytes, in Integer length);
void writeFile(in File file);
void writeImage(in HTMLCanvasElement canvas);
void writeImage(in HTMLImageElement image);
void writeBase64(in DOMString string);
}FileStream interfaceposition attribute,
of type unsigned integerThe position attribute determines the position of
the file pointer from within the file as an offset of bytes from the start of
the file stream. When invoking an operation that reads or writes from the
stream, the operation will take place from the position in the
position attribute.
When setting the value, any value in the range 0 -
(File.fileSize) is
accepted. If a script sets position<0, the value
is set to 0. If
position>fileSize, then
position is set to fileSize
bytesAvailable
attribute, of type unsigned integer, readonlyThe bytesAvailable attribute is a positive
integer giving the number of bytes that are available for reading from the
stream. The value should be equal to the length of the file minus the current
position of the current position within the file.
eof attribute, of type
BooleanThe eof attribute is true whenever
the value of pointer is beyond the end of the last
byte of the FileStream (when position is equal to or
greater than fileSize), otherwise the value is
false.
close() methodThe close() method takes no arguments, and
returns no value. The method is used to close a previously opened file stream.
When invoked, the method should immediatly close the stream (pending
any buffered writes that may not be complete), and free any locks that
may have been set on the file.
read() methodThe read() method is used to read characters from
the FileStream. The first argument to the method,
length, is an unsigned integer deciding how many characters are read from the
stream.
The second argument to the method is optional, and when present
must be DOMString specifying which
character encoding is to be assumed when reading from the stream.
A successful invocation of read()
must return a valid DOMString containing
the characters read from the stream, and the
position attribute should be advanced to the
position after the last octet read.
In the case that an octet obtained from a read()
invocation are invalid in a DOMString, the
characters in question should be replaced with a U+FFFD replacement
character. If the read() operation starts in the
middle of a multibyte character, and it is possible to determine this, the UA
should also replace the octets that cannot be represented in a
DOMString with the U+FFFD replacement character.
When invoking a read() when there are no bytes
left to read in the stream, and the eof attribute is
already set to true, a call to read()
must return null.
When invoking a read() operation is invoked with
a length argument, and this length argument means that reading will proceed
beyond the end of the stream, the invocation must read only to the
end of the stream, and set the eof attribute on the
FileStream. The return value must then be
all characters up until the end of the stream. Authors are cautioned that the
length of the returned DOMString may be less than that
of the requested length argument.
When reading from the start of a stream, e.g. when the
position is at 0, or before the first valid octet
that is a valid character in a DOMString,
read() may skip forward to the first
character, provided that the first octets represent a valid BOM.
If reading from a stream fails, the UA may throw a system-specific exception.
readLine() methodThe readLine() method is used to read a single
line of input from a valid FileStream instance. The
method accepts an optional DOMString argument specifying the
charset the stream is to be interpreted as.
A successful invocation of readLine()
must return a valid DOMString, not including the CR and
LF characters, and replacing invalid characters with the U+FFFD replacement
character. A successful invocation must also cause the UA to advance
the position within the file to the first character
after a valid octet sequence representing a newline.
When invoking a readLine() when are no bytes left
to read in the stream, and when the eof attribute is
already set, a call to read() must return
null.
If reading from a stream fails, the UA may throw a system-specific exception.
readBytes() methodThe readBytes method is used to read an octet off
a valid FileStream instance. The method takes one
argument, an unsigned integer representing the number of octets to be read
from the stream.
When a successful call to readBytes() method is
made, an UA must return a valid ByteArray
containing the octets read. When reading beyond the end of the stream, the UA
must set the eof attribute to
true, and return a ByteArray containing
the octets from the position it started to read from the stream until the
end. As such, a developer cannot rely on the length of the ByteArray being
equal to the length specified in the length argument to the stream.
If readBytes() is invoked when the
eof attribute is set to true, the UA
must return null.
A UA may throw system-specific exceptions if it is unable to read from the stream.
readBase64() methodThe readBase64 method is used to read an octet
from a valid FileStream instance, and return a
DOMString with a base-64 encoded representation of the octets
read from the stream. The method takes one argument, an unsigned integer
representing the number of octets to be read from the stream.
When a successful call to readBase64() method is
made, an UA must return a valid ByteArray
containing the octets read. When reading beyond the end of the stream, the UA
must set the eof attribute to
true, and return a DOMString containing
the octets from the position it started to read from the stream until the
end. As with readBytes(), a developer cannot rely
on the returned DOMString representing a base-64 encoded string
whose length, when converted back to a ByteArray,
matches the length specified in the first argument to
readBase64().
If readBase64() is invoked when the
eof attribute is set to true, the UA
must return null.
A UA may throw system-specific exceptions if it is unable to read from the stream.
write() methodThe write() method is used to write character
data to a file stream.
The first argument to write() is mandatory, and
must be a valid DOMString containing the data to be
written to the stream. When the method is successfully invoked, the UA
should write the data in this first argument to the file stream
starting from the position in the position
attribute, unless the file is opened in append mode. If the file is opened in
append mode, the position should be advanced to the end of file before
writing.
The second argument to write(), of type
DOMString, is used to specify which character encoding should be
used when writing the string specififed in the first argument.
write() may throw a system-specific
error if writing fails, when conditions such as running out of free disk space
arises.
writeLine() methodThe writeLine() method is used to write character
data to a file stream, and emit a valid linefeed sequence after the input
string.
The first argument to writeLine() is mandatory,
and must be a valid DOMString containing the data to be
written to the stream. When the method is successfully invoked, the UA
should write the data in this first argument, plus a valid linefeed
sequence to the file stream starting from the position in the
position attribute, unless the file is opened in
append mode. If the file is opened in append mode, the position should be
advanced to the end of file before writing.
The second argument to writeLine(), of type
DOMString, is used to specify which character encoding should be
used when writing the string specififed in the first argument.
writeLine() may throw a system-specific
error if writing fails, when conditions such as running out of free disk space
arises.
Valid linefeed sequences are not specified yet.
write and writeLine currently both write UTF-8 only, and ignores any encoding specified.
The valid strings for selecting encoding needs to be listed.
writeBytes() methodThe writeBytes() method is used to write a series
of octets to the file stream specified.
The first argument to writeBytes() is a
ByteArray containing the data to be written. When
the method is successfuly invoked, the UA should write the data to
the FileStream, starting from the current position,
as given by the position attribute, unless the
file is opened in append mode, in which case the position must be set
to the end of the file before the writing operation commences.
writeBytes() may throw a system-specific
error if writing fails, when conditions such as running out of free disk space
arises.
writeBase64() methodThe writeBase64() method is used to write a
series of octets to the file stream specified with the octets input specified
as a base-64 encoded string.
The first argument to writeBase64() is a
DOMString containing the data to be written. When the method is
successfuly invoked, the UA should take the base64-encoded string,
convert it to a ByteArray, and write the data to the
FileStream, starting from the current position, as
given by the position attribute, unless the file is
opened in append mode, in which case the position must be set to the
end of the file before the writing operation commences.
writeBytes() may throw a system-specific
error if writing fails, when conditions such as running out of free disk space
arises.
writeFile() methodThe writeFile() method is used to write the entire
contents of a valid File object to the
FileStream
The writeFile() method takes one mandatory
argument, a valid File object. When the method is
successfully invoked, the UA should write the contents of the file,
starting from the current position, unless the file
is in append mode, in which case the position should
be set to be at the end of the FileStream.
Given two file objects, f1 and f2, calling
f1.open(f1,"w").writeFile(f2) should behave the same as
the following example:
var srcStream = f2.open(f2,"r");
var destStream = f1.open(f1,"rw");
var srcData = srcStream.read(f2.fileSize);
srcStream.close();
destStream.writeBytes(srcData);
destStream.close();
writeFile has no return value.
writeImage() methodThe writeImage() method is used to write the
contents of a HTMLCanvasElement object or an
HTMLImageElement to a file.
The method accepts one argument, which is mandatory. This argument can be
either a HTMLCanvasElement object or an
HTMLImageElement instance. If
writeImage() is successfully invoked, the UA
should write the image, starting from the current
position, unless the file is in append mode, in
which case the position should be set to be at the
end of the FileStream.
When writing a HTMLCanvasElement, the image
should be encoded as image/png. In the case that the image is a
HTMLImageElement, the image should be written with the same
encoding that is used in the original element.
The U+002F solidus character, / is a reserved character and must not be used to name a file or folder.
Different file systems have different conventions for file names, and may or may not allow use of certain characters in a file or path name. For portability, applications are therefore discouraged when creating folders or files. The list is as follows:
| Character | Reason |
|---|---|
| : | Used to denote alternate file streams on NTFS file systems, as a path separator on OS X, and used to determine the mountpoint (e.g. C:) on Windows systems. |
| ? | Used as a wildcard match on virtually all systems, and explicitly illegal in filenames on Windows systems |
| * | Used as a wildcard match on virtually all systems, and explicitly illegal in filenames on Windows systems |
| |, < and > | Used for pipes and redirection on Unix systems |
| \ | Used as path separator on Windows systems |
The file names '.' and '..' are used to denote current folder and parent folder on virtually all file systems, and creating files or folders with these names are thus disallowed
In addition to the disallowed file names, a number of file names are discouraged for portable applications, because these files cannot be recreated reliably on all platforms. The list is as follows:
CON, PRN, AUX, CLOCK$, NUL, COM0, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9 LPT0, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, and LPT9.
Authors should not create files using any of these names, also including creating the file with an additional extension.
mountpoint URL
protocolWhen referencing files in mountpoints from inside an application, the
mountpoint protocol is used. The scheme-specific
syntax is described as below.
mountpoint_url = "mountpoint:" "//" mountpoint_name [ abs_path ]
Here, mountpoint_name corresponds to a previously mounted directory, and abs_path corresponds to an absolute path within the specified mountpoint.
The absolute path in a mountpoint always starts with the character for the path separator '/', (Unicode U+002F solidus).
For instance, if a user has acquired a mountpoint, and named it
myImages using the call
browseForDirectory("myImages","",callback_function), the
user can access files inside the mountpoint by creating an absolute URI:
mountpoint://myImages/example.txt