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