java.lang.Object | |
↳ | android.app.DownloadManager |
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.
Note that the application must have the INTERNET
permission to use this class.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
DownloadManager.Query | This class may be used to filter download manager queries. | ||||||||||
DownloadManager.Request | This class contains all the information necessary to request a new download. |
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
String | ACTION_DOWNLOAD_COMPLETE | Broadcast intent action sent by the download manager when a download completes. | |||||||||
String | ACTION_NOTIFICATION_CLICKED | 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. | |||||||||
String | ACTION_VIEW_DOWNLOADS | Intent action to launch an activity to display all downloads. | |||||||||
String | COLUMN_BYTES_DOWNLOADED_SO_FAR | Number of bytes download so far. | |||||||||
String | COLUMN_DESCRIPTION | The client-supplied description of this download. | |||||||||
String | COLUMN_ID | An identifier for a particular download, unique across the system. | |||||||||
String | COLUMN_LAST_MODIFIED_TIMESTAMP | Timestamp when the download was last modified, in System.currentTimeMillis() (wall clock time in UTC). |
|||||||||
String | COLUMN_LOCAL_FILENAME | The pathname of the file where the download is stored. | |||||||||
String | COLUMN_LOCAL_URI | Uri where downloaded file will be stored. | |||||||||
String | COLUMN_MEDIAPROVIDER_URI | The URI to the corresponding entry in MediaProvider for this downloaded entry. | |||||||||
String | COLUMN_MEDIA_TYPE | Internet Media Type of the downloaded file. | |||||||||
String | COLUMN_REASON | Provides more detail on the status of the download. | |||||||||
String | COLUMN_STATUS | Current status of the download, as one of the STATUS_* constants. | |||||||||
String | COLUMN_TITLE | The client-supplied title for this download. | |||||||||
String | COLUMN_TOTAL_SIZE_BYTES | Total size of the download in bytes. | |||||||||
String | COLUMN_URI | URI to be downloaded. | |||||||||
int | ERROR_CANNOT_RESUME | Value of COLUMN_REASON when some possibly transient error occurred but we can't
resume the download. |
|||||||||
int | ERROR_DEVICE_NOT_FOUND | Value of COLUMN_REASON when no external storage device was found. |
|||||||||
int | ERROR_FILE_ALREADY_EXISTS | Value of COLUMN_REASON when the requested destination file already exists (the
download manager will not overwrite an existing file). |
|||||||||
int | ERROR_FILE_ERROR | Value of COLUMN_REASON when a storage issue arises which doesn't fit under any
other error code. |
|||||||||
int | ERROR_HTTP_DATA_ERROR | Value of COLUMN_REASON when an error receiving or processing data occurred at
the HTTP level. |
|||||||||
int | ERROR_INSUFFICIENT_SPACE | Value of COLUMN_REASON when there was insufficient storage space. |
|||||||||
int | ERROR_TOO_MANY_REDIRECTS | Value of COLUMN_REASON when there were too many redirects. |
|||||||||
int | ERROR_UNHANDLED_HTTP_CODE | Value of COLUMN_REASON when an HTTP code was received that download manager
can't handle. |
|||||||||
int | ERROR_UNKNOWN | Value of COLUMN_ERROR_CODE when the download has completed with an error that doesn't fit under any other error code. | |||||||||
String | EXTRA_DOWNLOAD_ID | Intent extra included with ACTION_DOWNLOAD_COMPLETE intents, indicating the ID (as a
long) of the download that just completed. |
|||||||||
String | EXTRA_NOTIFICATION_CLICK_DOWNLOAD_IDS | When clicks on multiple notifications are received, the following provides an array of download ids corresponding to the download notification that was clicked. | |||||||||
String | INTENT_EXTRAS_SORT_BY_SIZE | Intent extra included with ACTION_VIEW_DOWNLOADS to start DownloadApp in
sort-by-size mode. |
|||||||||
int | PAUSED_QUEUED_FOR_WIFI | 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. |
|||||||||
int | PAUSED_UNKNOWN | Value of COLUMN_REASON when the download is paused for some other reason. |
|||||||||
int | PAUSED_WAITING_FOR_NETWORK | Value of COLUMN_REASON when the download is waiting for network connectivity to
proceed. |
|||||||||
int | PAUSED_WAITING_TO_RETRY | Value of COLUMN_REASON when the download is paused because some network error
occurred and the download manager is waiting before retrying the request. |
|||||||||
int | STATUS_FAILED | Value of COLUMN_STATUS when the download has failed (and will not be retried). |
|||||||||
int | STATUS_PAUSED | Value of COLUMN_STATUS when the download is waiting to retry or resume. |
|||||||||
int | STATUS_PENDING | Value of COLUMN_STATUS when the download is waiting to start. |
|||||||||
int | STATUS_RUNNING | Value of COLUMN_STATUS when the download is currently running. |
|||||||||
int | STATUS_SUCCESSFUL | Value of COLUMN_STATUS when the download has successfully completed. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Adds a file to the downloads database system, so it could appear in Downloads App
(and thus become eligible for management by the Downloads App).
| |||||||||||
Enqueue a new download.
| |||||||||||
Returns maximum size, in bytes, of downloads that may go over a mobile connection; or null if
there's no limit
| |||||||||||
Returns the media type of the given downloaded file id, if the file was
downloaded successfully.
| |||||||||||
Returns recommended maximum size, in bytes, of downloads that may go over a mobile
connection; or null if there's no recommended limit.
| |||||||||||
Returns the
Uri of the given downloaded file id, if the file is
downloaded successfully. | |||||||||||
Open a downloaded file for reading.
| |||||||||||
Query the download manager about downloads that have been requested.
| |||||||||||
Cancel downloads and remove them from the download manager.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
Broadcast intent action sent by the download manager when a download completes.
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.
Intent action to launch an activity to display all downloads.
Number of bytes download so far.
The client-supplied description of this download. This will be displayed in system notifications. Defaults to the empty string.
An identifier for a particular download, unique across the system. Clients use this ID to make subsequent calls related to the download.
Timestamp when the download was last modified, in System.currentTimeMillis()
(wall clock time in UTC).
The pathname of the file where the download is stored.
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.
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.
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.
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.
Current status of the download, as one of the STATUS_* constants.
The client-supplied title for this download. This will be displayed in system notifications. Defaults to the empty string.
Total size of the download in bytes. This will initially be -1 and will be filled in once the download starts.
URI to be downloaded.
Value of COLUMN_REASON
when some possibly transient error occurred but we can't
resume the download.
Value of COLUMN_REASON
when no external storage device was found. Typically,
this is because the SD card is not mounted.
Value of COLUMN_REASON
when the requested destination file already exists (the
download manager will not overwrite an existing file).
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.
Value of COLUMN_REASON
when an error receiving or processing data occurred at
the HTTP level.
Value of COLUMN_REASON
when there was insufficient storage space. Typically,
this is because the SD card is full.
Value of COLUMN_REASON
when there were too many redirects.
Value of COLUMN_REASON
when an HTTP code was received that download manager
can't handle.
Value of COLUMN_ERROR_CODE when the download has completed with an error that doesn't fit under any other error code.
Intent extra included with ACTION_DOWNLOAD_COMPLETE
intents, indicating the ID (as a
long) of the download that just completed.
When clicks on multiple notifications are received, the following
provides an array of download ids corresponding to the download notification that was
clicked. It can be retrieved by the receiver of this
Intent using getLongArrayExtra(String)
.
Intent extra included with ACTION_VIEW_DOWNLOADS
to start DownloadApp in
sort-by-size mode.
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.
Value of COLUMN_REASON
when the download is paused for some other reason.
Value of COLUMN_REASON
when the download is waiting for network connectivity to
proceed.
Value of COLUMN_REASON
when the download is paused because some network error
occurred and the download manager is waiting before retrying the request.
Value of COLUMN_STATUS
when the download has failed (and will not be retried).
Value of COLUMN_STATUS
when the download is waiting to retry or resume.
Value of COLUMN_STATUS
when the download is waiting to start.
Value of COLUMN_STATUS
when the download is currently running.
Value of COLUMN_STATUS
when the download has successfully completed.
Adds a file to the downloads database system, so it could appear in Downloads App (and thus become eligible for management by the Downloads App).
It is helpful to make the file scannable by MediaScanner by setting the param isMediaScannerScannable to true. It makes the file visible in media managing applications such as Gallery App, which could be a useful purpose of using this API.
title | the title that would appear for this file in Downloads App. |
---|---|
description | the description that would appear for this file in Downloads App. |
isMediaScannerScannable | true if the file is to be scanned by MediaScanner. Files scanned by MediaScanner appear in the applications used to view media (for example, Gallery app). |
mimeType | mimetype of the file. |
path | absolute pathname to the file. The file should be world-readable, so that it can be managed by the Downloads App and any other app that is used to read it (for example, Gallery app to display the file, if the file contents represent a video/image). |
length | length of the downloaded file |
showNotification | true if a notification is to be sent, false otherwise |
Enqueue a new download. The download will start automatically once the download manager is ready to execute it and connectivity is available.
request | the parameters specifying this download |
---|
Returns maximum size, in bytes, of downloads that may go over a mobile connection; or null if there's no limit
context | the Context to use for accessing the ContentResolver |
---|
Returns the media type of the given downloaded file id, if the file was downloaded successfully. Otherwise, null is returned.
id | the id of the downloaded file. |
---|
Returns recommended maximum size, in bytes, of downloads that may go over a mobile connection; or null if there's no recommended limit. The user will have the option to bypass this limit.
context | the Context to use for accessing the ContentResolver |
---|
Returns the Uri
of the given downloaded file id, if the file is
downloaded successfully. Otherwise, null is returned.
If the specified downloaded file is in external storage (for example, /sdcard dir),
then it is assumed to be safe for anyone to read and the returned Uri
corresponds
to the filepath on sdcard.
id | the id of the downloaded file. |
---|
Uri
of the given downloaded file id, if download was successful. null
otherwise.
Open a downloaded file for reading. The download must have completed.
id | the ID of the download |
---|
ParcelFileDescriptor
FileNotFoundException | if the destination file does not already exist |
---|
Query the download manager about downloads that have been requested.
query | parameters specifying filters for this query |
---|
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 there is a downloaded file, partial or complete, it is deleted.
ids | the IDs of the downloads to remove |
---|