Phone Gap's FileSystem object represents information about the FileSystem. It has the following two properties:

  • name : This is the name of the FileSystem.
  • root : This is the root directory of the FileSystem.

This object is returned as the success callback of the requestFileSystem().

Example

window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, onSuccess, onFail);
function onSuccess(fileSystem)
{
alert(fileSystem.name);
alert(fileSystem.root.name);
}
function onFail(event)
{
alert(event.target.error.code);
}

The root property contains a DirectoryEntry object.

Learning about Directories and Files

Two kinds of items are found in the filesystem: directories and files. Directories are represented by DirectoryEntry objects and files are represented by FileEntry objects.

Now here we learn how to use DirectoryEntry objects.

This object represents a directory on a filesystem. It has the following Properties:

  • isFile : This is always False.
  • isDirectory : This is always True.
  • name : This is the name of the DirectoryEntry, excluding the path leading to it.
  • fullPath : This is the full absolute path from the root to the DirectoryEntry object.

Furthermore, DirectoryEntry has the following methods:

  • getMetadata
  • moveTo
  • copyTo
  • toURI
  • remove
  • getParent
  • createReader
  • getDirectory
  • getFile
  • removeRecursively

Let's explain all the methods:

  1. getMetadata

    This method is used to look up metadata about a directory. It features two callback functions as parameters:

    • successCallback : This is a callback that is called with a metadata object.
    • errorCallback : This is a callback that is called if error retrieving the metadata object.

    Following is an example:

    function onSuccess(metadata)
    {
    alert("last modified: " + metadata.modificationtime);
    }
    function onFail(error)
    {
    alert(error.code);
    }
    //Request the metadata object for this entry
    entry.metadata(onSuccess, onFail);

  2. moveTo

    This method is used to move a directory to a different location on the filesystem. Any of the following conditions will create an error:

    • If you try to move a directory inside itself, or to any child at any depth.
    • If you try to move a directory into its parent if a name that is different from its current one is not provided.
    • If you try to move a directory to a path occupied by a file.
    • If you try to move a directory to a path occupied by a directory that is not empty.

    Following are the parameters for this method:

    • parent : This is the parent directory to which to move the directory.
    • newName : This is the new name of the directory. It defaults to the current name if unspecified.
    • successCallback : This is a callback that is called with the DirectoryEntry object of
      the new directory.
    • errorCallback : This is a callback that is called if an error occurs when attempting to
      move the directory.

    Following is an example:

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

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

    function moveDirectory(entry)
    {
    var parent = document.getElementById('parent').value,
    newName = document.getElementById('newName').value,
    parentEntry = new DirectoryEntry({fullPath: parent});

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

  3. copyTo

    This method is used to copy a directory to a different location on the filesystem. Any of the following will create an error:

    • If you try to copy a directory inside itself at any depth.
    • If you try to copy a directory into its parent if a name that is different from its current one is
      not provided.

    Following are the parameters for this method:

    • parent : This is the parent directory to which to copy the directory.
    • newName : This is the new name of the directory. It defaults to the current name if unspecified.
    • successCallback : This is a callback that is called with the DirectoryEntry object of the new directory.
    • errorCallback : This is a callback that is called if an error occurs when attempting to copy the underlying directory. It is invoked with a FileError object.

    Following is an example:

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

    function fail(error)
    {
    alert(error.code);
    }
    function copyDirectory(entry)
    {
    var parent = document.getElementById('parent').value,
    newName = document.getElementById('newName').value,
    parentEntry = new DirectoryEntry({fullPath: parent});

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

  4. toURI

    This method returns a URI that can be used to locate a directory. Following is an example:

    // Get the URI for this directory
    var uri = entry.toURI();
    alert(uri);

  5. remove

    This method deletes a directory. Any of the following will create an error:
    • If you try to delete a directory that is not empty.
    • If you try to delete the root directory of a filesystem.

    The parameters consist of two callback functions:

    • successCallback : This is a callback that is called after the directory has been deleted. Itis invoked with no parameters.
    • errorCallback : This is a callback that is called if an error occurs when attempting todelete the directory.

    Following is an example:

    function success(entry)
    {
    alert("Removal succeeded");
    }

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

    // remove this directory
    entry.remove(success, fail);

  6. getParent

    This method is used to look up the parent DirectoryEntry containing the current directory. The parameters consist of two callback functions:
    • successCallback : This is a callback that is called with the directory's parentDirectoryEntry object.
    • errorCallback : This is a callback that is called if an error occurs when attempting to retrieve the parent DirectoryEntry object. It is invoked with a FileError object.

    Following is an example:

    function success(parent)
    {
    alert("Parent: " + parent.name);
    }
    function fail(error)
    {
    alert("Failed to get parent: " + error.code);
    }

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

  7. createReader

    The way you read entries in a directory is to use the createReader method. Following is an example:

    // create a directory reader
    var directoryReader = entry.createReader();

  8. getDirectory

    This method creates or looks up an existing directory. If you try to create a directory whose immediate parent does not yet exist, you'll get an error.

    Following are the parameters:
    • path : This is the path to the directory to be looked up or created. This can be a relative or absolute path.
    • options : These are options to specify whether the directory is created if it doesn't exist.
    • successCallback : This is a callback that is invoked with a DirectoryEntry object.
    • errorCallback : This is a callback that is called if an error occurs when creating orlooking up the directory. It is invoked with a FileError object.

    Following is an example:

    function success(parent)
    {
    alert("Parent: " + 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("sampleFiles", { create: true, exclusive: false }, success,fail);

  9. getFile

    This method creates or looks up a file. If you try to create a file whose immediate parent does not yet exist, you'll get an error.

    Following are the parameters:

    • path : This is the path to the file to be looked up or created. This can be a relative orabsolute path.
    • options : These are options to specify whether the file is created if it doesn't exist.
    • successCallback : This is a callback that is invoked with a FileEntry object.
    • errorCallback : This is a callback that is called if an error occurs when creating orlooking up the file. It is invoked with a FileError object.

    Following is an example:

    function success(parent)
    {
    alert("Parent:" + 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("sample_data.txt", { create: true, exclusive: false }, success,fail):

  10. removeRecursively

    This deletes a directory and all of its contents. In the event of an error (for example, if you try to delete a directory that contains a file that cannot be removed), some of the contents of the directory may be deleted. If you try to delete the root directory of a filesystem, you'll get an error.

    The parameters consist of two callback functions:
    • successCallback : This is a callback that is called after the DirectoryEntry object has been deleted. It is invoked with no parameters.
    • errorCallback : This is a callback that is called if an error occurs when attempting to delete the DirectoryEntry object. It is invoked with a FileError object.

    Following is an example:

    function success(parent)
    {
    alert("Delete succeeded!");
    }
    function fail(error)
    {
    alert("Failed to delete directory or it's contents: " + error.code);
    }
    // remove the directory and all it's contents
    entry.removeRecursively(success, fail);