FileEntry

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

  • 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](../filewriter/filewriter.html) object that can be used to write to a file.

  • file: Creates a [File](../fileobj/fileobj.html) object containing file properties.

Supported Platforms

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

getMetadata

Look up metadata about a file.

Parameters:

  • successCallback: A callback that is passed a [Metadata](../metadata/metadata.html) object. (Function)

  • errorCallback: A callback that executes 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

Set metadata on a file.

Currently works only on iOS.

  • this will set the extended attributes of a file.

Parameters:

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

  • errorCallback: A callback that executes when the metadata is not successfully 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 file from being backed up to iCloud. Set the value to 0 to re-enable the file to be backed up to 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) {
        var data = {};
        data[metadataKey] = metadataValue;
        parent.setMetadata(onSetMetadataWin, onSetMetadataFail, data);
    }
    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.PERSISTENT, "Backups/sqlite.db", "com.apple.MobileBackup", 1);

moveTo

Move a file to a different location on the file system. An error results if the app attempts 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, moving a file on top of an existing file attempts 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 passed the new file's FileEntry object. (Function)

  • errorCallback: A callback that executes if an error occurs when attempting to move the file. 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 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. An error results if the app attempts 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 passed the new file's FileEntry object. (Function)

  • errorCallback: A callback that executes if an error occurs when attempting to copy the file. 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 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 executes after the file has been deleted. Invoked with no parameters. (Function)

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

Parameters:

  • successCallback: A callback that is passed the file's parent [DirectoryEntry](../directoryentry/directoryentry.html). (Function)

  • errorCallback: A callback that executes if an error occurs when attempting to retrieve the parent [DirectoryEntry](../directoryentry/directoryentry.html). Invoked with a [FileError](../fileerror/fileerror.html) 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](../filewriter/filewriter.html) object associated with the file represented by the FileEntry.

Parameters:

  • successCallback: A callback that is passed a [FileWriter](../filewriter/filewriter.html) object. (Function)

  • errorCallback: A callback that executes if an error occurs while attempting to create the FileWriter. Invoked with a [FileError](../fileerror/fileerror.html) 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](../fileobj/fileobj.html) object that represents the current state of the file that this FileEntry represents.

Parameters:

  • successCallback: A callback that is passed a [File](../fileobj/fileobj.html) object. (Function)

  • errorCallback: A callback that executes if an error occurs when creating the [File](../fileobj/fileobj.html) object, such as when the file no longer exists. Invoked with a [FileError](../fileerror/fileerror.html) 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);