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 com.blackberry.io.filetransfer

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 will not block execution.The function is an asynchronous call and will 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 will save to.

successCallback {Function}

Callback function that will be 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 will be 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 multi-part POST request. Both HTTP and HTTPS protocols are supported. The function is an asynchronous call and will 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 that will receive the file.

successCallback {Function}

Callback function that will be 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 will be 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 do not have to be specified in any particular order.

fileKey {String}

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

fileName {String}

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

mimeType {String}

MIME type of the data being uploaded. If not set, this 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, this defaults to true.

chunkSize {Number}

Specifies the size of each chunk when chunkedMode is true. If not set, this 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-05-14



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

comments powered by Disqus