public class

DownloadManager

extends Object
java.lang.Object
   ↳android.app.DownloadManager

Class Overview

The download manager is a system service that handles long-running HTTP downloads. Clients may request that a URI be downloaded to a particular destination file. The download manager will conduct the download in the background, taking care of HTTP interactions and retrying downloads after failures or across connectivity changes and system reboots. Instances of this class should be obtained through getSystemService(String) by passing DOWNLOAD_SERVICE. Apps that request downloads through this API should register a broadcast receiver for ACTION_NOTIFICATION_CLICKED to appropriately handle when the user clicks on a running download in a notification or from the downloads UI.

Summary

Nested Classes
classDownloadManager.QueryThis class may be used to filter download manager queries. 
classDownloadManager.RequestThis class contains all the information necessary to request a new download. 
Constants
StringACTION_DOWNLOAD_COMPLETEBroadcast intent action sent by the download manager when a download completes.
StringACTION_NOTIFICATION_CLICKEDBroadcast intent action sent by the download manager when the user clicks on a running download, either from a system notification or from the downloads UI.
StringACTION_VIEW_DOWNLOADSIntent action to launch an activity to display all downloads.
StringCOLUMN_BYTES_DOWNLOADED_SO_FARNumber of bytes download so far.
StringCOLUMN_DESCRIPTIONThe client-supplied description of this download.
StringCOLUMN_IDAn identifier for a particular download, unique across the system.
StringCOLUMN_LAST_MODIFIED_TIMESTAMPTimestamp when the download was last modified, in System.currentTimeMillis() (wall clock time in UTC).
StringCOLUMN_LOCAL_URIUri where downloaded file will be stored.
StringCOLUMN_MEDIAPROVIDER_URIThe URI to the corresponding entry in MediaProvider for this downloaded entry.
StringCOLUMN_MEDIA_TYPEInternet Media Type of the downloaded file.
StringCOLUMN_REASONProvides more detail on the status of the download.
StringCOLUMN_STATUSCurrent status of the download, as one of the STATUS_* constants.
StringCOLUMN_TITLEThe client-supplied title for this download.
StringCOLUMN_TOTAL_SIZE_BYTESTotal size of the download in bytes.
StringCOLUMN_URIURI to be downloaded.
intERROR_CANNOT_RESUMEValue of COLUMN_REASON when some possibly transient error occurred but we can't resume the download.
intERROR_DEVICE_NOT_FOUNDValue of COLUMN_REASON when no external storage device was found.
intERROR_FILE_ALREADY_EXISTSValue of COLUMN_REASON when the requested destination file already exists (the download manager will not overwrite an existing file).
intERROR_FILE_ERRORValue of COLUMN_REASON when a storage issue arises which doesn't fit under any other error code.
intERROR_HTTP_DATA_ERRORValue of COLUMN_REASON when an error receiving or processing data occurred at the HTTP level.
intERROR_INSUFFICIENT_SPACEValue of COLUMN_REASON when there was insufficient storage space.
intERROR_TOO_MANY_REDIRECTSValue of COLUMN_REASON when there were too many redirects.
intERROR_UNHANDLED_HTTP_CODEValue of COLUMN_REASON when an HTTP code was received that download manager can't handle.
intERROR_UNKNOWNValue of COLUMN_ERROR_CODE when the download has completed with an error that doesn't fit under any other error code.
StringEXTRA_DOWNLOAD_IDIntent extra included with ACTION_DOWNLOAD_COMPLETE intents, indicating the ID (as a long) of the download that just completed.
intPAUSED_QUEUED_FOR_WIFIValue of COLUMN_REASON when the download exceeds a size limit for downloads over the mobile network and the download manager is waiting for a Wi-Fi connection to proceed.
intPAUSED_UNKNOWNValue of COLUMN_REASON when the download is paused for some other reason.
intPAUSED_WAITING_FOR_NETWORKValue of COLUMN_REASON when the download is waiting for network connectivity to proceed.
intPAUSED_WAITING_TO_RETRYValue of COLUMN_REASON when the download is paused because some network error occurred and the download manager is waiting before retrying the request.
intSTATUS_FAILEDValue of COLUMN_STATUS when the download has failed (and will not be retried).
intSTATUS_PAUSEDValue of COLUMN_STATUS when the download is waiting to retry or resume.
intSTATUS_PENDINGValue of COLUMN_STATUS when the download is waiting to start.
intSTATUS_RUNNINGValue of COLUMN_STATUS when the download is currently running.
intSTATUS_SUCCESSFULValue of COLUMN_STATUS when the download has successfully completed.
Public Methods
long enqueue(DownloadManager.Request request)
Enqueue a new download.
ParcelFileDescriptor openDownloadedFile(long id)
Open a downloaded file for reading.
Cursor query(DownloadManager.Query query)
Query the download manager about downloads that have been requested.
int remove(long... ids)
Cancel downloads and remove them from the download manager.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String ACTION_DOWNLOAD_COMPLETE

Since: API Level 9

Broadcast intent action sent by the download manager when a download completes.

Constant Value: "android.intent.action.DOWNLOAD_COMPLETE"

public static final String ACTION_NOTIFICATION_CLICKED

Since: API Level 9

Broadcast intent action sent by the download manager when the user clicks on a running download, either from a system notification or from the downloads UI.

Constant Value: "android.intent.action.DOWNLOAD_NOTIFICATION_CLICKED"

public static final String ACTION_VIEW_DOWNLOADS

Since: API Level 9

Intent action to launch an activity to display all downloads.

Constant Value: "android.intent.action.VIEW_DOWNLOADS"

public static final String COLUMN_BYTES_DOWNLOADED_SO_FAR

Since: API Level 9

Number of bytes download so far.

Constant Value: "bytes_so_far"

public static final String COLUMN_DESCRIPTION

Since: API Level 9

The client-supplied description of this download. This will be displayed in system notifications. Defaults to the empty string.

Constant Value: "description"

public static final String COLUMN_ID

Since: API Level 9

An identifier for a particular download, unique across the system. Clients use this ID to make subsequent calls related to the download.

Constant Value: "_id"

public static final String COLUMN_LAST_MODIFIED_TIMESTAMP

Since: API Level 9

Timestamp when the download was last modified, in System.currentTimeMillis() (wall clock time in UTC).

Constant Value: "last_modified_timestamp"

public static final String COLUMN_LOCAL_URI

Since: API Level 9

Uri where downloaded file will be stored. If a destination is supplied by client, that URI will be used here. Otherwise, the value will initially be null and will be filled in with a generated URI once the download has started.

Constant Value: "local_uri"

public static final String COLUMN_MEDIAPROVIDER_URI

Since: API Level 9

The URI to the corresponding entry in MediaProvider for this downloaded entry. It is used to delete the entries from MediaProvider database when it is deleted from the downloaded list.

Constant Value: "mediaprovider_uri"

public static final String COLUMN_MEDIA_TYPE

Since: API Level 9

Internet Media Type of the downloaded file. If no value is provided upon creation, this will initially be null and will be filled in based on the server's response once the download has started.

Constant Value: "media_type"

public static final String COLUMN_REASON

Since: API Level 9

Provides more detail on the status of the download. Its meaning depends on the value of COLUMN_STATUS. When COLUMN_STATUS is STATUS_FAILED, this indicates the type of error that occurred. If an HTTP error occurred, this will hold the HTTP status code as defined in RFC 2616. Otherwise, it will hold one of the ERROR_* constants. When COLUMN_STATUS is STATUS_PAUSED, this indicates why the download is paused. It will hold one of the PAUSED_* constants. If COLUMN_STATUS is neither STATUS_FAILED nor STATUS_PAUSED, this column's value is undefined.

Constant Value: "reason"

public static final String COLUMN_STATUS

Since: API Level 9

Current status of the download, as one of the STATUS_* constants.

Constant Value: "status"

public static final String COLUMN_TITLE

Since: API Level 9

The client-supplied title for this download. This will be displayed in system notifications. Defaults to the empty string.

Constant Value: "title"

public static final String COLUMN_TOTAL_SIZE_BYTES

Since: API Level 9

Total size of the download in bytes. This will initially be -1 and will be filled in once the download starts.

Constant Value: "total_size"

public static final String COLUMN_URI

Since: API Level 9

URI to be downloaded.

Constant Value: "uri"

public static final int ERROR_CANNOT_RESUME

Since: API Level 9

Value of COLUMN_REASON when some possibly transient error occurred but we can't resume the download.

Constant Value: 1008 (0x000003f0)

public static final int ERROR_DEVICE_NOT_FOUND

Since: API Level 9

Value of COLUMN_REASON when no external storage device was found. Typically, this is because the SD card is not mounted.

Constant Value: 1007 (0x000003ef)

public static final int ERROR_FILE_ALREADY_EXISTS

Since: API Level 9

Value of COLUMN_REASON when the requested destination file already exists (the download manager will not overwrite an existing file).

Constant Value: 1009 (0x000003f1)

public static final int ERROR_FILE_ERROR

Since: API Level 9

Value of COLUMN_REASON when a storage issue arises which doesn't fit under any other error code. Use the more specific ERROR_INSUFFICIENT_SPACE and ERROR_DEVICE_NOT_FOUND when appropriate.

Constant Value: 1001 (0x000003e9)

public static final int ERROR_HTTP_DATA_ERROR

Since: API Level 9

Value of COLUMN_REASON when an error receiving or processing data occurred at the HTTP level.

Constant Value: 1004 (0x000003ec)

public static final int ERROR_INSUFFICIENT_SPACE

Since: API Level 9

Value of COLUMN_REASON when there was insufficient storage space. Typically, this is because the SD card is full.

Constant Value: 1006 (0x000003ee)

public static final int ERROR_TOO_MANY_REDIRECTS

Since: API Level 9

Value of COLUMN_REASON when there were too many redirects.

Constant Value: 1005 (0x000003ed)

public static final int ERROR_UNHANDLED_HTTP_CODE

Since: API Level 9

Value of COLUMN_REASON when an HTTP code was received that download manager can't handle.

Constant Value: 1002 (0x000003ea)

public static final int ERROR_UNKNOWN

Since: API Level 9

Value of COLUMN_ERROR_CODE when the download has completed with an error that doesn't fit under any other error code.

Constant Value: 1000 (0x000003e8)

public static final String EXTRA_DOWNLOAD_ID

Since: API Level 9

Intent extra included with ACTION_DOWNLOAD_COMPLETE intents, indicating the ID (as a long) of the download that just completed.

Constant Value: "extra_download_id"

public static final int PAUSED_QUEUED_FOR_WIFI

Since: API Level 9

Value of COLUMN_REASON when the download exceeds a size limit for downloads over the mobile network and the download manager is waiting for a Wi-Fi connection to proceed.

Constant Value: 3 (0x00000003)

public static final int PAUSED_UNKNOWN

Since: API Level 9

Value of COLUMN_REASON when the download is paused for some other reason.

Constant Value: 4 (0x00000004)

public static final int PAUSED_WAITING_FOR_NETWORK

Since: API Level 9

Value of COLUMN_REASON when the download is waiting for network connectivity to proceed.

Constant Value: 2 (0x00000002)

public static final int PAUSED_WAITING_TO_RETRY

Since: API Level 9

Value of COLUMN_REASON when the download is paused because some network error occurred and the download manager is waiting before retrying the request.

Constant Value: 1 (0x00000001)

public static final int STATUS_FAILED

Since: API Level 9

Value of COLUMN_STATUS when the download has failed (and will not be retried).

Constant Value: 16 (0x00000010)

public static final int STATUS_PAUSED

Since: API Level 9

Value of COLUMN_STATUS when the download is waiting to retry or resume.

Constant Value: 4 (0x00000004)

public static final int STATUS_PENDING

Since: API Level 9

Value of COLUMN_STATUS when the download is waiting to start.

Constant Value: 1 (0x00000001)

public static final int STATUS_RUNNING

Since: API Level 9

Value of COLUMN_STATUS when the download is currently running.

Constant Value: 2 (0x00000002)

public static final int STATUS_SUCCESSFUL

Since: API Level 9

Value of COLUMN_STATUS when the download has successfully completed.

Constant Value: 8 (0x00000008)

Public Methods

public long enqueue (DownloadManager.Request request)

Since: API Level 9

Enqueue a new download. The download will start automatically once the download manager is ready to execute it and connectivity is available.

Parameters
request the parameters specifying this download
Returns
  • an ID for the download, unique across the system. This ID is used to make future calls related to this download.

public ParcelFileDescriptor openDownloadedFile (long id)

Since: API Level 9

Open a downloaded file for reading. The download must have completed.

Parameters
id the ID of the download
Returns
Throws
FileNotFoundException if the destination file does not already exist

public Cursor query (DownloadManager.Query query)

Since: API Level 9

Query the download manager about downloads that have been requested.

Parameters
query parameters specifying filters for this query
Returns
  • a Cursor over the result set of downloads, with columns consisting of all the COLUMN_* constants.

public int remove (long... ids)

Since: API Level 9

Cancel downloads and remove them from the download manager. Each download will be stopped if it was running, and it will no longer be accessible through the download manager. If a file was already downloaded to external storage, it will not be deleted.

Parameters
ids the IDs of the downloads to remove
Returns
  • the number of downloads actually removed