Cordova Plugin File

The Cordova's Plugin file implements a File API that enables a user to perform read/write operation on the stored device files. In a Cordova framework, we can easily use file handling by using a file plugin. This plugin allows a user to access all the main functionality of the file like read, write, access, delete, etc.

This plugin defines a global cordova.file object and it will not be available until the deviceready event is not performed.

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(cordova.file);
}

Installation

For adding the Cordova File Plugin in your app, first you need to install it. For doing this, type the below command on command prompt:

This plugin is supported in different platforms like Android, Windows, iOS, Browser etc. But FileReader.readAsArrayBuffer or FileWriter.write(blob) object is not supported on these platforms.

What does the File API require from a user?

A File API requires some specific tasks from the user side that are as follows:

Request a filesystem.
Specify the file size.
Specify the file as temporary, or permanent.
Specify success and error handler for this request.

function onInitFs(fs) {
  console.log('File system opened: ' + fs.name)
}
window.requestFileSystem = window.requestFileSystem || window.webkitRequestFileSystem
window.requestFileSystem(
  window.PERSISTENT,
  50 * 1024 * 1024 /*50MB*/,
  onInitFs,
  errorHandler
)

Where to Store Files?

The important file-system directories are offered in the form of v1.2.0 URLs. These URL form looks like this: file:///path/to/spot/. If you want to convert these URLs to a DirectoryEntry, you can easily do it by using the window.resolveLocalFileSystemURL(). Below are some of the directories where we can store the files:

cordova.file.applicationDirectory - It is a Read-only directory that stores the main application. This directory is available for Android, iOS, Windows, BlackBerry 10, OSX platforms.
cordova.file.applicationStorageDirectory - It is a Root directory of the application's sandbox. This location is available as read-only for iOS, Android platform. But for some specific subdirectories, it is available as read-write operation like /Documents for iOS and /localState for windows platform. The important data contained within the subdirectory is private to the app (iOS, Android, BlackBerry 10, OSX).
cordova.file.dataDirectory - An application's sandbox consists of a persistent and private data storage using internal memory. To use the external memory on Android platform, you can use a .externalDataDirectory.

This directory is not synced with iCloud for the iOS platform. To sync the directory with iCloud, you can use .syncedDataDirectory.

cordova.file.cacheDirectory - This directory contains the cached data files. It also concludes those files that your app can easily re-create. These files can be deleted by the OS, if a system runs low on storage.
cordova.file.externalApplicationStorageDirectory - For Android platform, this directory provides an application space on the external storage.
cordova.file.externalDataDirectory - This directory is used for Android platform where an app-specific data files are stored on external storage.
cordova.file.externalCacheDirectory - This directory stores application cache on external storage for Android platform.
cordova.file.externalRootDirectory - This directory is used for external storage root for Android, BlackBerry 10 platform.
cordova.file.tempDirectory - This directory can clear the files and does not depend on the OS to clear it. An app must remove the files as it is applicable. (Windows, iOS, OSX).
cordova.file.syncedDataDirectory - It contains synced app-specific files like iCloud.
cordova.file.documentsDirectory - It consist the files that are private to an app. These files have connectivity with another application like Office files). For iOS and OSX platform, it is a user's ~/Documents directory.
cordova.file.sharedDirectory - A directory contains the files that are globally available to all applications. It is only used for BlackBerry 10.

Upgrading Notes

After introducing a v1.0.0 of the file plugin, the structure of FileEntry and DirectoryEntry has been changed in respect to a published specification.

In the previous versions, the absolute location of file is stored in the fullPath property of Entry objects. But with v1.0.0 of the file plugin, the fullPath attribute is used to define the path of a file, relative to the root of HTML filesystem. We have shown below the typical path of the file for both iOS and Android platform before v1.0.0

/var/mobile/Applications/<application UUID>/Documents/path/to/file  (iOS)
/storage/emulated/0/path/to/file                                                  (Android)

Because of the v1.0.0 of a file plugin, the above paths can be shown by a FileEntry attribute with a fullPath of

You need to update your code to use the entry.toURL() method instead of using fullPath property of Entry objects. This method should be used in below two cases:

Case1: When your application deals with device-absolute-paths,

Case2: The paths are retrieved previously through fullPath property of Entry objects.

Some issues were faced in File-Transfer plugin when using device-absolute-paths. So, the old plugin version has updated to deal correctly with the FileSystem URLs. For doing this, entry.fullPath is replaced with entry.toURL() method. This method is used to resolve any of the issues faced while dealing with files on the device.

The updation of the file plugin v1.1.0 changes the returned value of the toURL() method for returning an absolute 'file://' URL, wherever possible. A new version also add toInternalURL() method to ensure a 'cdvfile:'-URL. This method is also used to uniquely identify the file through returning a filesystem URLs in the below form:

File Operations

We can do a lot of things with these particular files by using a Cordova's file plugin. It enables a user to perform various operations like create, access, read, write, display, append to the files. We also have an option to store the files either in a temporary or in a permanent storage location for our project. If we need to store the files in other platform-dependent locations, we can easily do it through the file plugin.

Create a persistent file

Before creating a persistent file for our project, first we have to get an access to the file system. With the help of requestFileSystem, we can get an access to a persistent or temporary storage. If you require a temporary or persistent storage, you can request it through the requestFileSystem. We cannot remove the persistent storage unless the permission is granted by the user.

When you will get permission to the file system access via requestFileSystem, it is granted only for the sandboxed file system only. The general access to any of the file system location on the device is not provided by this method. You can use another methods to access the file system location outside the sandboxed storage like window.resolveLocalFileSystemURL because it supports platform-specific locations.

The below code demonstrates the requests for a persistent storage.

Note: We don't require to use requestQuota before using the persistent storage, if target the native apps or WebView clients.

window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, function (fs) 
{
 console.log('file system is open: ' + fs.name);
 fs.root.getFile("NewFile.txt", { create: true, exclusive: false }, function (fileEntry)
   {
     console.log("Is fileEntry file?" + fileEntry.isFile.toString());
     // fileEntry.name == 'File.txt'
    // fileEntry.fullPath == '/File.txt'
     writeFile(fileEntry, null);
    }, onErrorCreateFile);
}, onErrorLoadFs);

Create a temporary file

In a temporary storage, the files can be deleted when the system runs low on memory. Here, we demonstrate an example that requests for a temporary storage.

window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) 
{
   console.log('Open file system: ' + fs.name);
   createFile(fs.root, "newTempFile.txt", false);
}, onErrorLoadFs);

To create a new file or retrieve any existing file in a temporary storage, we have to call the getFile function. To perform the read or write operations, the getFile function returns a FileEntry object.

function createFile(dirEntry, fileName, isAppend) 
{
    // Create new file or return the file if it already exists.
    dirEntry.getFile(fileName, {create: true, exclusive: false}, function(fileEntry) 
    {
        writeFile(fileEntry, null, isAppend);
    }, onErrorCreateFile);
}

Write to a file

To write to a file, first we require a FileEntry object. After that, we can call the createWriter method to write to a file. This method returns a FileWriter object for the success callback of a function. A write method of FileWriter object is called to write to the file.

function writeFile(fileEntry, dataObj) 
{
    // Creating FileWriter object for FileEntry (data.txt).
    fileEntry.createWriter(function (fileWriter) 
            {
                  fileWriter.onwriteend = function() 
                  {
                            console.log("File Write Successfully");
                             readFile(fileEntry);
                   };
        fileWriter.onerror = function (e) 
        {
            console.log("File does not write: " + e.toString());
        };
                // creating new Blob instead, if data object is not passed in,        
            if (!dataObj) 
            {
            dataObj = new Blob(['file data'], { type: 'text/plain' });
            }
        fileWriter.write(dataObj);
    });
}

Read a File

For reading any existing data file, first we require a FileEntry object. To get a reference of the file, we can use the file property of this object.

To start the read operation, we can use the readAsText method and when the operation has been completed, this.result object is used to store the result of read operation.

function readFile(fileEntry)
 {
    fileEntry.file(function (file) 
          {
               var reader = new FileReader();
               reader.onloadend = function() 
                       {
                           console.log("Read file successfully: " + this.result);
                           displayFileData(fileEntry.fullPath + ": " + this.result);
                       };
                reader.readAsText(file);
            }, onErrorReadFile);
}

Code:

var fileURL = cordova.file.dataDirectory + 'file.gif';
var uri = encodeURI("https://javaTpoint gif");
var fileTransfer = new FileTransfer();
fileTransfer.download(
    fileURL,
    uri,
    function(entry) 
    {
        console.log("downloading is completed: " + entry.toURL());
    },
    function(error) {
        console.log("Error source download" + error.source);
        console.log("Error target download" + error.target);
        // 1 = FileTransferError.FILE_NOT_FOUND_ERR
        // 2 = FileTransferError.INVALID_URL_ERR
        // 3 = FileTransferError.CONNECTION_ERR
        // 4 = FileTransferError.ABORT_ERR
        // 5 = FileTransferError.NOT_MODIFIED_ERR
        console.log("upload error code " + error.code);
    },
    false,
    {
        headers: {
            // add custom headers if needed
        }
    }
);

Next TopicCordova Plugin Geolocation

← prev next →