FileSystem-DirectoryEntry Objects in PhoneGap

In this article you will learn how to work with PhoneGap FileSystems and directories and how files use DirectoryEntry objects.

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);