Download API

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

Summary of Interfaces and Methods

Interface

Method

Interface	Method
DownloadManagerObject
DownloadRequest
DownloadManager	long start (DownloadRequest downloadRequest, optional DownloadCallback? downloadCallback) void cancel (long downloadId) void pause (long downloadId) void resume (long downloadId) DownloadState getState (long downloadId) DownloadRequest getDownloadRequest (long downloadId) DOMString getMIMEType (long downloadId) void setListener (long downloadId, DownloadCallback downloadCallback)
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)

1. Type Definitions

1.1. DownloadHTTPHeaderFields

A set of HTTP header fields.

    typedef object DownloadHTTPHeaderFields;

Attributes

Since 2.1

The key / value type of each HTTP header field should be DOMString.

1.2. DownloadState

An enumerator to indicate the state of a download operation.

    enum DownloadState { "QUEUED", "DOWNLOADING", "PAUSED", "CANCELED", "COMPLETED", "FAILED" };

Attributes

Since 2.0

The following values are supported:

QUEUED - Indicates that the download operation is listed in a queue.
DOWNLOADING - Indicates that the download operation is in progress.
PAUSED - Indicates that the download operation is in a paused state by user request.
CANCELED - Indicates that the download operation is canceled by user request.
COMPLETED - Indicates that the download operation is in a completed state.
FAILED - Indicates that the download operation has failed due to some reasons.

1.3. DownloadNetworkType

An enumerator to indicate the network type.

    enum DownloadNetworkType { "CELLULAR", "WIFI", "ALL" };

Attributes

Since 2.1

The following values are supported:

CELLULAR - Indicates that the download operation is allowed in the cellular network only.
WIFI - Indicates that the download operation is allowed in the Wi-Fi network only.
ALL - Indicates that the download operation is allowed in all network types.

2. Interfaces

2.1. DownloadManagerObject

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

Attributes

    Tizen implements DownloadManagerObject;

Attributes

Since 2.0

2.2. DownloadRequest

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

Attributes

Since 2.0

Constructors

DownloadRequest(DOMString url, optional DOMString? destination, optional DOMString? fileName, optional DownloadNetworkType? networkType, optional DownloadHTTPHeaderFields? httpHeader);

Attributes

DOMString url

An attribute to store the URL of the object to download.

Since 2.0
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.

Since 2.0
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.

The default value is an empty string.

Since 2.0
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.

Since 2.1

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.

Since 2.1

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";

2.3. DownloadManager

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

Attributes

Since 2.0

Methods

start

Starts a download operation with the specified URL information.

long start(DownloadRequest downloadRequest, optional DownloadCallback? downloadCallback);

Attributes

Since 2.0

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:

downloadRequest: The URL and destination information of the object to download.
downloadCallback [optional] [nullable]: The method to invoke when the download state changes or an error occurs.

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:

WebAPIException
- 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.

Code example:

 // 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.");
 }

Attributes

cancel

Cancels an ongoing download operation that is specified by the downloadId parameter.

void cancel(long downloadId);

Attributes

Since 2.0

Parameters:

downloadId: The ID of the ongoing download operation to stop.

Exceptions:

WebAPIException
- with error type NotFoundError, if the identifier does not match any download operation in progress.
- with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
- with error type InvalidValuesError, if any of the input parameters contain an invalid value.
- with error type UnknownError, if any other error occurs.

Code example:

 // Cancels the ongoing download operation with the specified ID.
 tizen.download.cancel(downloadId);

Attributes

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

Attributes

Since 2.0

Parameters:

downloadId: The ID of the ongoing download operation to pause.

Exceptions:

WebAPIException
- with error type NotFoundError, if the identifier does not match any download operation in progress.
- with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
- with error type InvalidValuesError, if any of the input parameters contain an invalid value.
- with error type UnknownError, if any other error occurs.

Code example:

 // Pauses the ongoing download operation with the specified ID.
 tizen.download.pause(downloadId);

Attributes

resume

Resumes a paused download operation that is specified by the downloadId parameter.

void resume(long downloadId);

Attributes

Since 2.0

Parameters:

downloadId: The ID of the paused download operation to resume.

Exceptions:

WebAPIException
- with error type NotFoundError, if the identifier does not match any download operation in progress.
- with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
- with error type InvalidValuesError, if any of the input parameters contain an invalid value.
- with error type UnknownError, if any other error occurs.

Code example:

 // Resumes the paused download operation with the specified ID.
 tizen.download.resume(downloadId);

Attributes

getState

Gets the download state of an operation synchronously with the specified ID.

DownloadState getState(long downloadId);

Attributes

Since 2.0

Parameters:

downloadId: The ID to get the current state of the download operation.

Return value:

DownloadState The current download state of the specified ID.

Exceptions:

WebAPIException
- with error type NotFoundError, if the identifier does not match any download operation in progress.
- with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
- with error type InvalidValuesError, if any of the input parameters contain an invalid value.
- with error type UnknownError, if any other error occurs.

Code example:

 // Gets the state of the download operation with the given ID.
 var state = tizen.download.getState(downloadId);

Attributes

getDownloadRequest

Gets the DownloadRequest object from a given ID.

DownloadRequest getDownloadRequest(long downloadId);

Attributes

Since 2.0

Parameters:

downloadId: The ID to get the download request information.

Return value:

DownloadRequest The download request information of the given ID.

Exceptions:

WebAPIException
- with error type NotFoundError, if the identifier does not match any download operation in progress.
- with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
- with error type InvalidValuesError, if any of the input parameters contain an invalid value.
- with error type UnknownError, in any other error case.

Code example:

 // Gets the download request information with the given ID.
 var downloadRequest = tizen.download.getDownloadRequest(downloadId);

Attributes

getMIMEType

Gets the MIME type of the downloaded file.

DOMString getMIMEType(long downloadId);

Attributes

Since 2.0

Remark : This function returns a valid MIME type when the download operation has been started and successfully retrieves the file header.

Parameters:

downloadId: The ID to get the MIME type information.

Return value:

DOMString The MIME type of the downloaded file.

Exceptions:

WebAPIException
- with error type NotFoundError, if the identifier does not match any download operation in progress.
- with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
- with error type InvalidValuesError, if any of the input parameters contain an invalid value.
- with error type UnknownError, in any other error case.

Code example:

 // Get the MIME type of the download operation with the given ID.
 var MIMEtype = tizen.download.getMIMEType(downloadId);

Attributes

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

Attributes

Since 2.0

Parameters:

downloadId: The ID to set the download callback.
downloadCallback: The method to invoke when the download state changes or an error occurs.

Exceptions:

WebAPIException
- with error type NotFoundError, if the identifier does not match any download operation in progress.
- with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
- with error type InvalidValuesError, if any of the input parameters contain an invalid value.
- with error type UnknownError, in any other error case.

Code example:

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

Attributes

2.4. DownloadCallback

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

Attributes

Since 2.0

Methods

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

Attributes

Since 2.0

Parameters:

downloadId: The ID of the corresponding download operation.
receivedSize: The size of data received in bytes.
totalSize: The total size of data to receive in bytes.

onpaused

Called when the download operation is paused by the pause() method.

void onpaused(long downloadId);

Attributes

Since 2.0

Parameters:

downloadId: The ID of the corresponding download operation.

oncanceled

Called when the download operation is canceled by the cancel() method.

void oncanceled(long downloadId);

Attributes

Since 2.0

Parameters:

downloadId: The ID of the corresponding download operation.

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

Attributes

Since 2.0

Parameters:

downloadId: The ID of the corresponding download operation.
path: The final full path or virtual path for the downloaded file.

onfailed

Called when the download operation fails.

void onfailed(long downloadId, WebAPIError error);

Attributes

Since 2.0

Parameters:

downloadId: The ID of the corresponding download operation.
error: The reason for download failure.

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:

http://tizen.org/feature/network.wifi

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:

http://tizen.org/feature/network.telephony

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:

http://tizen.org/feature/network.ethernet

For more information, see Application Filtering.

4. Full WebIDL

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

Download API

Summary of Interfaces and Methods

1. Type Definitions

1.1. DownloadHTTPHeaderFields

Attributes

1.2. DownloadState

Attributes

1.3. DownloadNetworkType

Attributes

2. Interfaces

2.1. DownloadManagerObject

Attributes

Attributes

2.2. DownloadRequest

Attributes

Constructors

Attributes

Attributes

2.3. DownloadManager

Attributes

Methods

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

2.4. DownloadCallback

Attributes

Methods

Attributes

Attributes

Attributes

Attributes

Attributes

3. Related Feature

4. Full WebIDL