Download: Downloading Remote Objects by HTTP Request

This tutorial demonstrates how you can manage and monitor downloads.

The Download API is mandatory for the Tizen mobile profile, but optional for the wearable profile. This means that it is supported in all mobile devices, but may not be supported in all wearable devices. The Download API is supported on all Tizen Emulators.

Warm-up

Become familiar with the Download API basics by learning about:

Managing Downloads
Start, pause, and cancel downloading a file.
Checking the Download State and Information
Check whether a download is currently ongoing, failed, paused, or completed, and retrieve the download information.

Task

In the Download Manager task, we will walk through how to download URL content to the device storage.

Managing Downloads

To provide the user access to Internet resources, you must learn how to manage download operations:

Create an instance of the DownloadRequest interface (in mobile and wearable applications) that defines the URL of the file to be downloaded:
```
var downloadRequest = new tizen.DownloadRequest("http://download.tizen.org/tools/README.txt", "downloads");
```
The final parameter (downloads) defines the folder where the downloaded content is stored. The parameter uses a relative folder location defined in the Filesystem API (in mobile and wearable applications). The folder is not an absolute folder location, but instead uses a virtual root location (downloads is the default download location in the virtual root).

It is not possible to download anything when the device is not connected to a network. To check whether any connection is available, use the getPropertyValue() method of the SystemInfo interface (in mobile and wearable applications):

tizen.systeminfo.getPropertyValue("NETWORK", function(networkInfo)
                                  {
                                     if (networkInfo.networkType === "NONE")
                                     {
                                        console.log("Network connection is not available. Download is not possible.");
                                        downloadRequest = null;
                                     }
                                  });

Define the event handlers for different download process notifications using the DownloadCallback listener interface (in mobile and wearable applications):

var listener = 
{
   /* When the download progresses (interval is platform-dependent) */
   onprogress: function(id, receivedSize, totalSize) 
   {
      console.log('Received with id: ' + id + ', ' + receivedSize + '/' + totalSize);
   },

   /* When the user pauses the download */
   onpaused: function(id) 
   {
      console.log('Paused with id: ' + id);
   },

   /* When the user cancels the download */
   oncanceled: function(id) 
   {
      console.log('Canceled with id: ' + id);
   },

   /* When the download is completed */
   oncompleted: function(id, fullPath) 
   {
      console.log('Completed with id: ' + id + ', full path: ' + fullPath);
   },

   /* When the download fails */
   onfailed: function(id, error) 
   {
      console.log('Failed with id: ' + id + ', error name: ' + error.name);
   }
};

To start the download of the HTML file from the Internet, use the start() method of the DownloadManager interface (in mobile and wearable applications):
```
downloadId = tizen.download.start(downloadRequest, listener);
```
The start() method returns a unique identifier for the download operation.
During the download:
1. To pause the download, use the pause() method with the download ID:
```
tizen.download.pause(downloadId);
```
2. To resume the download, use the resume() method with the download ID:
```
tizen.download.resume(downloadId);
```
3. To cancel the download, use the cancel() method with the download ID:
```
tizen.download.cancel(downloadId);
```

Checking the Download State and Information

To provide the user access to Internet resources, you must learn how to check the state of a download operation and retrieve relevant information:

To be able to monitor the download state, you need the download ID, which is the return value of the start() method of the DownloadManager interface (in mobile and wearable applications):
```
downloadId = tizen.download.start(downloadRequest, listener); 
```
Use the getState() method with the download ID as a parameter to get the current state:
```
var state = tizen.download.getState(downloadId);
```
The method returns a DownloadState enumerator value (in mobile and wearable applications).
Use the getDownloadRequest() method with the download ID as a parameter to get the download request details that the user has previously set:
```
var downloadRequest = tizen.download.getDownloadRequest(downloadId);
```
The method returns the DownloadRequest information (in mobile and wearable applications) which is used as the parameter when starting the download.
Use the getMIMEType() method with the download ID as a parameter to get the MIME type of the file that you have started downloading:
```
var MIMEType = tizen.download.getMIMEType(downloadId);
```
The method returns the MIME type the target file which has started downloading.