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:
-
Managing downloads
You can start, pause, resume, cancel, and abandon a download of content using the
DownloadManager
interface (in mobile, wearable, and TV applications). -
Checking the download state and information
You can access the current download state and retrieve the download information using the
DownloadManager
interface. The states are defined in theDownloadState
enumerator (in mobile, wearable, and TV applications).
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:
-
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). -
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 theSystemInfo
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; } });
-
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); } };
-
To start downloading the file from the Internet, use the
start()
method of theDownloadManager
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);
-
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.
-
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. -
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. -
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. -
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:
-
To be able to monitor the download state, you need the download ID, which is the return value of the
start()
method of theDownloadManager
interface (in mobile, wearable, and TV 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, wearable, and TV 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, wearable, and TV 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);
Related information
- Dependencies
- Tizen 2.4 and Higher for Mobile
- Tizen 2.3.1 and Higher for Wearable
- Tizen 3.0 and Higher for TV