DirectoryEntry

This object represents a directory on a file system. It is defined in the W3C Directories and Systems specification.

Properties

• isFile: Always false. (boolean)
• isDirectory: Always true. (boolean)
• name: The name of the DirectoryEntry, excluding the path leading to it. (DOMString)
• fullPath: The full absolute path from the root to the DirectoryEntry. (DOMString)

NOTE: The following attributes are defined by the W3C specification, but are not supported by Cordova:

• filesystem: The file system on which the DirectoryEntry resides. (FileSystem)

Methods

The following methods can be invoked on a DirectoryEntry object:

• getMetadata: Look up metadata about a directory.
• setMetadata: Set metadata on a directory.
• moveTo: Move a directory to a different location on the file system.
• copyTo: Copy a directory to a different location on the file system.
• toURL: Return a URL that can be used to locate a directory.
• remove: Delete a directory. The directory must be empty.
• getParent: Look up the parent directory.
• createReader: Create a new DirectoryReader that can read entries from a directory.
• getDirectory: Create or look up a directory.
• getFile: Create or look up a file.
• removeRecursively: Delete a directory and all of its contents.

Supported Platforms

• Android
• BlackBerry WebWorks (OS 5.0 and higher)
• iOS
• Windows Phone 7 and 8
• Windows 8

getMetadata

Look up metadata about a directory.

Parameters:

• successCallback - A callback that is called with a Metadata object. (Function)
• errorCallback - A callback that is called if an error occurs retrieving the Metadata. Invoked with a FileError object. (Function)

Quick Example

function success(metadata) {
    console.log("Last Modified: " + metadata.modificationTime);
}

function fail(error) {
    alert(error.code);
}

// Request the metadata object for this entry
entry.getMetadata(success, fail);

setMetadata

Set metadata on a directory. Only works on iOS currently - this will set the extended attributes of a directory.

Parameters:

• successCallback - A callback that is called when the metadata was successfully set. (Function)
• errorCallback - A callback that is called when the metadata was not successfully set. (Function)
• metadataObject - An object that contains the metadata keys and values. (Object)

Quick Example

function success() {
    console.log("The metadata was successfully set.");
}

function fail() {
    alert("There was an error in setting the metadata");
}

// Set the metadata
entry.setMetadata(success, fail, { "com.apple.MobileBackup": 1}); __iOS Quirk__

• only the "com.apple.MobileBackup" extended attribute is supported. Set the value to 1 to NOT enable the directory to be backed up by iCloud. Set the value to 0 to re-enable the directory to be backed up by iCloud.

Quick Example

function setFolderMetadata(localFileSystem, subFolder, metadataKey, metadataValue) 
{
    var onSetMetadataWin = function() {
      console.log("success setting metadata")
    }
    var onSetMetadataFail = function() {
      console.log("error setting metadata")
    }

    var onGetDirectoryWin = function(parent) {
      var data = {};
      data[metadataKey] = metadataValue;
      parent.setMetadata(onSetMetadataWin, onSetMetadataFail, data);
    }
    var onGetDirectoryFail = function() {
      console.log("error getting dir")
    }

    var onFSWin = function(fileSystem) {
      fileSystem.root.getDirectory(subFolder, {create: true, exclusive: false}, onGetDirectoryWin, onGetDirectoryFail);
    }

    var onFSFail = function(evt) {
	  console.log(evt.target.error.code);
    }

    window.requestFileSystem(localFileSystem, 0, onFSWin, onFSFail);
}

setFolderMetadata([LocalFileSystem](../localfilesystem/localfilesystem.html).PERSISTENT, "Backups", "com.apple.MobileBackup", 1);

moveTo

Move a directory to a different location on the file system. It is an error to attempt to:

• move a directory inside itself or to any child at any depth;
• move a directory into its parent if a name different from its current one is not provided;
• move a directory to a path occupied by a file;
• move a directory to a path occupied by a directory which is not empty.

In addition, an attempt to move a directory on top of an existing empty directory must attempt to delete and replace that directory.

Parameters:

• parent - The parent directory to which to move the directory. (DirectoryEntry)
• newName - The new name of the directory. Defaults to the current name if unspecified. (DOMString)
• successCallback - A callback that is called with the DirectoryEntry object of the new directory. (Function)
• errorCallback - A callback that is called if an error occurs when attempting to move the directory. Invoked with a FileError object. (Function)

Quick Example

function success(entry) {
    console.log("New Path: " + entry.fullPath);
}

function fail(error) {
    alert(error.code);
}

function moveDir(entry) {
    var parent = document.getElementById('parent').value,
        parentName = parent.substring(parent.lastIndexOf('/')+1),
        newName = document.getElementById('newName').value,
        parentEntry = new DirectoryEntry(parentName, parent);

    // move the directory to a new directory and rename it
    entry.moveTo(parentEntry, newName, success, fail);
}

copyTo

Copy a directory to a different location on the file system. It is an error to attempt to:

• copy a directory inside itself at any depth;
• copy a directory into its parent if a name different from its current one is not provided.

Directory copies are always recursive - that is, they copy all contents of the directory.

Parameters:

• parent - The parent directory to which to copy the directory. (DirectoryEntry)
• newName - The new name of the directory. Defaults to the current name if unspecified. (DOMString)
• successCallback - A callback that is called with the DirectoryEntry object of the new directory. (Function)
• errorCallback - A callback that is called if an error occurs when attempting to copy the underlying directory. Invoked with a FileError object. (Function)

Quick Example

function win(entry) {
	console.log("New Path: " + entry.fullPath);
}

function fail(error) {
	alert(error.code);
}

function copyDir(entry) {
    var parent = document.getElementById('parent').value,
        parentName = parent.substring(parent.lastIndexOf('/')+1),
        newName = document.getElementById('newName').value,
        parentEntry = new DirectoryEntry(parentName, parent);

    // copy the directory to a new directory and rename it
    entry.copyTo(parentEntry, newName, success, fail);
}

toURL

Returns a URL that can be used to locate the directory.

Quick Example

// Get the URL for this directory
var dirURL = entry.toURL();
console.log(dirURL);

remove

Deletes a directory. It is an error to attempt to:

• delete a directory that is not empty;
• delete the root directory of a filesystem.

Parameters:

• successCallback - A callback that is called after the directory has been deleted. Invoked with no parameters. (Function)
• errorCallback - A callback that is called if an error occurs when attempting to delete the directory. Invoked with a FileError object. (Function)

Quick Example

function success(entry) {
    console.log("Removal succeeded");
}

function fail(error) {
    alert('Error removing directory: ' + error.code);
}

// remove this directory
entry.remove(success, fail);

getParent

Look up the parent DirectoryEntry containing the directory.

Parameters:

• successCallback - A callback that is called with the directory's parent DirectoryEntry. (Function)
• errorCallback - A callback that is called if an error occurs when attempting to retrieve the parent DirectoryEntry. Invoked with a FileError object. (Function)

Quick Example

function success(parent) {
    console.log("Parent Name: " + parent.name);
}

function fail(error) {
    alert('Failed to get parent directory: ' + error.code);
}

// Get the parent DirectoryEntry
entry.getParent(success, fail);

createReader

Creates a new DirectoryReader to read entries in a directory.

Quick Example

// create a directory reader
var directoryReader = entry.createReader();

getDirectory

Creates or looks up an existing directory. It is an error to attempt to:

• create a directory whose immediate parent does not yet exist.

Parameters:

• path - The path to the directory to be looked up or created. Either an absolute path, or a relative path from this DirectoryEntry. (DOMString)
• options - Options to specify whether the directory is created if it doesn't exist. (Flags)
• successCallback - A callback that is invoked with a DirectoryEntry object. (Function)
• errorCallback - A callback that is called if an error occurs creating or looking up the directory. Invoked with a FileError object. (Function)

Quick Example

function success(parent) {
    console.log("Parent Name: " + parent.name);
}

function fail(error) {
    alert("Unable to create new directory: " + error.code);
}

// Retrieve an existing directory, or create it if it does not already exist
entry.getDirectory("newDir", {create: true, exclusive: false}, success, fail);

getFile

Creates or looks up a file. It is an error to attempt to:

• create a file whose immediate parent does not yet exist.

Parameters:

• path - The path to the file to be looked up or created. Either an absolute path, or a relative path from this DirectoryEntry. (DOMString)
• options - Options to specify whether the file is created if it doesn't exist. (Flags)
• successCallback - A callback that is invoked with a FileEntry object. (Function)
• errorCallback - A callback that is called if an error occurs creating or looking up the file. Invoked with a FileError object. (Function)

Quick Example

function success(parent) {
    console.log("Parent Name: " + parent.name);
}

function fail(error) {
    alert("Failed to retrieve file: " + error.code);
}

// Retrieve an existing file, or create it if it does not exist
entry.getFile("newFile.txt", {create: true, exclusive: false}, success, fail);

removeRecursively

Deletes a directory and all of its contents. In the event of an error (e.g. trying to delete a directory that contains a file that cannot be removed), some of the contents of the directory may be deleted. It is an error to attempt to:

• delete the root directory of a filesystem.

Parameters:

• successCallback - A callback that is called after the DirectoryEntry has been deleted. Invoked with no parameters. (Function)
• errorCallback - A callback that is called if an error occurs when attempting to delete the DirectoryEntry. Invoked with a FileError object. (Function)

Quick Example

function success(parent) {
    console.log("Remove Recursively Succeeded");
}

function fail(error) {
    alert("Failed to remove directory or it's contents: " + error.code);
}

// remove the directory and all it's contents
entry.removeRecursively(success, fail);

BlackBerry Quirks

May fail with a ControlledAccessException in the following cases:

• Access is attempted on an directory created by a previous installation of an application.

solution: insure temporary directories are cleaned manually, or by the application before reinstall

• if device is connected by usb

solution: disconnect usb cable from device and run again