FileTransfer

The FileTransfer object contains functions for uploading and downloading files to/from a remote server.

Installation:

To use this API in your project, add the io filetransfer plugin:

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

In BlackBerry WebWorks 2.1 and earlier, the com.blackberry.io.filetransfer plugin was used. Update the code to use the org.apache.cordova.file-transfer plugin instead.

Learning Resources:

Sample - Using FileTransfer Sample that demonstrates how to use the BlackBerry File Transfer API [BlackBerry on GitHub].

Functions:
void download()
void upload()
Constants:
Number FILE_NOT_FOUND_ERR
Number INVALID_URL_ERR
Number PERMISSIONS_ERR
Number CONNECTION_ERR

download()

Downloads a file from a remote server to the device. The function is an asynchronous call and does not block execution.

Synopsis:

void blackberry.io.filetransfer.download(source, target, successCallback, errorCallback)

Parameters:

source {String}

URL of the server to receive the file.

target {String}

Full path on the device that the download file gets saved to.

successCallback {Function}

Callback function that is invoked if the file download is successful.

info {Object}

Object containing information about the download.

isFile {Boolean}

Always true.

isDirectory {Boolean}

Always true.

name {String}

The name of the file, excluding the path leading to it.

fullPath{String}

The full absolute path from the root.

errorCallback {function}

Callback function that is invoked if the file download fails.

errorCallback.info {Object}

Object containing information about the failed download request.

code {Number}

Error code indicating the type of error that occurred.

source {String}

Path of the original file.

target {String}

URL of the remote server.

http_status {Number}

HTTP status code. This attribute is only available when a response code is received from the HTTP connection.

Example:

<script type="text/javascript">

    function downloadSuccess(result) {
        alert("Download was successful");
        console.log("isFile: " + result.isFile);
        console.log("isDirectory: " + result.isDirectory);
        console.log("name: " + result.name);
        console.log("fullPath: " + result.fullPath);
    }

    function downloadError(result) {
        alert("Download failed");
        console.log("Error code: " + result.code);
        console.log("Source: " + result.source);
        console.log("Target: " + result.target);
        console.log("HTTP status: " + result.http_status);
    }

    function fileDownload() {
        try {
            blackberry.io.filetransfer.download(
                "http://www.blackberry.com/download", 
                "/accounts/1000/shared/camera/image_123.jpg", 
                downloadSuccess, downloadError);
        } catch(e) {
            alert("Exception in fileDownload: " + e);
        }
    }

</script>

upload()

Uploads a file from the device to a remote server using an HTTP multipart POST request. Both HTTP and HTTPS protocols are supported. The function is an asynchronous call and does not block execution.

Synopsis:

void upload(filePath, server, successCallback, errorCallback, options)

Parameters:

filePath {String}

Full path of the file on the device.

server {String}

URL of the remote server to receive the file.

successCallback {Function}

Callback function that is invoked if the file upload is successful.

info {Object}

Object containing information about the upload.

bytesSent {Number}

Total number of bytes sent to the server.

responseCode {Number}

HTTP response code returned by the server.

response {String}

Response returned by the server.

errorCallback {Function}

Callback function that is invoked if the file upload fails.

info {Object}

Object containing information about the failed upload request.

code {Number}

Error code indicating the type of error that occurred.

source {String}

Path of the original file.

target {String}

URL of the remote server.

http_status {Number}

HTTP status code. This attribute is only available when a response code is received from the HTTP connection.

options {Object}
Optional Object literal that allows the user to customize the file key, file name, MIME type, parameters, and chunked mode of the upload request. It is not required to provide all parameters, and these parameters do not have to be specified in any particular order.
fileKey {String}

Name of the form element. If not set, the name defaults to "file".

fileName {String}

Name that the file to be saved as on the remote server. If not set, the name defaults to "image.jpg".

mimeType {String}

MIME type of the data being uploaded. If not set, the type defaults to "image/jpeg".

params {Object}

A set of optional key/value pairs to be passed along in the HTTP request.

chunkedMode {Boolean}

Specifies whether the data should be uploaded in chunked streaming mode. If not set, the value defaults to true.

chunkSize {Number}

Specifies the size of each chunk when chunkedMode is true. If not set, the size defaults to 1024 bytes.

Example:

<script type="text/javascript">

    function uploadSuccess(result) {
        alert("Upload was successful");
        console.log("Bytes sent: " + result.bytesSent);
        console.log("Response code: " + result.responseCode);
        console.log("Response: " + result.response);
    }

    function uploadError(result) {
        alert("Upload failed");
        console.log("Error code: " + result.code);
        console.log("Source: " + result.source);
        console.log("Target: " + result.target);
        console.log("HTTP Status: " + result.https_status);
    }

    function fileUpload() {
        var parameters, options;
        try {
            parameters = { app : "webworks" };
            options = {
                fileKey : "file",
                fileName : "blackberry.jpg",
                mimeType : "image/jpeg",
                params : parameters,
                chunkedMode : true,
                chunkSize : 1024
            };
            blackberry.io.filetransfer.upload(
                "/accounts/1000/shared/camera/image_123.jpg", 
                "http://www.blackberry.com/upload", 
                uploadSuccess, uploadError, options);
        } catch(e) {
        alert("Exception in fileUpload: " + e);
        }
    }

</script>

Example:

/*
FILENAME: upload.php
A sample PHP upload server script which will save files into an "upload" directory. Make sure to create and set 777 permissions for the "upload" folder in the same directory as upload.php.
*/
<?php

    if (move_uploaded_file($_FILES["file"]["tmp_name"], 
        "upload/" . $_FILES["file"]["name"])) {
        echo "Success";
    } else {
        echo "Error";
    }

?>

FILE_NOT_FOUND_ERR

The file was not found.

Synopsis:

constant
Number blackberry.io.filetransfer.FILE_NOT_FOUND_ERR = 1

INVALID_URL_ERR

The URL of the server was invalid.

Synopsis:

constant
Number blackberry.io.INVALID_URL_ERR = 2

PERMISSIONS_ERR

Application unable to write to target folder due to insufficient permissions.

Synopsis:

constant
Number blackberry.io.filetransfer.PERMISSIONS_ERR = 4

CONNECTION_ERR

The upload failed due to a connection error.

Synopsis:

constant
Number blackberry.io.filetransfer.CONNECTION_ERR = 3

Last modified: 2014-09-29



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus