FileTransfer

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


Learning Resources:

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

Supported Platform(s)

- BlackBerry 10
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.io.filetransfer.download           Y 
blackberry.io.filetransfer.upload           Y 
FILE_NOT_FOUND_ERR           Y 
INVALID_URL_ERR           Y 
CONNECTION_ERR           Y 
PERMISSIONS_ERR           Y 

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

You must declare the feature element(s) below in your configuration document:

Feature IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.io.filetransfer" />           Y 

Permission Elements (PlayBook and BlackBerry 10+)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.


Constants

Functions

static void blackberry.io.filetransfer.download (source : String, target : String, successCallback: function(info : Object), errorCallback: function(info : Object))


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


Supported Platforms
 - BlackBerry 10


Parameters
source URL of the server to receive the file.
target Full path on the device that the download file will save to.
successCallback Callback function that will be invoked if the file download is successful.

info: Object containing information about the download.
info.isFile: Always true.
info.isDirectory: Always false.
info.name: The name of the file, excluding the path leading to it.
info.fullPath: The full absolute path from the root.
errorCallback Callback function that will be invoked if the file download fails.

info: Object containing information about the failed download request.
info.code: Error code indicating the type of error that occurred.
info.source: Path of the original file.
info.target: URL of the remote server.
info.http_status: HTTP status code. This attribute is only available when a response code is received from the HTTP connection.

Code 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>

static void blackberry.io.filetransfer.upload (filePath : String, server : String, successCallback: function(info : Object), errorCallback: function(info : Object), [options : Object])


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.


Supported Platforms
 - BlackBerry 10


Parameters
filePath Full path of the file on the device.
server URL of the remote server that will receive the file.
successCallback Callback function that will be invoked if the file upload is successful.

info: Object containing information about the upload.
info.bytesSent: Total number of bytes sent to the server.
info.responseCode: HTTP response code returned by the server.
info.response: Response returned by the server.
errorCallback Callback function that will be invoked if the file upload fails.

info: Object containing information about the failed upload request.
info.code: Error code indicating the type of error that occurred.
info.source: Path of the original file.
info.target: URL of the remote server.
info.http_status: HTTP status code. This attribute is only available when a response code is received from the HTTP connection.
options 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: Name of the form element. If not set, this defaults to "file".
fileName: Name that the file will be saved as on the remote server. If not set, this defaults to "image.jpg".
mimeType: MIME type of the data being uploaded. If not set, this defaults to "image/jpeg".
params: A set of optional key/value pairs to be passed along in the HTTP request.
chunkedMode: Specifies whether the data should be uploaded in chunked streaming mode. If not set, this defaults to true.
chunkSize: Specifies the size of each chunk when chunkedMode is true. If not set, this defaults to 1024 bytes.

Code 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>
/*
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";
}

?>

Constants

static Number FILE_NOT_FOUND_ERR = 1


The file was not found.


Supported Platforms
 - BlackBerry 10

static Number INVALID_URL_ERR = 2


The URL of the server was invalid.


Supported Platforms
 - BlackBerry 10

static Number CONNECTION_ERR = 3


The upload failed due to a connection error.


Supported Platforms
 - BlackBerry 10

static Number PERMISSIONS_ERR = 4


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


Supported Platforms
 - BlackBerry 10

Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:07 GMT-0500 (EST)