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 ( Mango )
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.
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);