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
- Amazon Fire OS
- Android
- BlackBerry WebWorks 5.0+
- 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 to1
to prevent the directory from being backed up to iCloud. Set the value to0
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(error) {
console.log(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(dirEntry) {
console.log("Directory Name: " + dirEntry.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(fileEntry) {
console.log("File Name: " + fileEntry.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 can't 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.