This API provides methods to asynchronously download the contents of a URL to a storage.
For more information on the Download features, see Download Guide.
Since 2.0
Interface
Method
A set of HTTP header fields.
typedef object DownloadHTTPHeaderFields;
Since 2.1
The key / value type of each HTTP header field should be DOMString.
An enumerator to indicate the state of a download operation.
enum DownloadState { "QUEUED", "DOWNLOADING", "PAUSED", "CANCELED", "COMPLETED", "FAILED" };
The following values are supported:
An enumerator to indicate the network type.
enum DownloadNetworkType { "CELLULAR", "WIFI", "ALL" };
This interface defines the default download manager that is instantiated by the Tizen object. The tizen.download object allows access to the functionality of the Download API.
[NoInterfaceObject] interface DownloadManagerObject { readonly attribute DownloadManager download; };
Tizen implements DownloadManagerObject;
The DownloadRequest interface defines the download request object.
[Constructor(DOMString url, optional DOMString? destination, optional DOMString? fileName, optional DownloadNetworkType? networkType, optional DownloadHTTPHeaderFields? httpHeader)] interface DownloadRequest { attribute DOMString url; attribute DOMString? destination; attribute DOMString? fileName; attribute DownloadNetworkType? networkType; attribute DownloadHTTPHeaderFields? httpHeader; };
DownloadRequest(DOMString url, optional DOMString? destination, optional DOMString? fileName, optional DownloadNetworkType? networkType, optional DownloadHTTPHeaderFields? httpHeader);
DOMString url
An attribute to store the URL of the object to download.
DOMString destination [nullable]
An attribute to store the folder path of the destination folder to which a requested file object will be downloaded.
If the destination is not specified or is an empty string, the file will be downloaded to the default storage: "Downloads". For more information, see Filesystem API.
The default value is an empty string.
DOMString fileName [nullable]
An attribute to store the file name for the specified URL.
If the file name is not given or is an empty string, the original file name from the URL is used.
DownloadNetworkType networkType [nullable]
An attribute to store the allowed network type.
If the network type is not given, all network types are allowed.
The default value is ALL.
DownloadHTTPHeaderFields httpHeader [nullable]
An attribute to store extra HTTP header fields.
For more information about HTTP header fields, see RFC-2616
The default value is an empty object.
Code example:
var req = new tizen.DownloadRequest("http://download.tizen.org/tools/README.txt"); req.httpHeader["Pragma"] = "no-cache"; req.httpHeader["Cookie"] = "version=1; Skin=new"; req.httpHeader["X-Agent"] = "Tizen Sample App";
The DownloadManager interface handles requests for downloading. Each step of a download operation is informed through callbacks.
[NoInterfaceObject] interface DownloadManager { long start(DownloadRequest downloadRequest, optional DownloadCallback? downloadCallback) raises(WebAPIException); void cancel(long downloadId) raises(WebAPIException); void pause(long downloadId) raises(WebAPIException); void resume(long downloadId) raises(WebAPIException); DownloadState getState(long downloadId) raises(WebAPIException); DownloadRequest getDownloadRequest(long downloadId) raises(WebAPIException); DOMString getMIMEType(long downloadId) raises(WebAPIException); void setListener(long downloadId, DownloadCallback downloadCallback) raises(WebAPIException); };
start
Starts a download operation with the specified URL information.
long start(DownloadRequest downloadRequest, optional DownloadCallback? downloadCallback);
Privilege level: public
Privilege: http://tizen.org/privilege/download
Remark : To check if CELLULAR type is supported, use tizen.systeminfo.getCapability("http://tizen.org/feature/network.telephony")
Remark : To check if WIFI type is supported, use tizen.systeminfo.getCapability("http://tizen.org/feature/network.wifi")
Parameters:
Return value:
long An identifier for each download operation. If the network is not available for downloading, the return value is -1 since Tizen 2.3.
Exceptions:
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type NotSupportedError, if the networkType of the given DownloadRequest is not supported on a device.
with error type InvalidValuesError, if any of the input parameters contain an invalid value.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type UnknownError, if any other error occurs.
// Check if Download API is supported not on a device. var download_api_capability = tizen.systeminfo.getCapability("http://tizen.org/feature/download"); if (download_api_capability === false) { console.log("Download API is not supported on this device."); return; } var listener = { onprogress: function(id, receivedSize, totalSize) { console.log('Received with id: ' + id + ', ' + receivedSize + '/' + totalSize); }, onpaused: function(id) { console.log('Paused with id: ' + id); }, oncanceled: function(id) { console.log('Canceled with id: ' + id); }, oncompleted: function(id, path) { console.log('Completed with id: ' + id + ', path: ' + path); }, onfailed: function(id, error) { console.log('Failed with id: ' + id + ', error name: ' + error.name); } }; // Starts downloading the file from the Web with the corresponding callbacks. var downloadRequest = new tizen.DownloadRequest("http://download.tizen.org/tools/README.txt", "documents"); var downloadId = tizen.download.start(downloadRequest, listener); // If you want to download a large file through Wi-Fi, var wifi_capability = tizen.systeminfo.getCapability("http://tizen.org/feature/network.wifi"); var wifiDownloadRequest = new tizen.DownloadRequest("http://download.tizen.org/tools/archive/14.02.2/Ubuntu_12.04/qemu_1.6.0rc3.orig.tar.gz", "downloads", null, "WIFI"); if (wifi_capability === true) { var downlodId_wifi = tizen.download.start(wifiDownloadRequest, listener); } else { // If you call tizen.download.start(), NotSupportedError will be thrown. console.log("This device doesn't support Download API through Wi-Fi."); }
cancel
Cancels an ongoing download operation that is specified by the downloadId parameter.
void cancel(long downloadId);
with error type NotFoundError, if the identifier does not match any download operation in progress.
// Cancels the ongoing download operation with the specified ID. tizen.download.cancel(downloadId);
pause
Pauses an ongoing download operation that is specified by the downloadId parameter. The paused download operation can be resumed later by the resume() method.
void pause(long downloadId);
// Pauses the ongoing download operation with the specified ID. tizen.download.pause(downloadId);
resume
Resumes a paused download operation that is specified by the downloadId parameter.
void resume(long downloadId);
// Resumes the paused download operation with the specified ID. tizen.download.resume(downloadId);
getState
Gets the download state of an operation synchronously with the specified ID.
DownloadState getState(long downloadId);
DownloadState The current download state of the specified ID.
// Gets the state of the download operation with the given ID. var state = tizen.download.getState(downloadId);
getDownloadRequest
Gets the DownloadRequest object from a given ID.
DownloadRequest getDownloadRequest(long downloadId);
DownloadRequest The download request information of the given ID.
with error type UnknownError, in any other error case.
// Gets the download request information with the given ID. var downloadRequest = tizen.download.getDownloadRequest(downloadId);
getMIMEType
Gets the MIME type of the downloaded file.
DOMString getMIMEType(long downloadId);
Remark : This function returns a valid MIME type when the download operation has been started and successfully retrieves the file header.
DOMString The MIME type of the downloaded file.
// Get the MIME type of the download operation with the given ID. var MIMEtype = tizen.download.getMIMEType(downloadId);
setListener
Sets the download callback to the download operation of the given ID. It's possible to change or register the listener of the download operation using the saved ID.
void setListener(long downloadId, DownloadCallback downloadCallback);
var listener = { onprogress: function(id, receivedSize, totalSize) { console.log('Received with id: ' + id + ', ' + receivedSize + '/' + totalSize); }, onpaused: function(id) { console.log('Paused with id: ' + id); }, oncanceled: function(id) { console.log('Canceled with id: ' + id); }, oncompleted: function(id, fileName) { console.log('Completed with id: ' + id + ', file name: ' + fileName); }, onfailed: function(id, error) { console.log('Failed with id: ' + id + ', error name: ' + error.name); } }; // Start downloading the html file on the web with the corresponding callbacks. var downloadRequest = new tizen.DownloadRequest("http://download.tizen.org/tools/README.txt", "documents"); downloadId = tizen.download.start(downloadRequest); // Add the listener. tizen.download.setListener(downloadId, listener);
The DownloadCallback defines notification callbacks for a download state change or progress.
[Callback, NoInterfaceObject] interface DownloadCallback { void onprogress(long downloadId, unsigned long long receivedSize, unsigned long long totalSize); void onpaused(long downloadId); void oncanceled(long downloadId); void oncompleted(long downloadId, DOMString path); void onfailed(long downloadId, WebAPIError error); };
onprogress
Called when a download is successful and it is called multiple times as the download progresses. The interval between the onprogress() callback is platform-dependent. When the download is started, the receivedSize can be 0.
void onprogress(long downloadId, unsigned long long receivedSize, unsigned long long totalSize);
onpaused
Called when the download operation is paused by the pause() method.
void onpaused(long downloadId);
oncanceled
Called when the download operation is canceled by the cancel() method.
void oncanceled(long downloadId);
oncompleted
Called when the download operation is completed with the final full path or virtual path. If the same file name already exists in the destination, it is changed according to the platform policy and delivered in this callback.
void oncompleted(long downloadId, DOMString path);
onfailed
Called when the download operation fails.
void onfailed(long downloadId, WebAPIError error);
You can check if this API is supported with tizen.systeminfo.getCapability() and decide enable/disable codes that need this API.
DownloadNetworkType 'WIFI' or 'ALL' can be available on a Wi-Fi enabled device. To guarantee that the download application runs on a device with the Wi-Fi feature, declare the following feature requirements in the config file:
DownloadNetworkType 'CELLULAR' or 'ALL' can be available on a cellular-enabled device. To guarantee that the download application runs on a device with the cellular feature, declare the following feature requirements in the config file:
DownloadNetworkType 'ALL' can be available on a ethernet-enabled device. To guarantee that the download application runs on a device with the ethernet network feature, declare the following feature requirements in the config file:
For more information, see Application Filtering.
module Download { typedef object DownloadHTTPHeaderFields; enum DownloadState { "QUEUED", "DOWNLOADING", "PAUSED", "CANCELED", "COMPLETED", "FAILED" }; enum DownloadNetworkType { "CELLULAR", "WIFI", "ALL" }; [NoInterfaceObject] interface DownloadManagerObject { readonly attribute DownloadManager download; }; Tizen implements DownloadManagerObject; [Constructor(DOMString url, optional DOMString? destination, optional DOMString? fileName, optional DownloadNetworkType? networkType, optional DownloadHTTPHeaderFields? httpHeader)] interface DownloadRequest { attribute DOMString url; attribute DOMString? destination; attribute DOMString? fileName; attribute DownloadNetworkType? networkType; attribute DownloadHTTPHeaderFields? httpHeader; }; [NoInterfaceObject] interface DownloadManager { long start(DownloadRequest downloadRequest, optional DownloadCallback? downloadCallback) raises(WebAPIException); void cancel(long downloadId) raises(WebAPIException); void pause(long downloadId) raises(WebAPIException); void resume(long downloadId) raises(WebAPIException); DownloadState getState(long downloadId) raises(WebAPIException); DownloadRequest getDownloadRequest(long downloadId) raises(WebAPIException); DOMString getMIMEType(long downloadId) raises(WebAPIException); void setListener(long downloadId, DownloadCallback downloadCallback) raises(WebAPIException); }; [Callback, NoInterfaceObject] interface DownloadCallback { void onprogress(long downloadId, unsigned long long receivedSize, unsigned long long totalSize); void onpaused(long downloadId); void oncanceled(long downloadId); void oncompleted(long downloadId, DOMString path); void onfailed(long downloadId, WebAPIError error); }; };