Working with Directory in PhoneGap

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