upload


Purpose

Uploads a local file to a remote server.

Signature

upload( filePath, url, options, callbacks )

Returns

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

Parameters

Name Description Type Use
filePath A path to the local file that is to be uploaded to the remote server, as defined in the Filesystem API. string required
url A URL address pointing to the server, to which the file is to be uploaded. 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 upload method's options object consists of the following:

{ credentials, fileKey, fileName, mimeType, params, headers, trustAll }
Name Description Type Use
credentials 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
fileKey A name of the form element. If not set, the parameter defaults to "file". string optional
fileName A file name to be used when saving the file on the server. If not set, the parameter defaults to "image.jpg". string optional
mimeType A MIME type of the data that is being uploaded. If not set, the parameter defaults to "image/jpeg". string optional
params A map of optional key/value pairs to be passed along in the HTTP request. object optional
headers

A map of header names to header values. Use an array of values to specify multiple values for a header.

object optional
trustAll If set to "true", the upload operation will accept all security certificates. This parameter is supported under Android and iOS and is not recommended for production use. boolean optional

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

{
  onSuccess: function(success) {...},
  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 upload operation completes without an error. Passes an object that consists of the following fields:

  • bytesSent - number of bytes sent to the server.

  • message - server response, if sent in human-readable form.

  • httpCode - an HTTP status code returned by the server. Specified as an integer.

undefined
onProgress Called to notify about file upload progress. The progress parameter passed in this callback consists of a value ranging from 0 to 1, indicating the current progress of uploading a file. undefined
onCancel Called when the file upload operation was canceled by the application. undefined
onFailure

Called when an error occurs during the file upload operation.

The error object consists of following fields:

  • url - file location on the remote server. Specified as an string.

  • filePath - a path in local storage to the file that failed to upload. Specified as an string.

  • code - one of 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 - an HTTP error code, if the error that has occurred is related to HTTP. Specified as an integer.

undefined

Related topics

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