upload

Purpose

Uploads a local file to a remote server.

upload( filePath, url, options, callbacks )

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

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`