Samsung Electronics logo

Samsung Web API: Filesystem

© 2013 Samsung Electronics Co., Ltd. All rights reserved.

Introduction

This API provides access to a device's filesystem.

The filesystem is represented as an abstract collection of disjointed filesystem virtual root locations, each corresponding to a specific location in the device filesystem. The filesystem API exposes the hierarchies below these root locations as a single virtual filesystem, but provides no access to other parts of the device filesystem.

Each virtual root has a string name. Each file or directory within the virtual filesystem is addressed using a fully-qualified path of the form: <root name>/<path> where <rootname> is the name of the virtual root and <path> is the path to the file or directory relative to that root.

The following virtual roots MUST be supported:

  • images: the images location
  • videos: the videos location
  • music: the sounds location
  • documents: the documents location
  • downloads: the location for downloaded items
  • ringtones: the location for ringtones (read-only location)
  • wgt-package: the widget package location (read-only location)
  • wgt-private: the widget private storage
  • wgt-private-tmp: the widget private volatile storage area

The file URI path is also supported. if you want to access other paths out of virtual root, for example '/tmp/', 'file:///tmp' could be used as location parameter.

To access specific locations from those specified above, a file handle must be retrieved using the filesystem.resolve call.

A file handle represents either a file or a directory. For a file, the isFile attribute is true. For a directory, the isDirectory attribute is true. A file can be opened for read and write operations, using a FileStream handle. A list of files and sub-directories can be obtained from a directory and a resolve method exists to resolve files or sub-directories more conveniently than processing directory listings.

The implementation MUST support the use of the following characters in file names:

  • Letters (azAZ)
  • Numbers (0-9)
  • Blank spaces
  • Underscores ("_")
  • Hyphens ("-")
  • Periods (".")

The implementation MAY support additional characters in file names, depending on platform support.

The implementation MAY forbid the use of additional characters in file names, depending on the platform. The use of the path separator "/" in file names MUST NOT be allowed. The "/" character is used as the (path) component separator.

Some other file name and path characteristics are platform-dependent, for example, maximum path length, file name length, case sensitivity, additional character support, etc. Therefore, it is recommended that you avoid any dependency on aspects that cannot be supported across many platforms.

When a path is used to interact with the underlying filesystem, the encoding used for the file path SHOULD be the platform default.

For more information on the Filesystem features, see File System Guide.

Table of Contents

Summary of Interfaces and Methods

Interface Method
FileSystemManagerObject
FileSystemManager void resolve(DOMString location, FileSuccessCallback onsuccess, ErrorCallback? onerror, FileMode? mode)
void getStorage(DOMString label, FileSystemStorageSuccessCallback onsuccess, ErrorCallback? onerror)
void listStorages(FileSystemStorageArraySuccessCallback onsuccess, ErrorCallback? onerror)
long addStorageStateChangeListener(FileSystemStorageSuccessCallback onsuccess, ErrorCallback? onerror)
void removeStorageStateChangeListener(long watchId)
FileSystemStorage
File DOMString toURI()
void listFiles(FileArraySuccessCallback onsuccess, ErrorCallback? onerror, FileFilter? filter)
void openStream(FileMode mode, FileStreamSuccessCallback onsuccess, ErrorCallback? onerror, DOMString? encoding)
void readAsText(FileStringSuccessCallback onsuccess, ErrorCallback? onerror, DOMString? encoding)
void copyTo(DOMString originFilePath, DOMString destinationFilePath, boolean overwrite, SuccessCallback? onsuccess, ErrorCallback? onerror)
void moveTo(DOMString originFilePath, DOMString destinationFilePath, boolean overwrite, SuccessCallback? onsuccess, ErrorCallback? onerror)
File createDirectory(DOMString dirPath)
File createFile(DOMString relativeFilePath)
File resolve(DOMString filePath)
void deleteDirectory(DOMString directoryPath, boolean recursive, SuccessCallback? onsuccess, ErrorCallback? onerror)
void deleteFile(DOMString filePath, SuccessCallback? onsuccess, ErrorCallback? onerror)
FileFilter
FileStream void close()
DOMString read(long charCount)
octet[] readBytes(long byteCount)
DOMString readBase64(long byteCount)
void write(DOMString stringData)
void writeBytes(octet[] byteData)
void writeBase64(DOMString base64Data)
FileSuccessCallback void onsuccess(File file)
FileSystemStorageArraySuccessCallback void onsuccess(FileSystemStorage[] storages)
FileSystemStorageSuccessCallback void onsuccess(FileSystemStorage storage)
FileStringSuccessCallback void onsuccess(DOMString fileStr)
FileStreamSuccessCallback void onsuccess(FileStream filestream)
FileArraySuccessCallback void onsuccess(File[] files)

1. Type Definitions

1.1. FileMode

The file mode provided when opening. 

  enum FileMode { "r", "rw", "w", "a" };

Value "r" to obtain read-only access, "rw" to obtain read and write access, "w" to obtain write access and "a" for appending.

1.2. FileSystemStorageType

The type of storage. 

  enum FileSystemStorageType { "INTERNAL", "EXTERNAL" };
  • INTERNAL: Internal storage is storage that cannot be removed, such as a flash memory.
  • EXTERNAL: External storage is removable storage, such as a USB drive or memory cards.

1.3. FileSystemStorageState

The state of the storage. 

  enum FileSystemStorageState { "MOUNTED", "REMOVED", "UNMOUNTABLE" };
  • MOUNTED: The device is mounted and can be browsed.
  • REMOVED: The device was removed. This states only applies to external drives.
  • UNMOUNTABLE: The device cannot be mounted due to an error.

2. Interfaces

2.1. FileSystemManagerObject

Defines what is instantiated in the webapis object. 

  [NoInterfaceObject] interface FileSystemManagerObject {
    readonly attribute FileSystemManager filesystem;
  };
  WebAPIs implements FileSystemManagerObject;

There will be a webapis.filesystem object that allows accessing the functionality of the filesystem API.

2.2. FileSystemManager

The file system manager interface that provides access to the filesystem API. 

  [NoInterfaceObject] interface FileSystemManager {
    readonly attribute long maxPathLength;

    void resolve(DOMString location,
                 FileSuccessCallback onsuccess,
                 optional ErrorCallback? onerror,
                 optional FileMode? mode) raises(WebAPIException);

    void getStorage(DOMString label,
                    FileSystemStorageSuccessCallback onsuccess,
                    optional ErrorCallback? onerror) raises(WebAPIException);

    void listStorages(FileSystemStorageArraySuccessCallback onsuccess,
                      optional ErrorCallback? onerror) raises(WebAPIException);

    long addStorageStateChangeListener(FileSystemStorageSuccessCallback onsuccess,
                                       optional ErrorCallback? onerror) raises(WebAPIException);

    void removeStorageStateChangeListener(long watchId) raises(WebAPIException);
  };

This manager exposes the filesystem base API, and provides functionality, such as determining root and default locations, resolving a given location into a file handle, and registering filesystem listeners for filesystem events.

Code example
 var documentsDir;
 function onsuccess(files) {
   for(var i = 0; i < files.length; i++) {
     console.log("File Name is " + files[i].name); // displays file name
   }

   var testFile = documentsDir.createFile("test.txt");

   if (testFile != null) {
     testFile.openStream(
       "w",
       function(fs){
         fs.write("HelloWorld");
         fs.close();
       }, function(e){
         console.log("Error " + e.message);
       }, "UTF-8"
     );
   }
 }

 function onerror(error) {
   console.log("The error " + error.message + " occurred when listing the files in the selected folder");
 }

 webapis.filesystem.resolve(
   'documents', 
   function(dir){
     documentsDir = dir;
     dir.listFiles(onsuccess,onerror);
   }, function(e){
     console.log("Error" + e.message);
   }, "rw"
 );

ATTRIBUTES

readonly long maxPathLength

Contains the platform-dependent maximum path length.

This attribute is read-only.
Code example
 console.log("The maximum path length is " + webapis.filesystem.maxPathLength);

METHODS

resolve

Resolves a location to a file handle.

Signature
void resolve(DOMString location, FileSuccessCallback onsuccess, optional ErrorCallback? onerror, optional FileMode? mode);

It validates and resolves the given location to a file handle. If the operation completes successfully, the handle is returned in the FileSuccessCallback. A valid location is prefixed with a valid root or default location and must address an existing, accessible file or directory.

A location can contain virtual path like (documents/some_file.txt) or it can be a file's URI (file:///my_strange_path/some_file.png).

The list of root locations that MUST be supported by a compliant implementation are:

  • documents: Describes the default folder in which text documents (such as pdf, doc...) are stored by default in the device. For example, in some platforms it corresponds to the "My Documents" folder.
  • images: Describes the default folder in which still images, like pictures (such as jpg, gif, png, etc.), are stored in the device by default. For example, in some platforms it corresponds to the "My Images" folder.
  • music: Describes the default folder in which sound clips (such as mp3, aac, etc.) are stored in the device by default. For example, in some platforms it corresponds to the "My Music" folder.
  • videos: Describes the default folder in which video clips (such as avi, mp4, etc.) are stored in the device by default. For example, in some platforms it corresponds to the "My Videos" folder.
  • ringtones: Describes the default folder in which ringtones (such as mp3, etc) are stored by default in the device.
  • downloads: Describes the default folder in which files downloaded (such as by a browser, e-mail client, etc.) are stored by default in the device. For example, in some platforms it corresponds to the "Downloads" folder.
  • wgt-package: Describes the read-only folder in which the content of the widget file was extracted to.
  • wgt-private: Describes a private folder in which a widget can store information. This folder MUST be accessible only to the widget. Other widgets or applications MUST NOT access the information stored there.
  • wgt-private-tmp: Describes a temporary, private folder in which a widget can store data that is available during one widget execution cycle. Content of this folder MAY be removed from this directory when the widget is closed or the Web Runtime is restarted. This folder MUST be accessible only to the widget. Other widgets or applications MUST NOT have access to it.

The mode parameter specifies whether the resulting File object has read-only access ("r" access), read and write access ("rw" access), append access ("a" access), or write access ("w" access) to the root location containing directory tree. Permission for the requested access is obtained from the security framework. Once the resulting File object has access, access is inherited by any other File objects derived from this instance without any further reference to the security framework, as noted in descriptions of certain methods of File.

The ErrorCallback is launched with these error types:

  • InvalidValuesError: If any of the input parameters contain an invalid value. For example, the mode is not valid (that is not "r", "rw", "a", or "w").
  • NotFoundError: The location input argument does not correspond to a valid location.
  • UnknownError: In any other error case.
Parameters
  • location
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: Location to resolve.
  • onsuccess
    • Optional: No.
    • Nullable: No.
    • Type: FileSuccessCallback.
    • Description: Called when the location has been. successfully resolved, passing the newly created File object.
  • onerror
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: Called if an error occurred.
  • mode
    • Optional: Yes.
    • Nullable: Yes.
    • Type: FileMode.
    • Description: Optional string of value "r" to obtain read-only access, "rw" to obtain read and write access, "a" to obtain append access, or "w" to obtain write access to all files and directories that can be reached from the File object passed to onsuccess. Defaults to "rw" if absent or null.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

Code example
 webapis.filesystem.resolve(
   'images',
   function(dir) {
     console.log("Mount point Name is " +  dir.path);
   }, function(e) {
     console.log("Error: " + e.message);
   }, "r"
 );

getStorage

Gets information about a storage based on its label.

Signature
void getStorage(DOMString label, FileSystemStorageSuccessCallback onsuccess, optional ErrorCallback? onerror);

Get storage information based on its label (example: "MyThumbDrive", "InternalFlash"). The onsuccess will receive as input argument the data structure containing additional information about the drive.

The ErrorCallback is launched with these error types:

  • NotFoundError: No drive was found with the given label.
  • InvalidValuesError: If any of the input parameters contain an invalid value.
  • UnknownError: In any other error case.
Parameters
  • label
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: Storage label.
  • onsuccess
    • Optional: No.
    • Nullable: No.
    • Type: FileSystemStorageSuccessCallback.
    • Description: Called when the list of storage is available, passing the storage list to the callback.
  • onerror
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: Called if an error occurred.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

Code example
 function onStorage(storage) {
     // Do something
 }

 function onStorageError(e) {
 console.log("Storage not found!" + e.message);
 }

 webapis.filesystem.getStorage("MMC", onStorage, onStorageError);

listStorages

Lists the available storages on the device.

Signature
void listStorages(FileSystemStorageArraySuccessCallback onsuccess, optional ErrorCallback? onerror);

Get the list of available internal and external storage devices. The onsuccess will receive as input argument a list of the data structure containing additional information about each drive found. Can get storages would have a label named as 'internal0', virtual roots (images, documents,...), 'removable1', 'removable2'. 'removable1' label would be used to resolve sdcard and 'removable2' label would be used to resolve usb host, if supported. The vfat filesystem used widly as sdcard filesystem is not case-sensitive. If you want to handle the file on sdcard, you need to consider case-sensitive filenames are regarded as same name.

Labels can be different, depends on platform implementation.

The ErrorCallback is launched with these error types:

  • InvalidValuesError: If any of the input parameters contain an invalid value.
  • UnknownError: In any other error case.
Parameters
  • onsuccess
    • Optional: No.
    • Nullable: No.
    • Type: FileSystemStorageArraySuccessCallback.
    • Description: Called when the list of storage is available, passing the storage list to the callback.
  • onerror
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: Called if an error occurred.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

Code example
 function alertForCorruptedRemovableDrives(storages) {
     for (var i = 0; i < storages.length; i++) {
         if (storages[i].type != "EXTERNAL")
             continue;
         if (storages[i].state == "UNMOUNTABLE")
             console.log("External drive " + storages[i].label + " is corrupted.");
     }
 }

 webapis.filesystem.listStorages(alertForCorruptedRemovableDrives);

addStorageStateChangeListener

Subscribes to notifications when a storage state changes.

Signature
long addStorageStateChangeListener(FileSystemStorageSuccessCallback onsuccess, optional ErrorCallback? onerror);

The most common usage for this method would be to watch notifications of additions and removals of external storages.

When executed, the implementation MUST immediately return a subscription identifier that identifies the watch operation. After returning the identifier, the watch operation is started asynchronously. The onsuccess MUST be invoked every time a storage state changes. If the attempt fails, the onerror (if present) MUST be invoked with the relevant error type.

The watch operation MUST continue until the removeStorageStateChangeListener() method is called with the corresponding subscription identifier.

Parameters
  • onsuccess
    • Optional: No.
    • Nullable: No.
    • Type: FileSystemStorageSuccessCallback.
    • Description: To be invoked in every change on storage state.
  • onerror
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: To be invoked in case of error during the watch process.
Return value
long The identifier used to clear the watch subscription.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error case.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var watchID;
 function onStorageStateChanged(storage) {
     if (storage.state == "MOUNTED")
         console.log("Storage " + storage.label + " was added!");
 }

 watchID = webapis.filesystem.addStorageStateChangeListener(onStorageStateChanged);

removeStorageStateChangeListener

Unsubscribes a storage watch operation.

Signature
void removeStorageStateChangeListener(long watchId);

If the watchId argument is valid and corresponds to a subscription already in place, the watch process MUST immediately stop and no further callbacks MUST be invoked.

Parameters
  • watchId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Subscription Identifier.
Exceptions
  • WebAPIException:

    with error type NotFoundError, if the watchId does not exist.

    with error type UnknownError, if any other error case.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var watchID;
 function onStorageStateChanged(storage) {
     if (storage.state == "MOUNTED")
         console.log("Storage " + storage.label + " was added!");
     webapis.filesystem.removeStorageStateChangeListener(watchID);
 }

 watchID = webapis.filesystem.addStorageStateChangeListener(onStorageStateChanged);

2.3. FileSystemStorage

The FileSystemStorage interface. 

  [NoInterfaceObject] interface FileSystemStorage {
    readonly attribute DOMString label;

    readonly attribute FileSystemStorageType type;

    readonly attribute FileSystemStorageState state;
  };

This interface gives additional information about a storage, such as if the device is mounted, if it's a removable drive or not, or the device's name. To retrieve the mount point, the resolve() method should be used using the label as argument.

ATTRIBUTES

readonly DOMString label

The storage name.

Used as input for functions like getStorage() and also used as 'location' parameter for File.resolve() and FileSystemManager.resolve().

This attribute is read-only.

readonly FileSystemStorageType type

The storage type.

Defines whether the storage is internal or external.

This attribute is read-only.

readonly FileSystemStorageState state

The storage state.

Defines whether the storage is mounted or not.

This attribute is read-only.

2.4. File

The file interface. 

  [NoInterfaceObject] interface File {
    readonly attribute File? parent;

    readonly attribute boolean readOnly;

    readonly attribute boolean isFile;

    readonly attribute boolean isDirectory;

    readonly attribute Date? created;

    readonly attribute Date? modified;

    readonly attribute DOMString path;

    readonly attribute DOMString name;

    readonly attribute DOMString fullPath;

    readonly attribute unsigned long long fileSize;

    readonly attribute long length;

    DOMString toURI() raises(WebAPIException);

    void listFiles(FileArraySuccessCallback onsuccess,
                   optional ErrorCallback? onerror,
                   optional FileFilter? filter) raises(WebAPIException);

    void openStream(FileMode mode,
                    FileStreamSuccessCallback onsuccess,
                    optional ErrorCallback? onerror,
                    optional DOMString? encoding) raises(WebAPIException);

    void readAsText(FileStringSuccessCallback onsuccess,
                    optional ErrorCallback? onerror,
                    optional DOMString? encoding) raises(WebAPIException);

    void copyTo(DOMString originFilePath,
                DOMString destinationFilePath,
                boolean overwrite,
                optional SuccessCallback? onsuccess,
                optional ErrorCallback? onerror) raises(WebAPIException);

    void moveTo(DOMString originFilePath,
                DOMString destinationFilePath,
                boolean overwrite,
                optional SuccessCallback? onsuccess,
                optional ErrorCallback? onerror) raises(WebAPIException);

    File createDirectory(DOMString dirPath) raises(WebAPIException);

    File createFile(DOMString relativeFilePath) raises(WebAPIException);

    File resolve(DOMString filePath) raises(WebAPIException);

    void deleteDirectory(DOMString directoryPath,
                         boolean recursive,
                         optional SuccessCallback? onsuccess,
                         optional ErrorCallback? onerror) raises(WebAPIException);

    void deleteFile(DOMString filePath,
                    optional SuccessCallback? onsuccess,
                    optional ErrorCallback? onerror) raises(WebAPIException);
  };

This interface represents the file abstraction in use. A file handle represents a file if the isFile property is true, if the isFile property is false, the file handle represents a directory. If a file handle represents a directory, it can address files and directories.

The file object permissions for the file object location and tree rooted at that location depends upon the mode defined in the resolve method. When a File object creates a child File object, the new File object inherits its access rights from the parent object without any reference to the security framework, as noted in certain methods of File.

A file handle representing a file can be opened for I/O operations, such as reading and writing.

A file handle representing a directory can be used for listing all files and directories rooted as the file handle location.

Code example
 function onsuccess(files) {
   for(var i = 0; i < files.length; i++) {
     // alerts each name of dir's contents
     console.log(files[i].name);
   }
 }

 function onerror(error) {
   console.log("The error " + error.message +
               " occurred when listing the files in the selected folder");
 }

 // list directory contents
 dir.listFiles(onsuccess, onerror);

ATTRIBUTES

readonly File? parent

The parent directory handle.

null if there is no parent directory.

If there is no parent directory, this represents a root location.

This attribute is read-only.
Code example
 // list directory contents
 dir.listFiles(onsuccess, onerror);

 function onsuccess(files) {
   for(var i = 0; i < files.length; i++) {
     // prints the file parent, should contain the
     // same value for all the files in the loop
     console.log("All the files should have the same parent " +
                 files[i].parent);
   }
 }

 function onerror(error){
   console.log("The error " + error.message +
               " occurred when listing the files in the selected folder");
 }

readonly boolean readOnly

The file/directory access state in the filesystem.

true if object has read-only access at its location.

false if object has write access at its location.

This attribute represents the actual state of a file or directory in the filesystem. Its value is not affected by the mode used in FileSystemManager.resolve that was used to create the File object from which this File object was obtained.

This attribute is read-only.
Code example
 // list directory contents
 dir.listFiles(onsuccess, onerror);

 function onsuccess(files) {
   for(var i = 0; i < files.length; i++) {
     if(files[i].readOnly)
       console.log("Cannot write to file " + files[i].name);
     else
       console.log("Can write to file " + files[i].name);
   }
 }

 function onerror(error) {
   console.log("The error " + error.message + " occurred when listing the files in the selected folder");
 }

readonly boolean isFile

The file type.

true if this handle is a file. false if this handle is a directory.

This attribute is read-only.

readonly boolean isDirectory

The file type.

true if this handle is a directory, false if this handle is a file.

This attribute is read-only.

readonly Date? created

The creation timestamp of this file.

This is the timestamp when the file was first created in the filesystem. Equivalent to the timestamp when a call to createFile() succeeds.

If the platform does not support this attribute, it MUST be null.

It is unspecified and platform-dependent if the creation timestamp changes when a file is moved.

This attribute is read-only.

readonly Date? modified

The modification timestamp.

The modification timestamp of this file. This is the timestamp of the most recent modification to the file, usually when the last write operation succeeded. Opening a file for reading does not change the modification timestamp.

If the platform does not support this attribute, it MUST be null.

It is unspecified and platform-dependent if the modified timestamp changes when a file is moved.

This attribute is read-only.
Code example
 console.log(file.modified); // displays the modification timestamp

readonly DOMString path

The path of this file, excluding the file name.

This is the path of this file, beginning with the name of the root containing the file, up to and including the directory containing the file, but excluding the file name.

Except in a special case of the File representing the root itself, the last character is always the character '/'.

For example, if a file is located at music/ramones/volume1/RockawayBeach.mp3, the path would be music/ramones/volume1/.

For example, if a directory is located at music/ramones/volume1, the path would be music/ramones/.

For the virtual roots, the path is same as the name of the virtual root. For example, if the root is music, then the path is music. If the root is documents, then the path is documents.

This attribute is read-only.
Code example
 console.log(file.path); // should be 'music/' if the file is music/foo.mp3

readonly DOMString name

The file name, excluding any path components.

This is the name of this file, excluding the root name and any other path components.

For example, if a file is located at music/ramones/volume1/RockawayBeach.mp3, the name would be RockawayBeach.mp3.

For example, if a directory is located at music/ramones/volume1, the name would be volume1.

For the special case of the root itself, the name is an empty string.

This attribute is read-only.
Code example
 console.log(file.name); // should be foo.mp3 if the file path is music/foo.mp3

readonly DOMString fullPath

The full path of this file.

The full path of this file, beginning with the name of the root containing the file, and including the name of the file or directory itself.

For instance, for a file, if the file is located at music/ramones/volume1/RockawayBeach.mp3, then the fullPath is music/ramones/volume1/RockawayBeach.mp3.

For a directory, if the directory is located at music/ramones/volume1, then the fullPath is music/ramones/volume1.

For the special case of the root itself, if the root is music, then the fullPath is music.

The fullPath is always equal to path + name.

This attribute is read-only.
Code example
 console.log(file.fullPath); // should be music/track1.mp3 if the file is music/track1.mp3

readonly unsigned long long fileSize

The size of this file, in bytes.

If there's an attempt to read this attribute on a directory, undefined is returned. To retrieve the number of files and directories contained in the directory, use the length attribute, instead.

This attribute is read-only.
Code example
 console.log(file.fileSize); // displays the file size

readonly long length

The number of files and directories contained in this file handle.

If there's an attempt to read this attribute on a file, undefined is returned. To retrieve the size of a file, use the fileSize attribute instead.

This attribute is read-only.
Code example
 console.log(file.length); // '3' if the directory contains two files and one sub-directory

METHODS

toURI

Returns a URI for the file.

Signature
DOMString toURI();

Returns a URI that can be used to identify this entry (such as using it as the src attribute on an HTML img element). The URI has no specific expiration, it should be valid at least as long as the file exists.

When this method is invoked, the implementation MUST generate a URI.

If that URI corresponds to any of the public virtual roots (that is images, videos, music, documents, and downloads) the URI MUST be globally unique and could be used by any widget.

If that URI corresponds to a file located in any of the widget private areas (such as wgt-package, wgt-private, wgt-private-tmp). The generated URI MUST be unique for that file and for the widget making the request (such as including some derived from the widget id in the URI). These URIs MUST NOT be accessible to other widgets, apart from the one invoking this method.

Return value
DOMString The URI that identifies the file or null if an error occurs.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error situation.

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if this functionality is not supported.

Code example
 // 'file://music/ramones/RockawayBeach.mp3' or 'file:///opt/media/music/ramones/RockawayBeach.mp3' if the file is
 // music/ramones/RockawayBeach.mp3
 console.log(file.toURI());

listFiles

Returns the list of all files in this directory.

Signature
void listFiles(FileArraySuccessCallback onsuccess, optional ErrorCallback? onerror, optional FileFilter? filter);

The list of files will be passed as a File[] in the onsuccess and contains directories and files. However, the directories "." and ".." MUST NOT be returned. Each File object part of the array MUST inherit all the access rights (that is one of the values in FileMode) from the File object in which this method was invoked.

If the filter is passed and contains valid values, only those directories and files in the directory that match the filter criteria specified in the FileFilter interface MUST be returned in the onsuccess. If no filter is passed, the filter is null or undefined, or the filter contains invalid values, the implementation MUST return the full list of files in the directory.

If the directory does not contain any files or directories, or the filter criteria is unmatched to any files or directories, the onsuccess will be invoked with an empty array.

The ErrorCallback is launched with these error types:

  • IOError: The operation is launched on a file (not a directory).
  • InvalidValuesError: If any of the input parameters contain an invalid value.
  • UnknownError: In any other error case.
Parameters
  • onsuccess
    • Optional: No.
    • Nullable: No.
    • Type: FileArraySuccessCallback.
    • Description: Called when the list operation has been successfully completed.
  • onerror
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: Called if an error occurred.
  • filter
    • Optional: Yes.
    • Nullable: Yes.
    • Type: FileFilter.
    • Description: Used to restrict the listed files.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

Code example
 function onsuccess(files) {
   console.log("There are " + files.length  + " in the selected folder");
 }

 function onerror(error) {
   console.log("The error " + error.message + " occurred when listing the files in the selected folder");
 }

 webapis.filesystem.resolve(
     "documents",
     function(dir){
       dir.listFiles(onsuccess, onerror);
     }, function(e){
       console.log("Error " + e.message);
     }, "r"
 );

openStream

Opens the file in the given mode supporting the given encoding.

Signature
void openStream(FileMode mode, FileStreamSuccessCallback onsuccess, optional ErrorCallback? onerror, optional DOMString? encoding);

This operation is performed asynchronously. If the file is opened successfully, the onsuccess is invoked with a FileStream that can be used for reading and writing the file, depending on the mode. The return FileStream instance includes a file pointer, which represents the current position in the file. The filepointer will, by default, be at the start of the file, except in the case of opening with append ("a") mode, in which case the filepointer points to the end of the file.

The ErrorCallback is launched with these error types:

  • InvalidValuesError: If any of the input parameters contains an invalid value.
  • IOError: The operation is launched on a directory (not a file), the file is not valid or it does not exist.
  • UnknownError: In any other error case.
Parameters
  • mode
    • Optional: No.
    • Nullable: No.
    • Type: FileMode.
    • Description: The mode for opening a file: "r" for reading "a" for appending "w" for [over]writing "rw" for reading and writing
  • onsuccess
    • Optional: No.
    • Nullable: No.
    • Type: FileStreamSuccessCallback.
    • Description: Called when the file has been opened.
  • onerror
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: Called if an error occurred.
  • encoding
    • Optional: Yes.
    • Nullable: Yes.
    • Type: DOMString.
    • Description: The encoding for read/write operations on the file, at least the following encodings MUST be supported: "UTF-8" default encoding, "ISO-8859-1" latin1 encoding. If no encoding is passed by the developer, then the default platform encoding MUST be used.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

Code example
 var documentsDir;
 function onsuccess(files) {
   for(var i = 0; i < files.length; i++) {
     console.log("File Name is " + files[i].name); // displays file name
   }

   var testFile = documentsDir.createFile("test.txt");
   if (testFile != null) {
     testFile.openStream(
         "w",
         function(fs){
           fs.write("HelloWorld");
           fs.close();
         }, function(e){
           console.log("Error " + e.message);
         }, "UTF-8"
     );
   }
 }

 function onerror(error) {
   console.log("The error " + error.message + " occurred when listing the files in the selected folder");
 }

 webapis.filesystem.resolve(
     'documents',
     function(dir){
       documentsDir = dir; dir.listFiles(onsuccess,onerror);
     }, function(e) {
       console.log("Error" + e.message);
     }, "rw"
 );

readAsText

Reads the content of a file as a DOMString.

Signature
void readAsText(FileStringSuccessCallback onsuccess, optional ErrorCallback? onerror, optional DOMString? encoding);

If the operation is successfully executed, the onsuccess is invoked and a DOMString is passed as input parameter that represents the file content in the format determined by the encoding parameter.

The ErrorCallback is launched with these error types:

  • InvalidValuesError: If any of the input parameters contain an invalid value.
  • IOError: The operation is launched on a directory (not a file), the file is not valid, or the file does not exist.
  • UnknownError: In any other error case.
Parameters
  • onsuccess
    • Optional: No.
    • Nullable: No.
    • Type: FileStringSuccessCallback.
    • Description: Called when the file has been successfully read.
  • onerror
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: If an error occurs while reading the file.
  • encoding
    • Optional: Yes.
    • Nullable: Yes.
    • Type: DOMString.
    • Description: The encoding for read/write operations on the file, at least the following encodings MUST be supported: "UTF-8" default encoding, "ISO-8859-1" latin1 encoding. If no encoding is passed by the developer, then the default platform encoding MUST be used.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

Code example
 function onsuccess(files) {
   for(var i = 0; i < files.length; i++) {
     console.log("File Name is " + files[i].name); // displays file name
     if (files[i].isDirectory == false)
       files[i].readAsText(
           function(str){
             console.log("The file content " + str);
           }, function(e){
             console.log("Error " + e.message);
           }, "UTF-8"
       );
   }
 }

 function onerror(error) {
   console.log("The error " + error.message + " occurred when listing the files in the selected folder");
 }

 var documentsDir;
 webapis.filesystem.resolve(
     'documents', 
     function(dir){
       documentsDir = dir;
       dir.listFiles(onsuccess,onerror);
     }, function(e) {
       console.log("Error" + e.message);
     }, "rw"
 );

copyTo

Copies (and overwrites if possible and specified) a file or a directory from a specified location to another specified location.

Signature
void copyTo(DOMString originFilePath, DOMString destinationFilePath, boolean overwrite, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror);

The copy of the file or directory identified by the originFilePath parameter MUST be created in the path passed in the destinationFilePath parameter.

The file or directory to be copied MUST be under the Directory from which the method is invoked, otherwise the operation MUST NOT be performed.

If the copy is performed successfully, the onsuccess is invoked.

The ErrorCallback is launched with these error types:

  • InvalidValuesError: If any of the input parameters contain an invalid value.
  • NotFoundError: originFilePath does not correspond to a valid file or destinationPath is not a valid path.
  • IOError: The File in which the copyTo method is invoked is a file (not a directory), originFilePath corresponds to a file or directory in use by another process, overwrite parameter is false and destinationFilePath corresponds to an existing file or directory.
  • UnknownError: In any other error case.
Parameters
  • originFilePath
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The origin full virtual file or directory path, it must be under the current directory.
  • destinationFilePath
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The new full virtual file path or directory path.
  • overwrite
    • Optional: No.
    • Nullable: No.
    • Type: boolean.
    • Description: true enforces overwriting an existing file.
  • onsuccess
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: Called when the file has been copied.
  • onerror
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: Called if an error occurred.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

Code example
 var documentsDir;
 function onsuccess(files) {
   for(var i = 0; i < files.length; i++) {
     if (files[i].isDirectory == false)
       documentsDir.copyTo(files[i].fullPath,
                           "images/backup/"+files[i].name,
                           false,
                           function(){console.log("file copied");});
   }
 }

 function onerror(error) {
   console.log("The error " + error.message +
               " occurred when listing the files in the selected folder");
 }

 webapis.filesystem.resolve(
     'documents', 
     function(dir){
       documentsDir = dir;
       dir.listFiles(onsuccess, onerror);
     }, function(e) {
       console.log("Error" + e.message);
     }, "rw"
 );

moveTo

Moves a file or a directory from a specified location to another.

Signature
void moveTo(DOMString originFilePath, DOMString destinationFilePath, boolean overwrite, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror);

The file or directory will be moved (and will overwrite if possible and specified) atomically to the given path. This operation is different from instantiating copyTo and then deleting the original file, as on certain platforms, this operation does not require extra disk space.

The file or directory identified by the originFilePath parameter MUST be moved to the path passed in the destinationFilePath parameter.

The file to be moved MUST be under the Directory from which the method is invoked, otherwise the operation MUST NOT be performed.

If the file or directory is moved successfully, the onsuccess is invoked.

The ErrorCallback is launched with these error types:

  • InvalidValuesError: If any of the input parameters contain an invalid value.
  • NotFoundError: originFilePath does not correspond to a valid file or destinationPath is not a valid path.
  • IOError: The File in which the moveTo method is invoked is a file (not a directory), originFilePath corresponds to a file or directory in use by another process, overwrite parameter is false and destinationFilePath corresponds to an existing file or directory.
  • UnknownError: In any other error case.
Parameters
  • originFilePath
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The origin full virtual file or directory path, it must be under the current directory.
  • destinationFilePath
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The new full virtual file path or directory path.
  • overwrite
    • Optional: No.
    • Nullable: No.
    • Type: boolean.
    • Description: true enforces overwriting an existing file.
  • onsuccess
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: Called when the file has been moved.
  • onerror
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: Called if an error occurred.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

Code example
 var documentsDir;
 function onsuccess(files) {
   for(var i = 0; i < files.length; i++) {
     if (files[i].isDirectory == false)
       documentsDir.moveTo(files[i].fullPath,
                           "images/newFolder/"+files[i].name,
                           false,
                           function(){console.log("file moved");});
   }
 }

 function onerror(error) {
   console.log("The error " + error.message +
               " occurred during listing the files in the selected folder");
 }

 webapis.filesystem.resolve(
     'documents', 
     function(dir){
       documentsDir = dir;
       dir.listFiles(onsuccess, onerror);
     }, function(e) {
       console.log("Error" + e.message);
     }, "rw"
 );

createDirectory

Creates a new directory.

Signature
File createDirectory(DOMString dirPath);

A new directory will be created relative to the current directory that this operation is performed on. The implementation will attempt to create all necessary sub-directories specified in the dirPath, as well. The use of "." or ".." in path components is not supported.

This operation can only be performed on file handlers that represent a directory (that is, isDirectory == true).

If the directory is successfully created, it will be returned.

In case the directory cannot be created, an error MUST be thrown with the appropriate error type.

Parameters
  • dirPath
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The relative directory path, it should only contain characters supported by the underlying filesystem.
Return value
File The file handle of the new directory. The new File object will have "rw" access rights, as it inherits this from the File object on which the createDirectory() method is called.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

    with error type InvalidValuesError, if the dirPath does not contain a valid path.

    with error type IOError, if the dirPath already exists.

Code example
 var newDir = dir.createDirectory("newDir");
 var anotherNewDir = dir.createDirectory("newDir1/subNewDir1");

createFile

Creates a new empty file in a specified location.

Signature
File createFile(DOMString relativeFilePath);

A new empty file is created in the given path relative to the directory indicated by currrent 'File' object's 'path' attribute. The use of "." or ".." in path components is not supported. This operation can only be performed on file handlers that represent a directory (that is, isDirectory == true).

If the file is successfully created, a file handler MUST be returned by this method.

In case the file cannot be created, an error MUST be thrown with the appropriate error type.

Parameters
  • relativeFilePath
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The new file path, it should only contain characters supported by the underlying filesystem.
Return value
File The file handle of the new empty file. The new File object will have "rw" access rights, as it inherits this from the File object on which the createFile() method is called.
Exceptions
  • WebAPIException:

    with error type UnknownError, in any other error case.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

    with error type InvalidValuesError, if the filePath contains an invalid value.

    with error type IOError, if the filePath already exists.

Code example
 var newFile = dir.createFile("newFilePath");

resolve

Resolves an existing file or directory relative to the current directory this operation is performed on, and returns a file handle for it.

Signature
File resolve(DOMString filePath);

The filePath is not allowed to contain the "." or ".." directories.

The encoding of file paths is UTF-8.

Parameters
  • filePath
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The relative file/directory path/file URI to resolve.
Return value
File The file handle of the file. The new File object will inherit its access rights from the File object on which this resolve() method is called.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type NotFoundError, if a file does not exist for the passed file path.

    with error type IOError, if the method is executed in a File object that does not represent a directory (that is, isDirectory attribute is false).

    with error type InvalidValuesError, if the file path contains an invalid value.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

Code example
 var file;
 // Resolves helloWorld.doc file that is located in the
 // documents root location
 webapis.filesystem.resolve(
   'documents', 
   function(dir){ file = dir.resolve("helloWorld.doc");},
   function(e){ console.log("Error" + e.message);},
   "rw");

deleteDirectory

Deletes a specified directory and directory tree if specified.

Signature
void deleteDirectory(DOMString directoryPath, boolean recursive, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror);

This function attempts to asynchronously delete a directory or directory tree under the current directory.

If the recursive parameter is set to true, all the directories and files under the specified directory MUST be deleted. If the recursive parameter is set to false, the directory will only be deleted if it is empty, otherwise an IOError error type will be passed in onerror.

The directory to be deleted MUST be under the Directory that the method is invoked from, otherwise the operation MUST NOT be performed. If the deletion is performed successfully, the onsuccess is invoked.

The ErrorCallback is launched with these error types:

  • InvalidValuesError: If any of the input parameters contain an invalid value.
  • NotFoundError: The passed directory does not correspond to a valid directory.
  • IOError: The File in which the delete method is invoked is a file (not a directory), the directory is in use by another process or the directory is not empty and recursive argument is false. This code will be also used if a recursive deletion partially fails and any data deleted so far cannot be recovered. This may occur due to the lack of filesystem permissions or if any directories or files are opened by other processes.
  • UnknownError: In any other error case.
Parameters
  • directoryPath
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The full virtual path to the directory to be deleted (must be under the current one).
  • recursive
    • Optional: No.
    • Nullable: No.
    • Type: boolean.
    • Description: true means a recursive deletion. This will delete all data in all subdirectories. Use with caution.
  • onsuccess
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: Called if the directory is successfully deleted.
  • onerror
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: Called if an error occurred.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

Code example
 var documentsDir;
 function onsuccess(files) {
   for(var i = 0; i < files.length; i++) {
     if (files[i].isDirectory) {
       documentsDir.deleteDirectory(
           files[i].fullPath,
           false,
           function(){
             console.log("Directory Deleted");
           }, function(e) {
             console.log("Error" + e.message);
           });
     } else {
       documentsDir.deleteFile(
           files[i].fullPath,
           function(){
             console.log("File Deleted");
           }, function(e) {
             console.log("Error" + e.message);
           });
     }
   }
 }

 function onerror(error) {
   console.log("The error " + error.message + " occurred when listing the files in the selected folder");
 }

 webapis.filesystem.resolve(
     'documents', 
     function(dir){
       documentsDir = dir;
       dir.listFiles(onsuccess,onerror);
     }, function(e) {
       console.log("Error" + e.message);
     }, "rw"
 );

deleteFile

Deletes a specified file.

Signature
void deleteFile(DOMString filePath, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror);

This function attempts to asynchronously delete a file under the current directory.

The file to be deleted MUST be under the Directory from which the method is invoked, otherwise the operation MUST NOT be performed.

If the deletion is performed successfully, the onsuccess is invoked.

The ErrorCallback is launched with these error types:

  • InvalidValuesError: If any of the input parameters contain an invalid value.
  • NotFoundError: The file does not correspond to a valid file.
  • IOError: The file in which the delete method is invoked is a directory (not a file), the file is in use by another process, or there is no permission in the file system.
  • UnknownError: In any other error case.
Parameters
  • filePath
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The full virtual path to the file to be deleted (must be under the current directory).
  • onsuccess
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: Called if the file is successfully deleted.
  • onerror
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: Called if an error occurred.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

Code example
 function onsuccess(files) {
   for(var i = 0; i < files.length; i++) {
     if (files[i].isDirectory) {
       documentsDir.deleteDirectory(
           files[i].fullPath,
           false,
           function(){
             console.log("Directory Deleted");
           }, function(e) {
             console.log("Error" + e.message);
           });
     } else {
       documentsDir.deleteFile(
           files[i].fullPath,
           function(){
             console.log("File Deleted");
           }, function(e) {
             console.log("Error" + e.message);
           });
     }
   }
 }

 function onerror(error) {
   console.log("The error " + error.message + " occurred when listing the files in the selected folder");
 }

 var documentsDir;
 webapis.filesystem.resolve(
   'documents', 
   function(dir){
     documentsDir = dir;
     dir.listFiles(onsuccess,onerror);
   }, function(e){
     console.log("Error" + e.message);
   }, "rw"
 );

2.5. FileFilter

Dictionary created to filter the items returned by the listFiles method. 

  dictionary FileFilter {
    DOMString name;

    Date startModified;

    Date endModified;

    Date startCreated;

    Date endCreated;
  };

When this dictionary is passed in the listFiles method, the result-set of the listFiles method MUST only contain the file items entries that match the attribute values of the filter. The result set of the listFiles method does not guarantee any sort order.

A file item only matches the FileFilter object if all the attributes of the file item match all the attribute values of the filter which are defined (that is, only matching values other than undefined or null). This is similar to an SQL "AND" operation.

An attribute of the file entry matches the FileFilter attribute value in accordance with the following rules:

  • For FileFilter attributes of type DOMString, an entry matches this value only if its corresponding attribute is an exact match. If the filter contains U+0025 'PERCENT SIGN' it is interpreted as a wildcard character and '%' matches any string of any length, including no length. If wildcards are used, the behavior is similar to the LIKE condition in SQL. To specify that a 'PERCENT SIGN' character is to be considered literally instead of interpreting it as a wildcard, developers may escape it with the backslash character (\). The matching is not case sensitive, such as "FOO" matches a "foo" or an "f%" filter.
  • For File entry attributes of type Date, attributes start and end are included to allow filtering of File entries between two supplied dates. If either or both of these attributes are specified, the following rules apply: A) If both start and end dates are specified (that is, other than null), a File entry matches the filter if it's corresponding attribute is the same as either start or end or between the two supplied dates (that is, after start and before end). B) If only the start attribute contains a value (other than null), a File entry matches the filter if its corresponding attribute is later than or equal to the start one. C) If only the end date contains a value (other than null), a file matches the filter if its corresponding attribute is earlier than or equal to the end date.

Dictionary members

DOMString name

Used for filtering the File name attribute.

Files which name corresponds with this attribute (either exactly or with the specified wildcards) match this filtering criteria.

Date startModified

Used for filtering the File modified attribute.

Files with modified date later than this attribute or equal to it match the filtering criteria.

Date endModified

Used for filtering the File created attribute.

Files with modified date earlier than this attribute or equal to it match the filtering criteria.

Date startCreated

Used for filtering the File created attribute.

Files with created date later than this attribute or equal to it match the filtering criteria.

Date endCreated

Used for filtering the File created attribute.

Files with created date earlier than this attribute or equal to it match the filtering criteria.

2.6. FileStream

FileStream API. 

  [NoInterfaceObject] interface FileStream {
    readonly attribute boolean eof;

    attribute long position setraises(WebAPIException);

    readonly attribute long bytesAvailable;

    void close();

    DOMString read(long charCount) raises(WebAPIException);

    octet[] readBytes(long byteCount) raises(WebAPIException);

    DOMString readBase64(long byteCount) raises(WebAPIException);

    void write(DOMString stringData) raises(WebAPIException);

    void writeBytes(octet[] byteData) raises(WebAPIException);

    void writeBase64(DOMString base64Data) raises(WebAPIException);
  };

A FileStream represents a handle to a File opened for read and/or write operations. Read and write operations are performed relative to a position attribute, which is a pointer that represents the current position in the file.

A series of read/write methods are available that permit both binary and text to be processed.

Once a file stream is closed, any operation attempted on this stream will result in a standard JavaScript error.

The read/write operations in this interface do not throw any security exceptions as the access rights are expected to be granted through the initial resolve() method or through the openStream() method of the File interface. Therefore, all actions performed on a successfully resolved File and FileStream are expected to succeed. This avoids successive asynchronous calls and may potentially increase application for a user.

ATTRIBUTES

readonly boolean eof

Indicates whether or not the current file pointer is at the end of the file.

If true, this attribute indicates that the file pointer is at the end of the file.

If false, this attribute indicates that the file pointer is not at the end of the file and may be anywhere within the file.

This attribute is read-only.
Code example
 if(stream.eof) {
   // file has been read completely
 }

long position

Gets/sets stream position for reads/writes.

The stream position is 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 byte defined by this position attribute. If the read or write operation is successful, the position of the stream is advanced by the number of bytes read or written. If the read/write operation is not successful, the position of the stream is unchanged.

Code example
 console.log(stream.position); // displays current stream position
 // alters current stream position to the begin of the file,
 // like seek() in C
 stream.position = 0;

readonly long bytesAvailable

Returns the number of bytes that are available for reading from the stream.

The number of bytes available for reading is the maximum amount of bytes that can be read in the next read operation. It corresponds to the number of bytes available after the file pointer denoted by the position attribute.

-1 if eof is true.

This attribute is read-only.
Code example
 console.log(stream.bytesAvailable); // displays the available bytes to be read

METHODS

close

Closes this FileStream.

Signature
void close();

Flushes any pending buffered writes and closes the File. Always succeeds. Note that pending writes might not succeed.

Code example
 stream.close(); // closes this stream, no subsequent access to stream allowed

read

Reads the specified number of characters from this FileStream.

Signature
DOMString read(long charCount);

Reads the specified number of characters after the position file pointer and returns them as a string. The resulting string length might be shorter than charCount if eof is true.

Parameters
  • charCount
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Number of characters being read.
Return value
DOMString The result of read characters as a string.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

    with error type IOError, if a read error occurs, such as the bytes in the stream cannot be decoded with the encoding in use.

Code example
 var text = stream.read(file.fileSize);
 stream.close();

readBytes

Reads the specified number of bytes from this FileStream.

Signature
octet[] readBytes(long byteCount);
Parameters
  • byteCount
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Number of bytes being read.
Return value
octet[] The result of read bytes as a byte (or number) array.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

    with error type IOError, if a read error occurs.

Code example
 // reads up to 256 bytes from the stream
 var raw = stream.readBytes(256);
 for(var i = 0; i < raw.length; i++) {
   // raw[i] contains the i-th byte of the current data chunk
 }

readBase64

Reads the specified number of bytes from this FileStream, encoding the result in base64.

Signature
DOMString readBase64(long byteCount);
Parameters
  • byteCount
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Number of bytes being read.
Return value
DOMString The result of read bytes as base64 encoding string.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

    with error type IOError, if a read error occurs.

Code example
 // reads up to 256 bytes from the stream
 var base64 = stream.readBase64(256);

write

Writes the specified DOMString to this FileStream.

Signature
void write(DOMString stringData);
Parameters
  • stringData
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The actual string to be written.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

    with error type IOError, if a write error occurs.

Code example
 var text = "Hello world";
 stream.write(text);

writeBytes

Writes the specified bytes to this FileStream.

Signature
void writeBytes(octet[] byteData);
Parameters
  • byteData
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: The byte data array being written.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

    with error type IOError, if a write error occurs.

Code example
 var bytes = in.readBytes(256);
 out.writeBytes(bytes); // writes the bytes read from in to out

writeBase64

Converts the specified base64 DOMString to bytes and writes the result to this FileStream.

Signature
void writeBase64(DOMString base64Data);
Parameters
  • base64Data
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The base64 data being written.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

    with error type IOError, if an error occurs during writeBase64.

Code example
 var base64 = in.readBase64(256);
 out.writeBase64(base64); // writes the base64 data read from in to out

2.7. FileSuccessCallback

The file system specific success callback. 

  [Callback=FunctionOnly, NoInterfaceObject] interface FileSuccessCallback {
    void onsuccess(File file);
  };

This callback interface specifies a success callback with a File object as input argument. It is used in asynchronous operations, such as FileSystemManager.resolve() and copying, moving, and deleting files.

METHODS

onsuccess

The method invoked when the asynchronous call completes successfully.

Signature
void onsuccess(File file);
Parameters
  • file
    • Optional: No.
    • Nullable: No.
    • Type: File.
    • Description: The file resulting from the asynchronous call.

2.8. FileSystemStorageArraySuccessCallback

The success callback to retrieve FileSystemStorage objects. 

  [Callback=FunctionOnly, NoInterfaceObject] interface FileSystemStorageArraySuccessCallback {
    void onsuccess(FileSystemStorage[] storages);
  };

This callback interface specifies a success callback with an array of FileSystemStorage objects as input argument. It is used in asynchronous operations, such as FileSystemManager.listStorages().

METHODS

onsuccess

The method invoked when the asynchronous call completes successfully.

Signature
void onsuccess(FileSystemStorage[] storages);
Parameters
  • storages
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: List of available storage devices.

2.9. FileSystemStorageSuccessCallback

The success callback to retrieve a FileSystemStorage object. 

  [Callback=FunctionOnly, NoInterfaceObject] interface FileSystemStorageSuccessCallback {
    void onsuccess(FileSystemStorage storage);
  };

This callback interface specifies a success callback with a FileSystmeStorage object as input argument. It is used in asynchronous operations, such as FileSystemManager.getStorage() and FileSystemManager.addStorageStateChangeListener().

METHODS

onsuccess

The method invoked when the asynchronous call completes successfully.

Signature
void onsuccess(FileSystemStorage storage);
Parameters
  • storage
    • Optional: No.
    • Nullable: No.
    • Type: FileSystemStorage.
    • Description: The storage device structure.

2.10. FileStringSuccessCallback

The success callback to read the content of a file as a DOMString. 

  [Callback=FunctionOnly, NoInterfaceObject] interface FileStringSuccessCallback {
    void onsuccess(DOMString fileStr);
  };

This callback interface specifies a success callback with a DOMString object as input argument. It is used in asynchronous operations, such as File.readAsText().

METHODS

onsuccess

The method invoked when the asynchronous call completes successfully.

Signature
void onsuccess(DOMString fileStr);
Parameters
  • fileStr
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The file represented as a DOMString resulting from the asynchronous call.

2.11. FileStreamSuccessCallback

The success callback to open a file for raw access. 

  [Callback=FunctionOnly, NoInterfaceObject] interface FileStreamSuccessCallback {
    void onsuccess(FileStream filestream);
  };

This callback interface specifies a success callback with a FileStream object as input argument. It is used by asynchronous methods, such as File.openStream().

METHODS

onsuccess

The method invoked when the File.openStream asynchronous call completes successfully.

Signature
void onsuccess(FileStream filestream);
Parameters
  • filestream
    • Optional: No.
    • Nullable: No.
    • Type: FileStream.
    • Description: The filestream to access file content.

2.12. FileArraySuccessCallback

The file system specific success callback for listing methods. 

  [Callback=FunctionOnly, NoInterfaceObject] interface FileArraySuccessCallback {
    void onsuccess(File[] files);
  };

This callback interface specifies a success callback with a function taking an array of File objects as input argument. It is used in asynchronous methods, such as File.listFiles().

METHODS

onsuccess

The method invoked when the asynchronous call completes successfully.

Signature
void onsuccess(File[] files);
Parameters
  • files
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: The files resulting from the asynchronous call.

3. Full WebIDL 

module Filesystem {
  enum FileMode { "r", "rw", "w", "a" };
  
  enum FileSystemStorageType { "INTERNAL", "EXTERNAL" };
  
  enum FileSystemStorageState { "MOUNTED", "REMOVED", "UNMOUNTABLE" };
  
  [NoInterfaceObject] interface FileSystemManagerObject {
    readonly attribute FileSystemManager filesystem;
  };
  WebAPIs implements FileSystemManagerObject;

  [NoInterfaceObject] interface FileSystemManager {
    readonly attribute long maxPathLength;

    void resolve(DOMString location,
                 FileSuccessCallback onsuccess,
                 optional ErrorCallback? onerror,
                 optional FileMode? mode) raises(WebAPIException);

    void getStorage(DOMString label,
                    FileSystemStorageSuccessCallback onsuccess,
                    optional ErrorCallback? onerror) raises(WebAPIException);

    void listStorages(FileSystemStorageArraySuccessCallback onsuccess,
                      optional ErrorCallback? onerror) raises(WebAPIException);

    long addStorageStateChangeListener(FileSystemStorageSuccessCallback onsuccess,
                                       optional ErrorCallback? onerror) raises(WebAPIException);

    void removeStorageStateChangeListener(long watchId) raises(WebAPIException);
  };

  [NoInterfaceObject] interface FileSystemStorage {
    readonly attribute DOMString label;

    readonly attribute FileSystemStorageType type;

    readonly attribute FileSystemStorageState state;
  };

  [NoInterfaceObject] interface File {
    readonly attribute File? parent;

    readonly attribute boolean readOnly;

    readonly attribute boolean isFile;

    readonly attribute boolean isDirectory;

    readonly attribute Date? created;

    readonly attribute Date? modified;

    readonly attribute DOMString path;

    readonly attribute DOMString name;

    readonly attribute DOMString fullPath;

    readonly attribute unsigned long long fileSize;

    readonly attribute long length;

    DOMString toURI() raises(WebAPIException);

    void listFiles(FileArraySuccessCallback onsuccess,
                   optional ErrorCallback? onerror,
                   optional FileFilter? filter) raises(WebAPIException);

    void openStream(FileMode mode,
                    FileStreamSuccessCallback onsuccess,
                    optional ErrorCallback? onerror,
                    optional DOMString? encoding) raises(WebAPIException);

    void readAsText(FileStringSuccessCallback onsuccess,
                    optional ErrorCallback? onerror,
                    optional DOMString? encoding) raises(WebAPIException);

    void copyTo(DOMString originFilePath,
                DOMString destinationFilePath,
                boolean overwrite,
                optional SuccessCallback? onsuccess,
                optional ErrorCallback? onerror) raises(WebAPIException);

    void moveTo(DOMString originFilePath,
                DOMString destinationFilePath,
                boolean overwrite,
                optional SuccessCallback? onsuccess,
                optional ErrorCallback? onerror) raises(WebAPIException);

    File createDirectory(DOMString dirPath) raises(WebAPIException);

    File createFile(DOMString relativeFilePath) raises(WebAPIException);

    File resolve(DOMString filePath) raises(WebAPIException);

    void deleteDirectory(DOMString directoryPath,
                         boolean recursive,
                         optional SuccessCallback? onsuccess,
                         optional ErrorCallback? onerror) raises(WebAPIException);

    void deleteFile(DOMString filePath,
                    optional SuccessCallback? onsuccess,
                    optional ErrorCallback? onerror) raises(WebAPIException);
  };


  dictionary FileFilter {
    DOMString name;

    Date startModified;

    Date endModified;

    Date startCreated;

    Date endCreated;
  };

  [NoInterfaceObject] interface FileStream {
    readonly attribute boolean eof;

    attribute long position setraises(WebAPIException);

    readonly attribute long bytesAvailable;

    void close();

    DOMString read(long charCount) raises(WebAPIException);

    octet[] readBytes(long byteCount) raises(WebAPIException);

    DOMString readBase64(long byteCount) raises(WebAPIException);

    void write(DOMString stringData) raises(WebAPIException);

    void writeBytes(octet[] byteData) raises(WebAPIException);

    void writeBase64(DOMString base64Data) raises(WebAPIException);
  };

  [Callback=FunctionOnly, NoInterfaceObject] interface FileSuccessCallback {
    void onsuccess(File file);
  };

  [Callback=FunctionOnly, NoInterfaceObject] interface FileSystemStorageArraySuccessCallback {
    void onsuccess(FileSystemStorage[] storages);
  };

  [Callback=FunctionOnly, NoInterfaceObject] interface FileSystemStorageSuccessCallback {
    void onsuccess(FileSystemStorage storage);
  };

  [Callback=FunctionOnly, NoInterfaceObject] interface FileStringSuccessCallback {
    void onsuccess(DOMString fileStr);
  };

  [Callback=FunctionOnly, NoInterfaceObject] interface FileStreamSuccessCallback {
    void onsuccess(FileStream filestream);
  };

  [Callback=FunctionOnly, NoInterfaceObject] interface FileArraySuccessCallback {
    void onsuccess(File[] files);
  };
};