download


Purpose

Downloads a file from a server.

Signature

download( url, filePath, options, callbacks )

Returns

The FileTransferTask object representing the download task that has been started.

Parameters

Name Description Type Use
url The URL pointing to the remote file to be downloaded. string required
filePath The path in the local storage where the downloaded file from the remote server is to be saved, as defined in the Filesystem API. string required
options

Optional transfer parameters passed to the function call, as described in the table below.

object optional
callbacks An object defining the callbacks for the function. object required

The download method's options object consists of the following:

{ credentials, params, headers, trustAll }
Name Description Type Use
credentials The user credentials specified in 'username:password' format to be used for basic access authentication. If the value specified consists of an empty string, the identifier and password of the currently open account will be used. string optional
params A map of optional query parameters to be passed along in the HTTP request. object optional
headers

A map of header names to header values. To specify multiple values for a header, use an array of values.

object optional
trustAll If set to 'true' then the download file transfer operation will accept all security certificates. This parameter is only supported under iOS and is not recommended for production use. It is not supported under Android due to platform limitations. For development purposes, under Android platform, one can add an untrusted certificate as trusted one on a given test device. boolean optional

The download method's callbacks object can be structured as follows:

{
  onSuccess: function(file) {...},
  onProgress: function(progress) {...},
  onCancel: function() {...},
  onFailure: function(error) {...}
}

The table below lists all callbacks supported by this method.

Name Description Return type
onSuccess Called when the file download operation has completed without an error. The file parameter passed within this callback contains the successfully downloaded file from the server as a FileEntry object. undefined
onProgress Called to notify about file download progress. The progress parameter passed in this callback consists of a double value between 0.0 (start) and 1.0 (finish), indicating the current progress of downloading a file. There is no guarantee that 0.0 and 1.0 values will be used. undefined
onCancel Called when the file download operation was canceled by the application. On the Android platform, it will also be called if the download operation has been canceled by the Download user interface. undefined
onFailure

Called when an error occurs during the file downloading operation.

The error object consists of following fields:

  • code - one of the error codes specifying the type of problem that has occurred, as listed in the Constants table, found in the FileTransfer article. Specified as an integer.

  • description - additional text describing the type or error that has occurred. Specified as a string.

  • httpCode - the HTTP error code, if the error that has occurred is related to HTTP. Specified as an integer.

undefined

Related topics

Overview
Legal notice | Copyright © 2016 and Confidential to Pegasystems Inc. All rights reserved
PDN | Hybrid Container | Feedback
Advanced...