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

Deprecation notice: This function has been deprecated since BlackBerry WebWorks 2.2. Apps that use this API should be updated 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].

Function Type Function Name
void download()
void upload()
Constant Type Constant Name
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
Type: String

URL of the server to receive the file.

target
Type: String

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

successCallback(info)

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

info
Type: Object

Object containing information about the download.

isFile
Type: Boolean

Always true.

isDirectory
Type: Boolean

Always true.

name
Type: String

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

fullPath
Type: String

The full absolute path from the root.

errorCallback(errorCallback.info)

Callback function that is invoked if the file download fails.

errorCallback.info
Type: Object

Object containing information about the failed download request.

code
Type: Number

Error code indicating the type of error that occurred.

source
Type: String

Path of the original file.

target
Type: String

URL of the remote server.

http_status
Type: 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
Type: String

Full path of the file on the device.

server
Type: String

URL of the remote server to receive the file.

successCallback(info)

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

info
Type: Object

Object containing information about the upload.

bytesSent
Type: Number

Total number of bytes sent to the server.

responseCode
Type: Number

HTTP response code returned by the server.

response
Type: String

Response returned by the server.

errorCallback(info)

Callback function that is invoked if the file upload fails.

info
Type: Object

Object containing information about the failed upload request.

code
Type: Number

Error code indicating the type of error that occurred.

source
Type: String

Path of the original file.

target
Type: String

URL of the remote server.

http_status
Type: Number

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

options
Type: 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
Type: String

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

fileName
Type: String

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

mimeType
Type: String

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

params
Type: Object

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

chunkedMode
Type: Boolean

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

chunkSize
Type: 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: 2015-03-19



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

comments powered by Disqus