public class DownloadManager extends Object
Context.getSystemService(String)
by passing
Context.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 android.Manifest.permission#INTERNET
permission to use this class.Modifier and Type | Class and Description |
---|---|
static class |
DownloadManager.Query
This class may be used to filter download manager queries.
|
static class |
DownloadManager.Request
This class contains all the information necessary to request a new download.
|
Modifier and Type | Field and Description |
---|---|
static String |
ACTION_DOWNLOAD_COMPLETE
Broadcast intent action sent by the download manager when a download completes.
|
static 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.
|
static String |
ACTION_VIEW_DOWNLOADS
Intent action to launch an activity to display all downloads.
|
static String |
COLUMN_BYTES_DOWNLOADED_SO_FAR
Number of bytes download so far.
|
static String |
COLUMN_DESCRIPTION
The client-supplied description of this download.
|
static String |
COLUMN_ID
An identifier for a particular download, unique across the system.
|
static String |
COLUMN_LAST_MODIFIED_TIMESTAMP
Timestamp when the download was last modified, in
System.currentTimeMillis() (wall clock time in UTC). |
static String |
COLUMN_LOCAL_FILENAME
The pathname of the file where the download is stored.
|
static String |
COLUMN_LOCAL_URI
Uri where downloaded file will be stored.
|
static String |
COLUMN_MEDIA_TYPE
Internet Media Type of the downloaded file.
|
static String |
COLUMN_MEDIAPROVIDER_URI
The URI to the corresponding entry in MediaProvider for this downloaded entry.
|
static String |
COLUMN_REASON
Provides more detail on the status of the download.
|
static String |
COLUMN_STATUS
Current status of the download, as one of the STATUS_* constants.
|
static String |
COLUMN_TITLE
The client-supplied title for this download.
|
static String |
COLUMN_TOTAL_SIZE_BYTES
Total size of the download in bytes.
|
static String |
COLUMN_URI
URI to be downloaded.
|
static int |
ERROR_BLOCKED
Value of
COLUMN_REASON when the download has failed because of
NetworkPolicyManager controls on the requesting application. |
static int |
ERROR_CANNOT_RESUME
Value of
COLUMN_REASON when some possibly transient error occurred but we can't
resume the download. |
static int |
ERROR_DEVICE_NOT_FOUND
Value of
COLUMN_REASON when no external storage device was found. |
static 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). |
static int |
ERROR_FILE_ERROR
Value of
COLUMN_REASON when a storage issue arises which doesn't fit under any
other error code. |
static int |
ERROR_HTTP_DATA_ERROR
Value of
COLUMN_REASON when an error receiving or processing data occurred at
the HTTP level. |
static int |
ERROR_INSUFFICIENT_SPACE
Value of
COLUMN_REASON when there was insufficient storage space. |
static int |
ERROR_TOO_MANY_REDIRECTS
Value of
COLUMN_REASON when there were too many redirects. |
static int |
ERROR_UNHANDLED_HTTP_CODE
Value of
COLUMN_REASON when an HTTP code was received that download manager
can't handle. |
static 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.
|
static String |
EXTRA_DOWNLOAD_ID
Intent extra included with
ACTION_DOWNLOAD_COMPLETE intents, indicating the ID (as a
long) of the download that just completed. |
static 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.
|
static String |
INTENT_EXTRAS_SORT_BY_SIZE
Intent extra included with
ACTION_VIEW_DOWNLOADS to start DownloadApp in
sort-by-size mode. |
static 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. |
static int |
PAUSED_UNKNOWN
Value of
COLUMN_REASON when the download is paused for some other reason. |
static int |
PAUSED_WAITING_FOR_NETWORK
Value of
COLUMN_REASON when the download is waiting for network connectivity to
proceed. |
static 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. |
static int |
STATUS_FAILED
Value of
COLUMN_STATUS when the download has failed (and will not be retried). |
static int |
STATUS_PAUSED
Value of
COLUMN_STATUS when the download is waiting to retry or resume. |
static int |
STATUS_PENDING
Value of
COLUMN_STATUS when the download is waiting to start. |
static int |
STATUS_RUNNING
Value of
COLUMN_STATUS when the download is currently running. |
static int |
STATUS_SUCCESSFUL
Value of
COLUMN_STATUS when the download has successfully completed. |
static String[] |
UNDERLYING_COLUMNS
columns to request from DownloadProvider.
|
Constructor and Description |
---|
DownloadManager(ContentResolver resolver,
String packageName) |
Modifier and Type | Method and Description |
---|---|
long |
addCompletedDownload(String title,
String description,
boolean isMediaScannerScannable,
String mimeType,
String path,
long length,
boolean showNotification)
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).
|
long |
enqueue(DownloadManager.Request request)
Enqueue a new download.
|
static long |
getActiveNetworkWarningBytes(Context context) |
static Long |
getMaxBytesOverMobile(Context context)
Returns maximum size, in bytes, of downloads that may go over a mobile connection; or null if
there's no limit
|
String |
getMimeTypeForDownloadedFile(long id)
Returns
Uri for the given downloaded file id, if the file is
downloaded successfully. |
static Long |
getRecommendedMaxBytesOverMobile(Context context)
Returns recommended maximum size, in bytes, of downloads that may go over a mobile
connection; or null if there's no recommended limit.
|
Uri |
getUriForDownloadedFile(long id)
Returns
Uri for the given downloaded file id, if the file is
downloaded successfully. |
static boolean |
isActiveNetworkExpensive(Context context) |
int |
markRowDeleted(long... ids)
Marks the specified download as 'to be deleted'.
|
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.
|
void |
restartDownload(long... ids)
Restart the given downloads, which must have already completed (successfully or not).
|
void |
setAccessAllDownloads(boolean accessAllDownloads)
Makes this object access the download provider through /all_downloads URIs rather than
/my_downloads URIs, for clients that have permission to do so.
|
public static final String COLUMN_ID
public static final String COLUMN_TITLE
public static final String COLUMN_DESCRIPTION
public static final String COLUMN_URI
public static final String COLUMN_MEDIA_TYPE
public static final String COLUMN_TOTAL_SIZE_BYTES
public static final String COLUMN_LOCAL_URI
public static final String COLUMN_LOCAL_FILENAME
public static final String COLUMN_STATUS
public static final String COLUMN_REASON
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.public static final String COLUMN_BYTES_DOWNLOADED_SO_FAR
public static final String COLUMN_LAST_MODIFIED_TIMESTAMP
System.currentTimeMillis()
(wall clock time in UTC).public static final String COLUMN_MEDIAPROVIDER_URI
public static final int STATUS_PENDING
COLUMN_STATUS
when the download is waiting to start.public static final int STATUS_RUNNING
COLUMN_STATUS
when the download is currently running.public static final int STATUS_PAUSED
COLUMN_STATUS
when the download is waiting to retry or resume.public static final int STATUS_SUCCESSFUL
COLUMN_STATUS
when the download has successfully completed.public static final int STATUS_FAILED
COLUMN_STATUS
when the download has failed (and will not be retried).public static final int ERROR_UNKNOWN
public static final int ERROR_FILE_ERROR
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.public static final int ERROR_UNHANDLED_HTTP_CODE
COLUMN_REASON
when an HTTP code was received that download manager
can't handle.public static final int ERROR_HTTP_DATA_ERROR
COLUMN_REASON
when an error receiving or processing data occurred at
the HTTP level.public static final int ERROR_TOO_MANY_REDIRECTS
COLUMN_REASON
when there were too many redirects.public static final int ERROR_INSUFFICIENT_SPACE
COLUMN_REASON
when there was insufficient storage space. Typically,
this is because the SD card is full.public static final int ERROR_DEVICE_NOT_FOUND
COLUMN_REASON
when no external storage device was found. Typically,
this is because the SD card is not mounted.public static final int ERROR_CANNOT_RESUME
COLUMN_REASON
when some possibly transient error occurred but we can't
resume the download.public static final int ERROR_FILE_ALREADY_EXISTS
COLUMN_REASON
when the requested destination file already exists (the
download manager will not overwrite an existing file).public static final int ERROR_BLOCKED
COLUMN_REASON
when the download has failed because of
NetworkPolicyManager
controls on the requesting application.public static final int PAUSED_WAITING_TO_RETRY
COLUMN_REASON
when the download is paused because some network error
occurred and the download manager is waiting before retrying the request.public static final int PAUSED_WAITING_FOR_NETWORK
COLUMN_REASON
when the download is waiting for network connectivity to
proceed.public static final int PAUSED_QUEUED_FOR_WIFI
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.public static final int PAUSED_UNKNOWN
COLUMN_REASON
when the download is paused for some other reason.public static final String ACTION_DOWNLOAD_COMPLETE
public static final String ACTION_NOTIFICATION_CLICKED
public static final String ACTION_VIEW_DOWNLOADS
public static final String INTENT_EXTRAS_SORT_BY_SIZE
ACTION_VIEW_DOWNLOADS
to start DownloadApp in
sort-by-size mode.public static final String EXTRA_DOWNLOAD_ID
ACTION_DOWNLOAD_COMPLETE
intents, indicating the ID (as a
long) of the download that just completed.public static final String EXTRA_NOTIFICATION_CLICK_DOWNLOAD_IDS
Intent.getLongArrayExtra(String)
.public static final String[] UNDERLYING_COLUMNS
public DownloadManager(ContentResolver resolver, String packageName)
public void setAccessAllDownloads(boolean accessAllDownloads)
public long enqueue(DownloadManager.Request request)
request
- the parameters specifying this downloadpublic int markRowDeleted(long... ids)
ids
- the IDs of the downloads to be marked 'deleted'public int remove(long... ids)
ids
- the IDs of the downloads to removepublic Cursor query(DownloadManager.Query query)
query
- parameters specifying filters for this querypublic ParcelFileDescriptor openDownloadedFile(long id) throws FileNotFoundException
id
- the ID of the downloadParcelFileDescriptor
FileNotFoundException
- if the destination file does not already existpublic Uri getUriForDownloadedFile(long id)
Uri
for 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
for the given downloaded file id, if download was successful. null
otherwise.public String getMimeTypeForDownloadedFile(long id)
Uri
for 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
for the given downloaded file id, if download was successful. null
otherwise.public void restartDownload(long... ids)
ids
- the IDs of the downloadspublic static Long getMaxBytesOverMobile(Context context)
context
- the Context
to use for accessing the ContentResolver
public static Long getRecommendedMaxBytesOverMobile(Context context)
context
- the Context
to use for accessing the ContentResolver
public static boolean isActiveNetworkExpensive(Context context)
public static long getActiveNetworkWarningBytes(Context context)
public long addCompletedDownload(String title, String description, boolean isMediaScannerScannable, String mimeType, String path, long length, boolean showNotification)
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 fileshowNotification
- true if a notification is to be sent, false otherwise