DirectoryEntry

The DirectoryEntry interface of the FileSystem API represents a directory in a file system. It includes methods for creating, reading, looking up, and recursively removing files in a directory.

About this document

This document was last updated on March 2, 2012, and follows the W3C Specifications (Working Draft) drafted on April 19, 2011.

This specification is abandoned, having failed to reach any substantial traction.

Basic concepts

You can create a new directory by calling DirectoryEntry.getDirectory(). If you want to create subdirectories, create each child directory in sequence. If you try creating a directory using a full path that includes parent directories that do not exist yet, an error is returned. So create the hierarchy by recursively adding a new path after creating the parent directory.

Example

In the following code snippet, we create a directory called "Documents."

// Taking care of the browser-specific prefixes.
window.requestFileSystem  = window.requestFileSystem || window.webkitRequestFileSystem; 
window.directoryEntry = window.directoryEntry || window.webkitDirectoryEntry;

...

function onFs(fs){
  fs.root.getDirectory('Documents', {create:true}, function(directoryEntry){
    //directoryEntry.isFile === false
    //directoryEntry.isDirectory === true
    //directoryEntry.name === 'Documents'
    //directoryEntry.fullPath === '/Documents'
    
    }, onError);

  }

// Opening a file system with temporary storage
window.requestFileSystem(TEMPORARY, 1024*1024 /*1MB*/, onFS, onError);

Method overview

Methods

createReader()

Creates a new DirectoryReader to read entries from this directory. 

DirectoryReader createReader ();

Returns

DirectoryReader

getFile()

Depending on how you've set the options parameter, this method either creates a file or looks up an existing file.

void getFile (
  in DOMString path, in optional Flags options, in optional EntryCallback successCallback, in optional ErrorCallback errorCallback
);

Parameter

path

Either an absolute path or a relative path from the directory to the file to be looked up or created. You cannot create a file whose immediate parent does not exist. Create the parent directory first.

options

An object literal describing the behavior of the method. If the file does not exist, it is created.

successCallback

A callback that is called to return the file selected or created.

errorCallback

A callback that is called when errors occur.

Returns

void

getDirectory()

Creates or looks up a directory. The methods are similar to getFile() with DirectoryEntry being passed in the success callback.

void getDirectory (
  in DOMString path, in optional Flags options, in optional EntryCallback successCallback, in optional ErrorCallback errorCallback
);

Parameter

path

Either an absolute path or a relative path from the DirectoryEntry to the directory to be looked up or created. It is an error to attempt to create a file whose immediate parent does not yet exist.

options

An object literal describing the behavior of the method if the directory does not exist.

successCallback

A callback that is called to return the directory selected or created.

errorCallback

A callback that is called when errors happen.

Returns

void

removeRecursively()

Deletes a directory and all of its contents. You cannot delete the root directory of a file system.

If you delete a directory containing a file that cannot be removed or if an error occurs while the deletion is in progress, some of the contents might not be deleted. Catch these cases with error callbacks and retry the deletion.

DOMString removeRecursively (
  in VoidCallback successCallback, optional ErrorCallback errorCallback
);

Parameter

successCallback

A callback that is called when the deletion succeeds.

errorCallback

A callback that is called when errors happen.

Returns

void

Browser compatibility

See also

Specification: File API: Directories and System SpecificationWD

Reference: File System API

Introduction: Basic Concepts About the File System API