This version of the documentation is outdated! Click here for the latest released version.

FileTransfer

The FileTransfer object allows you to upload or download files to and from a server.

Properties

onprogress: Called with a ProgressEvent whenever a new chunk of data is transferred. (Function)

Methods

upload: sends a file to a server.
download: downloads a file from server.
abort: Aborts an in-progress transfer.

Details

The FileTransfer object provides a way to upload files to a remote server using an HTTP multi-part POST request. Both HTTP and HTTPS protocols are supported. Optional parameters can be specified by passing a [FileUploadOptions](../fileuploadoptions/fileuploadoptions.html) object to the upload() method. On successful upload, a [FileUploadResult](../fileuploadresult/fileuploadresult.html) object is passed to the success callback. If an error occurs, a [FileTransferError](../filetransfererror/filetransfererror.html) object is passed to the error callback. It is also possible (only on iOS and Android) to download a file from a remote server and save it on the device.

Supported Platforms

Amazon Fire OS
Android
BlackBerry WebWorks 5.0+
iOS
Windows Phone 7 and 8
Windows 8

upload

Parameters:

filePath: Full path of the file on the device.
server: URL of the server to receive the file, as encoded by encodeURI().
successCallback: A callback that is passed a [Metadata](../metadata/metadata.html) object. (Function)
errorCallback: A callback that executes if an error occurs retrieving the [Metadata](../metadata/metadata.html). Invoked with a [FileTransferError](../filetransfererror/filetransfererror.html) object. (Function)
options: Optional parameters such as file name and mimetype.
trustAllHosts: Optional parameter, defaults to false. If set to true, it accepts all security certificates. This is useful since Android rejects self-signed security certificates. Not recommended for production use. Supported on Android and iOS. (boolean)

Quick Example

// !! Assumes variable fileURI contains a valid URI to a text file on the device

var win = function (r) {
    console.log("Code = " + r.responseCode);
    console.log("Response = " + r.response);
    console.log("Sent = " + r.bytesSent);
}

var fail = function (error) {
    alert("An error has occurred: Code = " + error.code);
    console.log("upload error source " + error.source);
    console.log("upload error target " + error.target);
}

var options = new FileUploadOptions();
options.fileKey = "file";
options.fileName = fileURI.substr(fileURI.lastIndexOf('/') + 1);
options.mimeType = "text/plain";

var params = {};
params.value1 = "test";
params.value2 = "param";

options.params = params;

var ft = new FileTransfer();
ft.upload(fileURI, encodeURI("http://some.server.com/upload.php"), win, fail, options);

Full Example

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
    <title>File Transfer Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
    <script type="text/javascript" charset="utf-8">

        // Wait for device API libraries to load
        //
        document.addEventListener("deviceready", onDeviceReady, false);

        // device APIs are available
        //
        function onDeviceReady() {
            // Retrieve image file location from specified source
            navigator.camera.getPicture(
                uploadPhoto,
                function(message) { alert('get picture failed'); },
                {
                    quality         : 50,
                    destinationType : navigator.camera.DestinationType.FILE_URI,
                    sourceType      : navigator.camera.PictureSourceType.PHOTOLIBRARY
                }
            );
        }

        function uploadPhoto(imageURI) {
            var options = new FileUploadOptions();
            options.fileKey="file";
            options.fileName=imageURI.substr(imageURI.lastIndexOf('/')+1);
            options.mimeType="image/jpeg";

            var params = {};
            params.value1 = "test";
            params.value2 = "param";

            options.params = params;

            var ft = new FileTransfer();
            ft.upload(imageURI, encodeURI("http://some.server.com/upload.php"), win, fail, options);
        }

        function win(r) {
            console.log("Code = " + r.responseCode);
            console.log("Response = " + r.response);
            console.log("Sent = " + r.bytesSent);
        }

        function fail(error) {
            alert("An error has occurred: Code = " + error.code);
            console.log("upload error source " + error.source);
            console.log("upload error target " + error.target);
        }

        </script>
</head>
<body>
    <h1>Example</h1>
    <p>Upload File</p>
</body>
</html>

Setting Upload Headers

Supported on Android and iOS

function win(r) {
    console.log("Code = " + r.responseCode);
    console.log("Response = " + r.response);
    console.log("Sent = " + r.bytesSent);
}

function fail(error) {
    alert("An error has occurred: Code = " + error.code);
    console.log("upload error source " + error.source);
    console.log("upload error target " + error.target);
}

var uri = encodeURI("http://some.server.com/upload.php");

var options = new FileUploadOptions();
options.fileKey="file";
options.fileName=fileURI.substr(fileURI.lastIndexOf('/')+1);
options.mimeType="text/plain";

var headers={'headerParam':'headerValue'};

options.headers = headers;

var ft = new FileTransfer();
ft.upload(fileURI, uri, win, fail, options);

Android Quirks

Set the chunkedMode option to false to prevent problems uploading to a Nginx server.

download

Parameters:

source: URL of the server to download the file, as encoded by encodeURI().
target: Full path of the file on the device.
successCallback: A callback that is passed a [FileEntry](../fileentry/fileentry.html) object. (Function)
errorCallback: A callback that executes if an error occurs when retrieving the [Metadata](../metadata/metadata.html). Invoked with a [FileTransferError](../filetransfererror/filetransfererror.html) object. (Function)
trustAllHosts: Optional parameter, defaults to false. If set to true, it accepts all security certificates. This is useful because Android rejects self-signed security certificates. Not recommended for production use. Supported on Android and iOS. (boolean)
options: Optional parameters, currently only supports headers (such as Authorization (Basic Authentication), etc).

Quick Example

// !! Assumes filePath is a valid path on the device

var fileTransfer = new FileTransfer();
var uri = encodeURI("http://some.server.com/download.php");

fileTransfer.download(
    uri,
    filePath,
    function(entry) {
        console.log("download complete: " + entry.fullPath);
    },
    function(error) {
        console.log("download error source " + error.source);
        console.log("download error target " + error.target);
        console.log("upload error code" + error.code);
    },
    false,
    {
        headers: {
            "Authorization": "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA=="
        }
    }
);

abort

Aborts an in-progress transfer. The onerror callback is passed a FileTransferError object which has an error code of FileTransferError.ABORT_ERR.

Supported Platforms

Amazon Fire OS
Android
iOS

Quick Example

// !! Assumes variable fileURI contains a valid URI to a text file on the device

var win = function(r) {
    console.log("Should not be called.");
}

var fail = function(error) {
    // error.code == FileTransferError.ABORT_ERR
    alert("An error has occurred: Code = " + error.code);
    console.log("upload error source " + error.source);
    console.log("upload error target " + error.target);
}

var options = new FileUploadOptions();
options.fileKey="file";
options.fileName="myphoto.jpg";
options.mimeType="image/jpeg";

var ft = new FileTransfer();
ft.upload(fileURI, encodeURI("http://some.server.com/upload.php"), win, fail, options);
ft.abort();

onprogress

Called with a ProgressEvent whenever a new chunk of data is transferred.

Supported Platforms

Amazon Fire OS
Android
iOS

Example

fileTransfer.onprogress = function(progressEvent) {
    if (progressEvent.lengthComputable) {
      loadingStatus.setPercentage(progressEvent.loaded / progressEvent.total);
    } else {
      loadingStatus.increment();
    }
};
fileTransfer.download(...); // or fileTransfer.upload(...);

Quirks

On both Android an iOS, lengthComputable is false for downloads that use gzip encoding.