DownloadManager
open class DownloadManager
kotlin.Any | |
↳ | 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.
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.
Summary
Nested classes | |
---|---|
open |
This class may be used to filter download manager queries. |
open |
This class contains all the information necessary to request a new download. |
Constants | |
---|---|
static String |
Broadcast intent action sent by the download manager when a download completes. |
static String |
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 |
Intent action to launch an activity to display all downloads. |
static String |
Number of bytes download so far. |
static String |
The client-supplied description of this download. |
static String |
An identifier for a particular download, unique across the system. |
static String |
Timestamp when the download was last modified, in |
static String |
Path to the downloaded file on disk. |
static String |
Uri where downloaded file will be stored. |
static String |
The URI to the corresponding entry in MediaProvider for this downloaded entry. |
static String |
Internet Media Type of the downloaded file. |
static String |
Provides more detail on the status of the download. |
static String |
Current status of the download, as one of the STATUS_* constants. |
static String |
The client-supplied title for this download. |
static String |
Total size of the download in bytes. |
static String |
URI to be downloaded. |
static Int |
Value of |
static Int |
Value of |
static Int |
Value of |
static Int |
Value of |
static Int |
Value of |
static Int |
Value of |
static Int |
Value of |
static Int |
Value of |
static Int |
Value of COLUMN_ERROR_CODE when the download has completed with an error that doesn't fit under any other error code. |
static String |
Intent extra included with |
static String |
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 extra included with |
static Int |
Value of |
static Int |
Value of |
static Int |
Value of |
static Int |
Value of |
static Int |
Value of |
static Int |
Value of |
static Int |
Value of |
static Int |
Value of |
static Int |
Value of |
Public methods | |
---|---|
open Long |
addCompletedDownload(title: String!, description: String!, isMediaScannerScannable: Boolean, mimeType: String!, path: String!, length: Long, showNotification: Boolean) 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). |
open Long |
addCompletedDownload(title: String!, description: String!, isMediaScannerScannable: Boolean, mimeType: String!, path: String!, length: Long, showNotification: Boolean, uri: Uri!, referer: Uri!) 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). |
open Long |
enqueue(request: DownloadManager.Request!) Enqueue a new download. |
open 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 |
open String! |
Returns the media type of the given downloaded file id, if the file was downloaded successfully. |
open 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. |
open Uri! |
Returns the |
open ParcelFileDescriptor! |
openDownloadedFile(id: Long) Open a downloaded file for reading. |
open Cursor! |
query(query: DownloadManager.Query!) Query the download manager about downloads that have been requested. |
open Int |
Cancel downloads and remove them from the download manager. |
Constants
ACTION_DOWNLOAD_COMPLETE
static val ACTION_DOWNLOAD_COMPLETE: String
Broadcast intent action sent by the download manager when a download completes.
Value: "android.intent.action.DOWNLOAD_COMPLETE"
ACTION_NOTIFICATION_CLICKED
static val ACTION_NOTIFICATION_CLICKED: String
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.
Value: "android.intent.action.DOWNLOAD_NOTIFICATION_CLICKED"
ACTION_VIEW_DOWNLOADS
static val ACTION_VIEW_DOWNLOADS: String
Intent action to launch an activity to display all downloads.
Value: "android.intent.action.VIEW_DOWNLOADS"
COLUMN_BYTES_DOWNLOADED_SO_FAR
static val COLUMN_BYTES_DOWNLOADED_SO_FAR: String
Number of bytes download so far.
Value: "bytes_so_far"
COLUMN_DESCRIPTION
static val COLUMN_DESCRIPTION: String
The client-supplied description of this download. This will be displayed in system notifications. Defaults to the empty string.
Value: "description"
COLUMN_ID
static val COLUMN_ID: String
An identifier for a particular download, unique across the system. Clients use this ID to make subsequent calls related to the download.
Value: "_id"
COLUMN_LAST_MODIFIED_TIMESTAMP
static val COLUMN_LAST_MODIFIED_TIMESTAMP: String
Timestamp when the download was last modified, in System.currentTimeMillis()
(wall clock time in UTC).
Value: "last_modified_timestamp"
COLUMN_LOCAL_FILENAME
static valCOLUMN_LOCAL_FILENAME: String
Deprecated: apps should transition to using ContentResolver#openFileDescriptor(Uri, String)
instead.
Path to the downloaded file on disk.
Note that apps may not have filesystem permissions to directly access this path. Instead of trying to open this path directly, apps should use ContentResolver#openFileDescriptor(Uri, String)
to gain access.
Value: "local_filename"
COLUMN_LOCAL_URI
static val COLUMN_LOCAL_URI: String
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.
Value: "local_uri"
COLUMN_MEDIAPROVIDER_URI
static val COLUMN_MEDIAPROVIDER_URI: String
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.
Value: "mediaprovider_uri"
COLUMN_MEDIA_TYPE
static val COLUMN_MEDIA_TYPE: String
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.
Value: "media_type"
See Also
COLUMN_REASON
static val COLUMN_REASON: String
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.
Value: "reason"
See Also
COLUMN_STATUS
static val COLUMN_STATUS: String
Current status of the download, as one of the STATUS_* constants.
Value: "status"
COLUMN_TITLE
static val COLUMN_TITLE: String
The client-supplied title for this download. This will be displayed in system notifications. Defaults to the empty string.
Value: "title"
COLUMN_TOTAL_SIZE_BYTES
static val COLUMN_TOTAL_SIZE_BYTES: String
Total size of the download in bytes. This will initially be -1 and will be filled in once the download starts.
Value: "total_size"
ERROR_CANNOT_RESUME
static val ERROR_CANNOT_RESUME: Int
Value of COLUMN_REASON
when some possibly transient error occurred but we can't resume the download.
Value: 1008
ERROR_DEVICE_NOT_FOUND
static val ERROR_DEVICE_NOT_FOUND: Int
Value of COLUMN_REASON
when no external storage device was found. Typically, this is because the SD card is not mounted.
Value: 1007
ERROR_FILE_ALREADY_EXISTS
static val ERROR_FILE_ALREADY_EXISTS: Int
Value of COLUMN_REASON
when the requested destination file already exists (the download manager will not overwrite an existing file).
Value: 1009
ERROR_FILE_ERROR
static val ERROR_FILE_ERROR: Int
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: 1001
ERROR_HTTP_DATA_ERROR
static val ERROR_HTTP_DATA_ERROR: Int
Value of COLUMN_REASON
when an error receiving or processing data occurred at the HTTP level.
Value: 1004
ERROR_INSUFFICIENT_SPACE
static val ERROR_INSUFFICIENT_SPACE: Int
Value of COLUMN_REASON
when there was insufficient storage space. Typically, this is because the SD card is full.
Value: 1006
ERROR_TOO_MANY_REDIRECTS
static val ERROR_TOO_MANY_REDIRECTS: Int
Value of COLUMN_REASON
when there were too many redirects.
Value: 1005
ERROR_UNHANDLED_HTTP_CODE
static val ERROR_UNHANDLED_HTTP_CODE: Int
Value of COLUMN_REASON
when an HTTP code was received that download manager can't handle.
Value: 1002
ERROR_UNKNOWN
static val ERROR_UNKNOWN: Int
Value of COLUMN_ERROR_CODE when the download has completed with an error that doesn't fit under any other error code.
Value: 1000
EXTRA_DOWNLOAD_ID
static val EXTRA_DOWNLOAD_ID: String
Intent extra included with ACTION_DOWNLOAD_COMPLETE
intents, indicating the ID (as a long) of the download that just completed.
Value: "extra_download_id"
EXTRA_NOTIFICATION_CLICK_DOWNLOAD_IDS
static val EXTRA_NOTIFICATION_CLICK_DOWNLOAD_IDS: String
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 android.content.Intent#getLongArrayExtra(String)
.
Value: "extra_click_download_ids"
INTENT_EXTRAS_SORT_BY_SIZE
static val INTENT_EXTRAS_SORT_BY_SIZE: String
Intent extra included with ACTION_VIEW_DOWNLOADS
to start DownloadApp in sort-by-size mode.
Value: "android.app.DownloadManager.extra_sortBySize"
PAUSED_QUEUED_FOR_WIFI
static val PAUSED_QUEUED_FOR_WIFI: Int
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: 3
PAUSED_UNKNOWN
static val PAUSED_UNKNOWN: Int
Value of COLUMN_REASON
when the download is paused for some other reason.
Value: 4
PAUSED_WAITING_FOR_NETWORK
static val PAUSED_WAITING_FOR_NETWORK: Int
Value of COLUMN_REASON
when the download is waiting for network connectivity to proceed.
Value: 2
PAUSED_WAITING_TO_RETRY
static val PAUSED_WAITING_TO_RETRY: Int
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: 1
STATUS_FAILED
static val STATUS_FAILED: Int
Value of COLUMN_STATUS
when the download has failed (and will not be retried).
Value: 16
STATUS_PAUSED
static val STATUS_PAUSED: Int
Value of COLUMN_STATUS
when the download is waiting to retry or resume.
Value: 4
STATUS_PENDING
static val STATUS_PENDING: Int
Value of COLUMN_STATUS
when the download is waiting to start.
Value: 1
STATUS_RUNNING
static val STATUS_RUNNING: Int
Value of COLUMN_STATUS
when the download is currently running.
Value: 2
STATUS_SUCCESSFUL
static val STATUS_SUCCESSFUL: Int
Value of COLUMN_STATUS
when the download has successfully completed.
Value: 8
Public methods
addCompletedDownload
open funaddCompletedDownload(
title: String!,
description: String!,
isMediaScannerScannable: Boolean,
mimeType: String!,
path: String!,
length: Long,
showNotification: Boolean
): Long
Deprecated: Apps should instead contribute files to android.provider.MediaStore.Downloads
collection to make them available to user as part of Downloads.
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.
For applications targeting android.os.Build.VERSION_CODES#Q
or above, path
must be within directories owned by the application {e.g. Context#getExternalFilesDir(String)
} or if the application is running under the legacy storage model (see android:requestLegacyExternalStorage
), path
can also be within the top-level Downloads directory (as returned by Environment#getExternalStoragePublicDirectory(String)
with Environment#DIRECTORY_DOWNLOADS
).
Parameters | |
---|---|
title |
String!: the title that would appear for this file in Downloads App. |
description |
String!: the description that would appear for this file in Downloads App. |
isMediaScannerScannable |
Boolean: 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 |
String!: mimetype of the file. |
path |
String!: 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 |
Long: length of the downloaded file |
showNotification |
Boolean: true if a notification is to be sent, false otherwise |
Return | |
---|---|
Long |
an ID for the download entry added to the downloads app, unique across the system This ID is used to make future calls related to this download. |
addCompletedDownload
open funaddCompletedDownload(
title: String!,
description: String!,
isMediaScannerScannable: Boolean,
mimeType: String!,
path: String!,
length: Long,
showNotification: Boolean,
uri: Uri!,
referer: Uri!
): Long
Deprecated: Apps should instead contribute files to android.provider.MediaStore.Downloads
collection to make them available to user as part of Downloads.
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.
For applications targeting android.os.Build.VERSION_CODES#Q
or above, path
must be within directories owned by the application {e.g. Context#getExternalFilesDir(String)
} or if the application is running under the legacy storage model (see android:requestLegacyExternalStorage
), path
can also be within the top-level Downloads directory (as returned by Environment#getExternalStoragePublicDirectory(String)
with Environment#DIRECTORY_DOWNLOADS
).
Parameters | |
---|---|
title |
String!: the title that would appear for this file in Downloads App. |
description |
String!: the description that would appear for this file in Downloads App. |
isMediaScannerScannable |
Boolean: 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 |
String!: mimetype of the file. |
path |
String!: 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 |
Long: length of the downloaded file |
showNotification |
Boolean: true if a notification is to be sent, false otherwise |
uri |
Uri!: the original HTTP URI of the download |
referer |
Uri!: the HTTP Referer for the download |
Return | |
---|---|
Long |
an ID for the download entry added to the downloads app, unique across the system This ID is used to make future calls related to this download. |
enqueue
open fun enqueue(request: DownloadManager.Request!): Long
Enqueue a new download. The download will start automatically once the download manager is ready to execute it and connectivity is available.
Parameters | |
---|---|
request |
DownloadManager.Request!: the parameters specifying this download |
Return | |
---|---|
Long |
an ID for the download, unique across the system. This ID is used to make future calls related to this download. Returns -1 if the operation fails. |
getMaxBytesOverMobile
open static fun getMaxBytesOverMobile(context: Context!): Long!
Returns maximum size, in bytes, of downloads that may go over a mobile connection; or null if there's no limit
Parameters | |
---|---|
context |
Context!: the Context to use for accessing the ContentResolver |
Return | |
---|---|
Long! |
maximum size, in bytes, of downloads that may go over a mobile connection; or null if there's no limit |
getMimeTypeForDownloadedFile
open fun getMimeTypeForDownloadedFile(id: Long): String!
Returns the media type of the given downloaded file id, if the file was downloaded successfully. Otherwise, null is returned.
Parameters | |
---|---|
id |
Long: the id of the downloaded file. |
Return | |
---|---|
String! |
the media type of the given downloaded file id, if download was successful. null otherwise. |
getRecommendedMaxBytesOverMobile
open static fun getRecommendedMaxBytesOverMobile(context: Context!): Long!
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.
Parameters | |
---|---|
context |
Context!: the Context to use for accessing the ContentResolver |
Return | |
---|---|
Long! |
recommended maximum size, in bytes, of downloads that may go over a mobile connection; or null if there's no recommended limit. |
getUriForDownloadedFile
open fun getUriForDownloadedFile(id: Long): Uri!
Returns the Uri
of the given downloaded file id, if the file is downloaded successfully. Otherwise, null is returned.
Parameters | |
---|---|
id |
Long: the id of the downloaded file. |
Return | |
---|---|
Uri! |
the Uri of the given downloaded file id, if download was successful. null otherwise. |
openDownloadedFile
open fun openDownloadedFile(id: Long): ParcelFileDescriptor!
Open a downloaded file for reading. The download must have completed.
Parameters | |
---|---|
id |
Long: the ID of the download |
Return | |
---|---|
ParcelFileDescriptor! |
a read-only ParcelFileDescriptor |
Exceptions | |
---|---|
java.io.FileNotFoundException |
if the destination file does not already exist |
query
open fun query(query: DownloadManager.Query!): Cursor!
Query the download manager about downloads that have been requested.
Parameters | |
---|---|
query |
DownloadManager.Query!: parameters specifying filters for this query |
Return | |
---|---|
Cursor! |
a Cursor over the result set of downloads, with columns consisting of all the COLUMN_* constants. |
remove
open fun remove(vararg ids: Long): Int
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.
Parameters | |
---|---|
ids |
Long: the IDs of the downloads to remove |
Return | |
---|---|
Int |
the number of downloads actually removed |