Download API

This API provides methods to asynchronously download the contents of a URL to a storage.

Remark: In order to access files, a proper privilege has to be defined additionally:

For more information on the Download features, see Download Guide.

Since: 2.0

Table of Contents

Summary of Interfaces and Methods

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

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

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

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;
  };
  Tizen implements DownloadManagerObject;

Since: 2.0

Attributes

  • readonly DownloadManager download
    Object representing a download manager.

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

Since: 2.0

Constructors

Constructor (DOMString, DOMString?, DOMString?, DownloadNetworkType?, DownloadHTTPHeaderFields?) 
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);
  };

Since: 2.0

Methods

start
Starts a download operation with the specified URL information. 
long start(DownloadRequest downloadRequest, optional DownloadCallback? downloadCallback);

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 or the application does not have privilege to access the storage. For more information, see Storage privileges.

    • with error type UnknownError, if any other error occurs.

Code example:

/* Checks whether Download API is supported 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 downloadId_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);

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

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);
resume
Resumes a paused download operation that is specified by the downloadId parameter. 
void resume(long downloadId);

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);
getState
Gets the download state of an operation synchronously with the specified ID. 
DownloadState getState(long downloadId);

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);
getDownloadRequest
Gets the DownloadRequest object from a given ID. 
DownloadRequest getDownloadRequest(long downloadId);

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);
getMIMEType
Gets the MIME type of the downloaded file. 
DOMString getMIMEType(long downloadId);

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:

/* Gets 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);

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

/* Starts 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);

/* Adds the listener. */
tizen.download.setListener(downloadId, listener);

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

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

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

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

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

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

Since: 2.0

Parameters:

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

3. Related Feature

Method tizen.systeminfo.getCapability() can be used in application runtime to check whether this API is supported.

DownloadNetworkType WIFI 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 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" };
  Tizen implements DownloadManagerObject;
  [NoInterfaceObject] interface DownloadManagerObject {
    readonly attribute DownloadManager download;
  };
  [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);
  };
};
    Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
    For details, see the Content License.