cordova-plugin-file-transfer/doc/index.md

org.apache.cordova.file-transfer

This plugin allows you to upload and download files.

Installation

cordova plugin add org.apache.cordova.file-transfer

Supported Platforms

• Amazon Fire OS
• Android
• BlackBerry 10*
• iOS
• Windows Phone 7 and 8*
• Windows 8*

* Do not support onprogress nor abort()

FileTransfer

The FileTransfer object provides a way to upload files using an HTTP multi-part POST request, and to download files as well.

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.

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 object. (Function)

• errorCallback: A callback that executes if an error occurs retrieving the Metadata. Invoked with a FileTransferError object. (Function)

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

• options: Optional parameters (Object). Valid keys:

  • fileKey: The name of the form element. Defaults to file. (DOMString)
  • fileName: The file name to use when saving the file on the server. Defaults to image.jpg. (DOMString)
  • mimeType: The mime type of the data to upload. Defaults to image/jpeg. (DOMString)
  • params: A set of optional key/value pairs to pass in the HTTP request. (Object)
  • chunkedMode: Whether to upload the data in chunked streaming mode. Defaults to true. (Boolean)
  • headers: A map of header name/header values. Use an array to specify more than one value. (Object)

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

Example with Upload Headers and Progress Events (Android and iOS only)

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.onprogress = function(progressEvent) {
    if (progressEvent.lengthComputable) {
      loadingStatus.setPercentage(progressEvent.loaded / progressEvent.total);
    } else {
      loadingStatus.increment();
    }
};
ft.upload(fileURI, uri, win, fail, options);

FileUploadResult

A FileUploadResult object is passed to the success callback of the FileTransfer object's upload() method.

Properties

• bytesSent: The number of bytes sent to the server as part of the upload. (long)

• responseCode: The HTTP response code returned by the server. (long)

• response: The HTTP response returned by the server. (DOMString)

iOS Quirks

• Does not support responseCode or bytesSent.

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 object. (Function)

• errorCallback: A callback that executes if an error occurs when retrieving the Metadata. Invoked with a FileTransferError 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).

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.

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

FileTransferError

A FileTransferError object is passed to an error callback when an error occurs.

Properties

• code: One of the predefined error codes listed below. (Number)

• source: URI to the source. (String)

• target: URI to the target. (String)

• http_status: HTTP status code. This attribute is only available when a response code is received from the HTTP connection. (Number)

Constants

• FileTransferError.FILE_NOT_FOUND_ERR
• FileTransferError.INVALID_URL_ERR
• FileTransferError.CONNECTION_ERR
• FileTransferError.ABORT_ERR