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:
|
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:
|
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:
|
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) });