This version of the documentation is outdated! Click here for the latest released version.

FileEntry

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

Properties

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

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

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

Methods

getMetadata: Look up metadata about a file.
setMetadata: Set metadata on a file.
moveTo: Move a file to a different location on the file system.
copyTo: Copy a file to a different location on the file system.
toURL: Return a URL that can be used to locate a file.
remove: Delete a file.
getParent: Look up the parent directory.
createWriter: Creates a FileWriter object that can be used to write to a file.
file: Creates a File object containing file properties.

Supported Platforms

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

getMetadata

Look up metadata about a file.

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 file. Only works on iOS currently - this will set the extended attributes of a file.

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 file to be backed up by iCloud. Set the value to 0 to re-enable the file to be backed up by iCloud.

Quick Example

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

    var onGetFileWin = function(parent) {
      parent.setMetadata(onSetMetadataWin, onSetMetadataFail, { metadataKey: metadataValue});
    }
    var onGetFileFail = function() {
      console.log("error getting file")
    }

    var onFSWin = function(fileSystem) {
      fileSystem.root.getFile(filePath, {create: true, exclusive: false}, onGetFileWin, onGetFileFail);
    }

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

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

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

moveTo

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

move a file into its parent if a name different from its current one isn't provided;
move a file to a path occupied by a directory;

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

Parameters:

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

Quick Example

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

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

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

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

copyTo

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

copy a file into its parent if a name different from its current one is not provided.

Parameters:

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

Quick Example

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

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

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

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

toURL

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

Quick Example

// Request the URL for this entry
var fileURL = entry.toURL();
console.log(fileURL);

remove

Deletes a file.

Parameters:

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

Quick Example

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

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

// remove the file
entry.remove(success, fail);

getParent

Look up the parent DirectoryEntry containing the file.

Parameters:

successCallback - A callback that is called with the file'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(error.code);
}

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

createWriter

Create a FileWriter object associated with the file that the FileEntry represents.

Parameters:

successCallback - A callback that is called with a FileWriter object. (Function)
errorCallback - A callback that is called if an error occurs while attempting to create the FileWriter. Invoked with a FileError object. (Function)

Quick Example

function success(writer) {
    writer.write("Some text to the file");
}

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

// create a FileWriter to write to the file
entry.createWriter(success, fail);

file

Return a File object that represents the current state of the file that this FileEntry represents.

Parameters:

successCallback - A callback that is called with a File object. (Function)
errorCallback - A callback that is called if an error occurs when creating the File object (e.g. the underlying file no longer exists). Invoked with a FileError object. (Function)

Quick Example

function success(file) {
    console.log("File size: " + file.size);
}

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

// obtain properties of a file
entry.file(success, fail);