DirectoryEntry

This object represents a directory on a file system, as defined by 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 attribute is defined by the W3C specification, but is not supported:

• 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 to help locate a directory.

• remove: Delete a directory. The directory must be empty.

• getParent: Look up the parent directory.

• createReader: Create a new [DirectoryReader](../directoryreader/directoryreader.html) 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 function to execute with a [Metadata](../metadata/metadata.html) object. (Function)

• errorCallback: A callback function to execute if an error occurs when retrieving the [Metadata](../metadata/metadata.html). Invoked with a [FileError](../fileerror/fileerror.html) 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

Sets a directory's extended attributes, or metadata. Currently works only on iOS.

Parameters:

• successCallback: A callback that executes when the metadata is successfully set. (Function)

• errorCallback: A callback that executes when the metadata fails to be set. (Function)

• metadataObject: An object that contains the metadata's 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 prevent the directory from being backed up to iCloud. Set the value to 0 to re-enable the directory to be backed up to 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.PERSISTENT, "Backups", "com.apple.MobileBackup", 1);

moveTo

Move a directory to a different location on the file system. An error results if the app attempts 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 directory is not provided.

• move a directory to a path occupied by a file.

• move a directory to a path occupied by a directory that is not empty.

Moving a directory on top of an existing empty directory attempts 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 executes with the DirectoryEntry object for the new directory. (Function)

• errorCallback: A callback that executes if an error occurs when attempting to move the directory. Invoked with a [FileError](../fileerror/fileerror.html) 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. An error results if the app attempts to:

• copy a directory inside itself at any depth.

• copy a directory into its parent if a name different from its current directory is not provided.

Directory copies are always recursive, and 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 executes with the DirectoryEntry object for the new directory. (Function)

• errorCallback: A callback that executes if an error occurs when attempting to copy the underlying directory. Invoked with a [FileError](../fileerror/fileerror.html) 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. An error results if the app attempts to:

• delete a directory that is not empty.

• delete the root directory of a filesystem.

Parameters:

• successCallback: A callback that executes after the directory is deleted. Invoked with no parameters. (Function)

• errorCallback: A callback that executes if an error occurs when attempting to delete the directory. Invoked with a [FileError](../fileerror/fileerror.html) 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 passed the directory's parent DirectoryEntry. (Function)

• errorCallback: A callback that executes if an error occurs when attempting to retrieve the parent DirectoryEntry. Invoked with a [FileError](../fileerror/fileerror.html) 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. An error results if the app attempts 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 to be created if it doesn't exist. (Flags)

• successCallback: A callback that executes with a DirectoryEntry object. (Function)

• errorCallback: A callback that executes if an error occurs when creating or looking up the directory. Invoked with a [FileError](../fileerror/fileerror.html) 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. An error results if the app attempts 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 passed a [FileEntry](../fileentry/fileentry.html) object. (Function)

• errorCallback: A callback that executes if an error occurs when creating or looking up the file. Invoked with a [FileError](../fileerror/fileerror.html) 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 (such as trying to delete a directory containing a file that cannot be removed), some of the contents of the directory may be deleted. An error results if the app attempts to:

• delete the root directory of a filesystem.

Parameters:

• successCallback: A callback that executes after the DirectoryEntry has been deleted. Invoked with no parameters. (Function)

• errorCallback: A callback that executes if an error occurs when attempting to delete the DirectoryEntry. Invoked with a [FileError](../fileerror/fileerror.html) 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:

• An app attempts to access a directory created by a previous installation of the app.

Solution: ensure temporary directories are cleaned manually, or by the application prior to reinstallation.

• If the device is connected by USB.

Solution: disconnect the USB cable from the device and run again.