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
- Amazon Fire OS
- Android
- BlackBerry WebWorks 5.0+
- 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 sets 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 to1
to prevent the file from being backed up to iCloud. Set the value to0
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(error) {
console.log(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);