# Download Manager

## Methods

This section describes the following methods:

- download
- cancelDownload
- deleteDownloadedFile
- downloadStatusQuery
- listPending
- upload

### download

Downloads the file located at the target URI, and returns a ticket unique to the download event. When subscribe is set to false the onSuccess handler is called only when the download request is sent. To determine when the download has completed, you can set the subscribe parameter to true, causing the onSuccess handler to be called periodically with progress updates. The download is complete when the handler receives a response with a completed attribute value of true. Another option is to make a call to the downloadStatusQuery function at any point with the ticket received from a download request.

If the target filename is not explicitly specified in the call and a file with the same name already exists, the download manager appends an underscore and a number (_1, _2, and so on) to avoid overwriting the existing copy of the file. If you specify the target filename in the call, any existing file with the same name is overwritten.

Required parameter:

- target

#### Parameters

Parameter | Type | Description
--- | --- | ---
target | string | URL of the form "http://file" or "https://file" where file is a well-formed URI targeting a downloadable file.
mime | string | The MIME type of the file.
targetDir | string | The local directory in which to save the file. This directory must be beneath /media/internal and will default to /media/internal/downloads if not specified.
targetFilename | string | The local file name to use when saving the file.
keepFilenameOnRedirect | boolean | When the download URL redirects, setting keepFilenameOnRedirect to true preserves the original target filename. This parameter is ignored if targetFilename is specified.
subscribe | boolean | If set to true, download() calls the onSuccess handler periodically with updates during the file download. If set to false, download() calls the onSuccess handler when the download request is sent (not when it completes).

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | Set to true if the call to download() succeeded.
ticket | number | A ticket, unique to each download request, for use in other operations on the download.
url | string | URI of the downloaded file.
subscribed | boolean | Set to true if subscribed to downloads from that URI.
amountReceived | number | The number of bytes received so far.
amountTotal | number | The total number of bytes downloaded.
completionStatusCode | string | A code indicating the completion status.
completed | boolean | Indicates whether the download is complete.
target | string | A path to the local downloaded file.
mimetype | string | The MIME type of the file.
size | number | The size of the file.

onFailure

Attribute | Type | Description
--- | --- | ---
ticket | number | A ticket, unique to each download request, for use in other operations on the download.
url | string | URI of the downloaded file.
completionStatusCode | number | A code indicating the completion status.
completed | boolean | Indicates whether the download is complete.

#### Example

>     this.controller.serviceRequest('palm://com.palm.downloadmanager/', {
>       method: 'download',
>       parameters: {
>           target: "http://developer.palm.com/download/attachments/38731952/palm-mojo-styling-07.xls",
>           mime: "application/xls",
>           targetDir : "/media/internal/files/",
>           targetFilename : "my-override-filename.xls",
>           keepFilenameOnRedirect: false,
>           subscribe: true
>       },
>       onSuccess: function (resp){Mojo.Log.info(Object.toJSON(resp))},
>       onFailure : function (e){Mojo.Log.info(Object.toJSON(e))}
>     });

### cancelDownload

Cancels the download specified by the ticket.

Required parameter:

- ticket

#### Parameters

Parameter | Type | Description
--- | --- | ---
ticket | number | The ticket returned by a call to download().

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | Set to true if the call to cancelDownload() succeeded.
ticket | number | The ticket passed in during the call.
url | string | The URI of the downloaded file.
amountReceived | number | The number of bytes received before download was cancelled.

onFailure

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | Set to true if the call to cancelDownload() succeeded.

#### Example

>     this.controller.serviceRequest('palm://com.palm.downloadmanager/', {
>       method: 'cancelDownload',
>       parameters: {"ticket":ticket},
>       onSuccess: function (resp){Mojo.Log.info(resp.ticket)},
>       onFailure: function (e){ Mojo.Log.info(Object.toJSON(e))}
>     });

### deleteDownloadedFile

Deletes the file specified by the download ticket.

Required parameter:

- ticket

#### Parameters

Parameter | Type | Description
--- | --- | ---
ticket | number | The ticket returned by a call to download().

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | Set to true if the call to deleteDownloadedFile() succeeded.
ticket | number | The ticket passed in during the call.
url | string | The URI of the downloaded file.
amountReceived | number | The number of bytes received.

onFailure

Attribute | Type | Description
--- | --- | ---
ticket | string | The ticket passed in during the call.
returnValue | boolean | Set to true if the call to deleteDownloadedFile() succeeded.

#### Example

>     this.controller.serviceRequest('palm://com.palm.downloadmanager/', {
>       method: 'deleteDownloadedFile',
>       parameters: {"ticket":ticket},
>       onSuccess : function (resp){Mojo.Log.info(Object.toJSON(resp))},
>       onFailure : function (e){ Mojo.Log.info(Object.toJSON(e))}
>     });

### downloadStatusQuery

Returns the status of the download specified by the ticket.

Required parameter:

- ticket

#### Parameters

Parameter | Type | Description
--- | --- | ---
ticket | number | The ticket returned by a call to download().

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
ticket | number | The ticket passed in during the call.
url | string | The URI of the downloaded file.
amountReceived | number | The number of bytes received.
amountTotal | number | The total number of bytes.
completionStatusCode | number | A code indicating the completion status.
target | string | A path to the local downloaded file.
completed | boolean | Indicates whether the download is complete.
mimetype | string | The MIME type of the file.
size | number | The size of the file.

onFailure

Attribute | Type | Description
--- | --- | ---
errorCode | string | A string representing the error code.
returnValue | boolean | Set to true if the call to downloadStatusQuery() succeeded.

#### Example

>     this.controller.serviceRequest('palm://com.palm.downloadmanager/', {
>       method: 'downloadStatusQuery',
>       parameters: {"ticket" : ticket},
>       onSuccess: function (resp){Mojo.Log.info(resp.ticket)},
>       onFailure: function (e){ Mojo.Log.info(Object.toJSON(e))}
>     });

### listPending

Lists the pending downloads.

#### Parameters

- None.

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | Set to true if the call to listPending() succeeded.
count | number | The number of downloads in progress.
downloads | JSON | If downloads are in progress, JSON objects, each representing a download, with the following attributes: ownerID (number)– the owner of the download. ticket (number)– the ticket associated with the download. url (string)–the URI to the downloaded file. destpath (string)– the path to the local target. destFile (string)– the local target filename. bytesCompleted (number)– the number of bytes downloaded so far. bytesTotal (number)– the number of bytes in the file. If no downloads are in progress, this object is absent.

onFailure

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | Set to true if the call to listPending() succeeded.

#### Example

>     this.controller.serviceRequest('palm://com.palm.downloadmanager/', {
>       method: 'listPending',
>       parameters: {},
>       onSuccess: function (resp){Mojo.Log.info(Object.toJSON(resp))},
>       onFailure: function (e){ Mojo.Log.info(Object.toJSON(e))}
>     });

### upload

Uploads the specified file to the target URI, and returns a ticket unique to the upload event. When subscribe is set to false, the onSuccess handler is called only when the upload request is sent. To determine when the upload has completed, you can set the subscribe parameter to true, causing the onSuccess handler to be called periodically with progress updates. The upload is complete when the handler receives a response with a completed attribute value of true.

On completing the upload, the upload method sends the following object to all subscribed apps for both success and failure cases:

Attribute | Type | Description
--- | --- | ---
ticket | number | A ticket, unique to each upload request, for use in other operations on the upload.
sourceFile | string | Path to the local file uploaded.
url | string | The URL to which to post the file.
completed | boolean | Indicates whether the upload is completed.
completionCode | number | A code indicating the completion status.
httpCode | number | HTTP return code, as described in http://www.w3.org/Protocols/HTTP/HTRESP.html
responseString | string | Server response to the POST request.

Required parameters:

- fileName
- url

#### Parameters

Parameter | Type | Description
--- | --- | ---
fileName | string | Path to the local file to be uploaded.
url | string | The URL to which to post the file.
fileLabel | string | The label portion of the file name (as opposed to the file extension).
contentType | string | The MIME type of the file.
postParameters | object | An object containing key/data/content triplets to support parameters required by the server to which the file is uploaded: key (string)–the name of the header. data (string)–the value of the header. contentType (string)–the type of the header value (defaults to text/plain).
cookies | object | Key-value pairs that carry additional optional information with the upload, in the format: cookies: { "key1": "val1", "key2": "val2", ...}
customHttpHeaders | object | Values to include in the HTTP headers, in the format: customHttpHeaders: [ "val1", "val2", ...]
subscribe | boolean | If set to true, upload() calls the onSuccess handler periodically with updates during the file upload. If set to false, calls the onSuccess handler only when the upload request is sent.

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | Set to true if the call to upload() succeeded.
ticket | number | A ticket, unique to each upload request, for use in other operations on the upload.
subscribed | boolean | Set to true if subscribed to updates on the upload request.

onFailure

Attribute | Type | Description
--- | --- | ---
returnValue | boolean | Set to true if the call to upload() succeeded.
ticket | number | A ticket, unique to each upload request, for use in other operations on the upload.
errorCode | string | One of the following error codes: url parameter missing fileName parameter missing failed to start upload

#### Example

>     this.controller.serviceRequest('palm://com.palm.downloadmanager/', {
>       method: 'upload',
>       parameters: {
>           'fileName': "icon.png",
>           'url': 'http://www.mytesturl.com/directory/path',
>           'contentType': 'img',
>           subscribe: true
>       },
>       onSuccess: function (resp){
>           Mojo.Log.info('Success : ' + Object.toJSON(resp));
>       },
>       onFailure: function (e){
>           Mojo.Log.info('Failure : ' + Object.toJSON(resp));
>       }.bind(this)
>     });