A FileEntry object represents a file on a filesystem. It has the following properties:
isFile- This is always true.
isDirectory- This is always false.
name- This is the name of the FileEntry object, excluding the path leading to it.
fullPath- This is the full absolute path from the root to the FileEntry object.
This object also has the following methods:
- getMetadata
- moveTo
- copyTo
- toURI
- remove
- getParent
- createWriter
- file
1. getMetadata
This method is used to look up metadata about a file. Remember that a file is separate form its data; the data would be what's stored in the file (words, images and so on), whereas metadata would be more like the creation time for the file, the file's size and so on.
The parameters consists of two callback functions:
successCallback- This is a callback that is called with a Metadata object.
errorCallback- This is a callback that is called if an error occurs while retrieving the Metadata object. It is invoked with a FileError object.
The following is an example:
function success(metadata) {
alert("Last Modified: " + metadata.modificationTime);
}
function fail(error) {
alert(error.code);
}
// Request the metadata object for this entry
entry.getMetadata(success, fail);
2. moveTo
This method is used to move a file to a different location on the filesystem. If you try to do any of the following, you'll get an error:
- Try to move a file into its parent if a name that is different from its current one isn't
provided.
- Try to move a file to a path occupied by a directory.
- Try to move a file on top of an existing file without first deleting the existing file.
The following are the parameters:
parent- This is the parent directory to which to move the file.
newName- This is the new name of the file. It defaults to the current name if unspecified.
successCallback- This is a callback that is called with the FileEntry object of the new file.
errorCallback- This is a callback that is called if an error occurs when attempting to move the file. It is invoked with a FileError object.
The following is an example:
function success(entry) {
alert("New Path: " + entry.fullPath);
}
function fail(error) {
alert(error.code);
}
function moveFile(entry) {
var parent = document.getElementById('parent').value,
parentEntry = new DirectoryEntry({fullPath: parent});
// move the file to a new directory and rename it
entry.moveTo(parentEntry, "new_file.txt", success, fail);
}
3. copyTo
This method is used to copy a file to a new location on the filesystem. If you try to copy a file into its parent, and a file with that name already exists there, you'll get an error.
The following are the parameters:
parent- This is the parent directory to which to copy the file.
newName- This is the new name of the file. It defaults to the current name if unspecified.
successCallback- This is a callback that is called with the FileEntry object of thenew file.
errorCallback- This is a callback that is called if an error occurs when attempting to copy the file.
The following is an example:
function success(entry) {
alert("New Path: " + entry.fullPath);
}
function fail(error) {
alert(error.code);
}
function copyFile(entry) {
var parent = document.getElementById('parent').value,
parentEntry = new DirectoryEntry({fullPath: parent});
// copy the file to a new directory and rename it
entry.copyTo(parentEntry, "file.copy.txt", success, fail);
}
4. toURI
This method is used to return a URI that can be used to locate the file. The following is an example:
// Request the metadata object for this entry
var uri = entry.toURI();
console.log(uri);
5. remove
This method is used to delete a file. The parameters consist of two callback functions:
successCallback- This is a callback that is called after the file has been deleted. It is invoked with no parameters.
errorCallback- This is a callback that is called if an error occurs when attempting todelete the file. It is invoked with a FileError object.
The following is an example:
function success(entry) {
alert("Removal succeeded");
}
function fail(error) {
alert('Error removing file: ' + error.code);
}
// remove the file
entry.remove(success, fail);
6. getParent
This method is used to look up the parent DirectoryEntry object containing the file. The parameters consists of two callback functions:
successCallback- This is a callback that is called with the file's parent DirectoryEntryobject.
errorCallback- This is a callback that is called if an error occurs when attempting to retrieve the parent DirectoryEntry object.
The following is an example:
function success(parent) {
alert("Parent Name: " + parent.name);
}
function fail(error) {
alert(error.code);
}
// Get the parent DirectoryEntry
entry.getParent(success, fail);
7. createWriter
You can write a file to a directory by using the createWriter method. It creates a FileWriter object associated with the file. The parameters consist of two callback functions:
successCallback- This is a callback that is called with a FileWriter object.
errorCallback- This is a callback that is called if an error occurs while attempting to create the FileWriter object.
The following is an 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);
8. file
This method is used to return a File object that represents the current state of the file represented by the FileEntry object. The parameters consist of two callback functions:
successCallback- This is a callback that is called with a File object.
errorCallback- This is a callback that is called if an error occurs when creating the File object (in other words, the underlying file no longer exists).
The following is an example:
function success(file) {
alert("File size: " + file.size);
}
function fail(error) {
alert("Unable to retrieve file properties: " + error.code);
}
// obtain properties of a file
entry.file(success, fail);
Resources:
Some of the useful resources are:
FileSystem-DirectoryEntry Objects in PhoneGap
Working With Networks in Windows Phone 7 Using PhoneGap
Events in PhoneGap