Content Downloads

You can download files from the Internet and monitor the progress and status of ongoing downloads.

The Download API is mandatory for the Tizen Mobile profile, but optional for wearable and TV profiles. This means that it is supported on all mobile devices, but may not be supported on all wearable and TV devices. The Download API is supported on all Tizen emulators.

The main features of the Download API include the following:

Prerequisites

To use the Download API (in mobile, wearable, and TV applications), the application has to request permission by adding the following privilege to the config.xml file:

<tizen:privilege name="http://tizen.org/privilege/download"/>

Managing downloads

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

  1. Create an instance of the DownloadRequest interface (in mobile, wearable, and TV 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, wearable, and TV 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).

  2. 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, wearable, and TV applications):

    tizen.systeminfo.getPropertyValue('NETWORK', function(networkInfo) {
        if (networkInfo.networkType === 'NONE') {
            console.log('Network connection is not available.
                         Download is not possible.');
            downloadRequest = null;
        }
    });
    
  3. Define the event handlers for different download process notifications using the DownloadCallback listener interface (in mobile, wearable, and TV 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);
        }
    };
    
  4. To start downloading the file from the Internet, use the start() method of the DownloadManager interface (in mobile, wearable, and TV applications):

    downloadId = tizen.download.start(downloadRequest, listener);
    

    The start() method returns a unique identifier for the download operation.

    You can check the status of the download operation by calling the getState() method with the download ID:

    tizen.download.getState(downloadId);
    
  5. During the download operation, you can modify the download state by using the following methods:

    Note

    For downloading small file with using high speed connection, the download operation completes almost instantly.

    1. To pause the download, use the pause() method with the download ID:

      tizen.download.pause(downloadId);
      

      If the current state is DOWNLOADING or QUEUED, calling the pause() method changes the download state to PAUSED.

    2. To resume the download, use the resume() method with the download ID:

      tizen.download.resume(downloadId);
      

      If the current state is PAUSED, CANCELED, or FAILED, calling the resume() method changes the download state to DOWNLOADING or QUEUED.

    3. To cancel the download, use the cancel() method with the download ID:

      tizen.download.cancel(downloadId);
      

      If the current state is DOWNLOADING or QUEUED, calling the cancel() method changes the download state to CANCELED.

    4. To abandon the download, use the abandon() method with the download ID:

      tizen.download.abandon(downloadId);
      

      For any abandoned download operation, the resources are already released. Thus, the download operation cannot be resumed.

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 by following these steps:

  1. 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, wearable, and TV applications):

    downloadId = tizen.download.start(downloadRequest, listener);
    
  2. 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, wearable, and TV applications).

  3. 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, wearable, and TV applications) which is used as the parameter when starting the download.

  4. 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);
    
  • Dependencies
    • Tizen 2.4 and Higher for Mobile
    • Tizen 2.3.1 and Higher for Wearable
    • Tizen 3.0 and Higher for TV