Samsung Electronics logo

Samsung Web API: Download


Introduction

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


Table of Contents


Summary of Interfaces and Methods

Interface Method
DownloadManagerObject
DownloadRequest
DownloadManager long start(DownloadRequest downloadRequest, 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 fullPath)
void onfailed(long downloadId, WebAPIError error)

1. Type Definitions

1.1. DownloadHTTPHeaderFields

A set of HTTP header fields.

    typedef object DownloadHTTPHeaderFields;

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

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

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 webapis object. There will be a webapis.download object that allows access to the functionality of the Download API.

    [NoInterfaceObject] interface DownloadManagerObject {
        readonly attribute DownloadManager download;
    };
    WebAPIs implements DownloadManagerObject;

2.2. DownloadRequest

This 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

DOMString url

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

DOMString? destination

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

An attribute to store the file name for the specified URL.

If the file name is not given or an empty string, the original file name from URL is used.

The default value is an empty string.

DownloadNetworkType? networkType

An attribute to store the allowed network type.

If the network type is not given, all network type are allowed.

The default value is "ALL".

DownloadHTTPHeaderFields? httpHeader

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 webapis.DownloadRequest("http://download.tizen.org/tools/README.txt");
 req.httpHeader["Pragma"] = "no-cache";
 req.httpHeader["Cookie"] = "version=1; Skin=new";
 req.httpHeader["X-Agent"] = "Sample App";
 

2.3. DownloadManager

This interface handles requests for downloading. Each step of download operation will be 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);
   };

METHODS

start

Starts a download operation with the specified URL information.

Signature
long start(DownloadRequest downloadRequest, optional DownloadCallback? downloadCallback);
Parameters
  • downloadRequest
    • Optional: No.
    • Nullable: No.
    • Type: DownloadRequest.
    • Description: The URL and destination information of the object to download.
  • downloadCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: DownloadCallback.
    • Description: The method to invoke when the download state changes or an error occurs.
Return value
long An identifier for each download operation.
Exceptions
  • WebAPIException:

    with error type UnknownError if any other error occurs.

    with error type SecurityError, if the application does not have the privilege to call this method.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type NotSupportedError, if this feature is not supported.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

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, fullPath) {
     console.log('Completed with id: ' + id + ', full path: ' + fullPath);
   },
   onfailed: function(id, error) {
     console.log('Failed with id: ' + id + ', error name: ' + error.name);
   }
 };

 // Starts downloading of the file from the Web with the corresponding callbacks.
 var downloadRequest = new webapis.DownloadRequest("http://download.tizen.org/tools/README.txt", "documents");
 downloadId = webapis.download.start(downloadRequest, listener);
 

cancel

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

Signature
void cancel(long downloadId);
Parameters
  • downloadId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: The ID of the ongoing download operation to stop.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type NotSupportedError, if this feature is not supported.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

    with error type NotFoundError, if the identifier does not match any download operation in progress.

Code example
 // Cancels the ongoing download operation with the specified id.
 webapis.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.

Signature
void pause(long downloadId);
Parameters
  • downloadId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: The ID of the ongoing download operation to pause.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type NotSupportedError, if this feature is not supported.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

    with error type NotFoundError, if the identifier does not match any download operation in progress.

Code example
 // Pauses the ongoing download operation with the specified id.
 webapis.download.pause(downloadId);
 

resume

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

Signature
void resume(long downloadId);
Parameters
  • downloadId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: The ID of the paused download operation to be resume.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type NotSupportedError, if this feature is not supported.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

    with error type NotFoundError, if the identifier does not match any download operation in progress.

Code example
 // Resumes the paused download operation with the specified id.
 webapis.download.resume(downloadId);
 

getState

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

Signature
DownloadState getState(long downloadId);
Parameters
  • downloadId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: The ID to get the current state of download operation.
Return value
DownloadState The current download state of the specified ID.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type NotSupportedError, if this feature is not supported.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

    with error type NotFoundError, if the identifier does not match any download operation in progress.

Code example
 // Gets the state of the download operation with the given id.
 var state = webapis.download.getState(downloadId);
 

getDownloadRequest

Gets the DownloadRequest object from a given id.

Signature
DownloadRequest getDownloadRequest(long downloadId);
Parameters
  • downloadId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: The ID to get the download request information.
Return value
DownloadRequest The download request information of the given id.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type NotSupportedError, if this feature is not supported.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

    with error type NotFoundError, if the identifier does not match any download operation in progress.

Code example
 // Gets the download request information with the given id.
 var downloadRequest = webapis.download.getDownloadRequest(downloadId);
 

getMIMEType

Gets the MIME type of the downloaded file.

Signature
DOMString getMIMEType(long downloadId);

This function will return a valid MIME type when the download operation has been started and successfully retrieved the file header.

Parameters
  • downloadId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: The ID to get the MIME type information.
Return value
DOMString The MIME type of the downloaded file.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type NotSupportedError, if this feature is not supported.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

    with error type NotFoundError, if the identifier does not match any download operation in progress.

Code example
 // Get the MIME type of the download operation with the given id.
 var MIMEtype = webapis.download.getMIMEType(downloadId);
 

setListener

Sets the download callback to the download operation of given id. It's possible to change or register the listener of download operation using the saved id.

Signature
void setListener(long downloadId, DownloadCallback downloadCallback);
Parameters
  • downloadId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: The ID to set the download callback.
  • downloadCallback
    • Optional: No.
    • Nullable: No.
    • Type: DownloadCallback.
    • Description: The method to invoke when the download state changes or an error occurs.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type NotSupportedError, if this feature is not supported.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

    with error type NotFoundError, if the identifier does not match any download operation in progress.

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 webapis.DownloadRequest("http://download.tizen.org/tools/README.txt", "documents");
 downloadId = webapis.download.start(downloadRequest);

 // Add the listener.
 webapis.download.setListener(downloadId, listener);
 

2.4. DownloadCallback

This interface defines notification callbacks for the 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 fullPath);

       void onfailed(long downloadId, WebAPIError error);
   };

METHODS

onprogress

Called when a download is successful and it called multiple times as the download progresses. The interval between onprogress() callback is platform-dependent. When the download is started, the receivedSize can be 0.

Signature
void onprogress(long downloadId, unsigned long long receivedSize, unsigned long long totalSize);
Parameters
  • downloadId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: The ID of the corresponding download operation.
  • receivedSize
    • Optional: No.
    • Nullable: No.
    • Type: unsigned long long.
    • Description: The size of data received in bytes.
  • totalSize
    • Optional: No.
    • Nullable: No.
    • Type: unsigned long long.
    • Description: The total size of data to receive in bytes.

onpaused

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

Signature
void onpaused(long downloadId);
Parameters
  • downloadId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: The ID of the corresponding download operation.

oncanceled

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

Signature
void oncanceled(long downloadId);
Parameters
  • downloadId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: The ID of the corresponding download operation.

oncompleted

Called when the download operation is completed with the final full path. If the same file name already exists in the destination, it is changed according to the platform policy and delivered in this callback.

Signature
void oncompleted(long downloadId, DOMString fullPath);
Parameters
  • downloadId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: The ID of the corresponding download operation.
  • fullPath
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The final full path for the downloaded file.

onfailed

Called when the download operation fails.

Signature
void onfailed(long downloadId, WebAPIError error);
Parameters
  • downloadId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: The ID of the corresponding download operation.
  • error
    • Optional: No.
    • Nullable: No.
    • Type: WebAPIError.
    • Description: The reason for the download failure.

3. 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;
    };
    WebAPIs 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 fullPath);

       void onfailed(long downloadId, WebAPIError error);
   };
};