DownloadManager详解

DownloadManager概述

DownloadManager是一种处理长时间运行的HTTP下载的系统服务。客户端可以请求将URI下载到特定目标文件。DownloadManager将在后台进行下载，负责HTTP交互并在发生故障或连接更改和系统重新启动后重试下载。

请求通过此API下载的应用程序应注册广播接收器即：DownloadManager.ACTION_NOTIFICATION_CLICKED以便在用户单击通知中的正在运行的下载或从下载UI中进行适当处理。

请注意，应用程序必须具有Manifest.permission.INTERNET 使用此类的权限。

如果使用存储SD卡需要写权限：Manifest.permission.WRITE_EXTERNAL_STORAGE.

获取DownloadManager实例：

1.Context.getSystemService(Class)参数：DownloadManager.class

2.Context.getSystemService(String)参数：Context.DOWNLOAD_SERVICE

方法介绍：

public long addCompletedDownload (

                                                            String title, 

                                                            String description, 

                                                            boolean isMediaScannerScannable, 

                                                            String mimeType, 

                                                            String path, 

                                                            long length,

                                                             boolean showNotification)；

将文件添加到下载数据库系统，因此它可以显示在下载应用程序中（因此可以通过下载应用程序进行管理）。

通过将参数 isMediaScannerScannable设置为true，使MediaScanner可以扫描文件是有帮助的。 它使文件在媒体管理应用程序（如Gallery App）中可见，这可能是使用此API的有用目的。

参数：

title：下载应用程序中将显示此文件的标题。

description：下载应用程序中将显示此文件的说明。

isMediaScannerScannable：如果要由MediaScanner扫描文件，则为true。 MediaScanner扫描的文件显示在用于查看媒体的应用程序中（例如，Gallery应用程序）。

mimeType：文件的mimetype

path：文件的绝对路径名。 该文件应该是全局可读的，因此可以通过下载应用程序和用于读取它的任何其他应用程序进行管理（例如，Gallery应用程序显示文件，如果文件内容代表视频/图像）。

length：下载文件的长度

showNotification：如果要发送通知，则为true，否则为false

结果返回：

添加到下载应用程序的下载条目的ID，在整个系统中是唯一的。此ID用于进行与此下载相关的未来调用。

public long addCompletedDownload (

                                                             String title, 

                                                              String description, 

                                                              boolean isMediaScannerScannable, 

                                                              String mimeType, 

                                                              String path, 

                                                              long length, 

                                                              boolean showNotification, 

                                                              Uri uri, 

                                                              Uri referer)；

将文件添加到下载数据库系统，因此它可以显示在下载应用程序中（因此可以通过下载应用程序进行管理）。
通过将参数isMediaScannerScannable设置为true，使MediaScanner可以扫描文件是有帮助的。 它使文件在媒体管理应用程序（如Gallery App）中可见，这可能是使用此API的有用目的。

参数：

title：下载应用程序中将显示此文件的标题。

description：下载应用程序中将显示此文件的说明。

isMediaScannerScannable：如果要由MediaScanner扫描文件，则为true。 MediaScanner扫描的文件显示在用于查看媒体的应用程序中（例如，Gallery应用程序）。

mimeType：文件的mimetype

path：文件的绝对路径名。 该文件应该是全局可读的，因此可以通过下载应用程序和用于读取它的任何其他应用程序进行管理（例如，Gallery应用程序显示文件，如果文件内容代表视频/图像）。

length：下载文件的长度

showNotification：如果要发送通知，则为true，否则为false

uri：下载的原始HTTP的URI

referer：用于下载的HTTP引用页

结果返回：

添加到下载应用程序的下载条目的ID，在整个系统中是唯一的。此ID用于进行与此下载相关的未来调用。

public long enqueue (DownloadManager.Request request)；

排队新的下载。 下载管理器准备好执行并且连接可用后，下载将自动启动。

参数：

request:指定此下载的参数

结果返回：

下载的ID，在整个系统中是唯一的。 此ID用于进行与此下载相关的未来调用。

public static Long getMaxBytesOverMobile (Context context)；

返回可能通过移动连接的下载的最大大小（以字节为单位）; 如果没有限制，则为null

public String getMimeTypeForDownloadedFile (long id)；

如果文件已成功下载，则返回给定下载文件ID的媒体类型。 否则，返回null。

参数：

id:下载文件的ID。

public static Long getRecommendedMaxBytesOverMobile (Context context);

返回可能通过移动连接的下载的建议最大大小（以字节为单位）; 如果没有建议的限制，则返回null。 用户可以选择绕过此限制。

public Uri getUriForDownloadedFile (long id);

如果文件下载成功，则返回给定下载文件ID的Uri。 否则，返回null。

参数：

id:下载文件的ID。

public ParcelFileDescriptor openDownloadedFile (long id);

打开下载的文件进行阅读。 下载必须已完成。

参数：

id:下载的ID

结果返回：

只读ParcelFileDescriptor

异常：

如果目标文件尚不存在将会抛出FileNotFoundException

public Cursor query (DownloadManager.Query query)；

向下载管理器查询已请求的下载。

参数：

query:参数指定此查询的过滤器

结果返回：

下载结果集上的游标，列包含所有COLUMN_ *常量。

DownloadManager.COLUMN_BYTES_DOWNLOADED_SO_FAR:到目前为止下载的字节数。

DownloadManager.COLUMN_DESCRIPTION:这个下载的客户端提供的描述

DownloadManager.COLUMN_ID:特定下载的标识符，在整个系统中是唯一的。

DownloadManager.COLUMN_LAST_MODIFIED_TIMESTAMP:上一次修改下载的时间戳，在system.currenttimemillis（）（UTC时间）。

DownloadManager.COLUMN_LOCAL_URI:将存储下载文件的Uri。

DownloadManager.COLUMN_MEDIAPROVIDER_URI:这个下载条目的MediaProvider对应条目的URI。

DownloadManager.COLUMN_MEDIA_TYPE:下载文件的网络媒体类型。

DownloadManager.COLUMN_REASON:提供有关下载状态的更多详细信息。

DownloadManager.COLUMN_STATUS:下载的当前状态，作为STATUS_ *常量之一。

DownloadManager.COLUMN_TITLE:这个下载的客户端提供的标题

DownloadManager.COLUMN_TOTAL_SIZE_BYTES:下载的总大小

DownloadManager.COLUMN_URI:URI下载

public int remove (long... ids)；

取消下载并从下载管理器中删除它们。 如果每次下载都在运行，则会停止下载，并且将无法再通过下载管理器访问该下载。 如果有下载的文件，部分或完整，则会将其删除。

参数：

ids:要删除的下载的ID

结果返回：实际删除的下载次数

DownloadManager.Request

此类包含请求新下载所需的所有信息。 

URI是惟一必需的参数。注意，默认的下载目的地是一个共享卷，如果系统需要回收空间供系统使用，它可能会删除您的文件。如果这是一个问题，请在外部存储上使用一个位置(参见setDestinationUri(Uri)))。

构造方法：

DownloadManager.Request(Uri uri);

要下载的HTTP或HTTPS的URI

方法介绍：

public DownloadManager.Request addRequestHeader (String header, String value)；

添加一个包含在下载请求中的HTTP头。头将被添加到列表的末尾。

参数说明：

header： HTTP 名称，value：对应的名称值。

详细参见:HTTP/1.1 Message Headers 地址：http://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2

public void allowScanningByMediaScanner ();

如果要下载的文件要被MediaScanner扫描，那么应该在调用DownloadManager.enqueue(Request)之前调用这个方法。

public DownloadManager.Request setAllowedNetworkTypes (int flags);

限制此下载可能进行的网络类型。

参数说明：

flags:DownloadManager.Request.NETWORK_MOBILE 移动网络 或者 DownloadManager.Request.NETWORK_WIFI 无线网络

默认情况下，所有网络类型都是允许的。考虑使用setAllowedOverMetered(boolean)，因为它更灵活。

自Build.VERSION_CODES.N（OS 7.0）起，这里只设置NETWORK_WIFI标志等同于用false调用setAllowedOverMetered(boolean)。

public DownloadManager.Request setAllowedOverMetered (boolean allow)；

设置此下载是否可以通过计量网络（移动流量）连接进行。默认情况下，计量网络是允许的。

参数说明：

allow: true表示可以使用移动网络，false不可以使用移动网络。

可见：ConnectivityManager.isActiveNetworkMetered() 

地址：https://developer.android.google.cn/reference/android/net/ConnectivityManager.html#isActiveNetworkMetered()

public DownloadManager.Request setAllowedOverRoaming (boolean allowed)；

设置此下载是否可以通过漫游连接进行。默认情况下，允许漫游。

参数说明：

allowed:true可以漫游。false：不可以漫游

public DownloadManager.Request setDescription (CharSequence description)；

设置此下载的描述，在通知中显示(如果启用)

public DownloadManager.Request setDestinationInExternalFilesDir (Context context, String dirType, String subPath)；

将下载文件的存储位置设置为应用程序外部文件目录中的路径(如Context.getExternalFilesDir(String)返回)

下载的文件不会被MediaScanner扫描。但是可以通过调用allowScanningByMediaScanner()来进行扫描。

参数：

context:用于确定外部文件目录的上下文 

dirType:要传递给Context.getExternalFilesDir(String)的目录类型

subPath:外部目录中的路径，包括目标文件名

异常：

如果无法找到或创建外部存储目录抛出IllegalStateException

public DownloadManager.Request setDestinationInExternalPublicDir (String dirType, String subPath)；

将下载的文件存储位置设置为公共外部存储目录中的路径（由Environment.getexternalstoragepublicdirectory（String）返回）。

MediaScanner不会扫描下载的文件。 但是可以通过调用allowScanningByMediaScanner（）使其可以扫描。

参数说明：

dirType:要传递给Environment.getExternalStoragePublicDirectory（String）的目录类型

subPath:外部目录中的路径，包括目标文件名

异常说明：

如果找不到或创建外部存储目录抛出IllegalStateException

public DownloadManager.Request setDestinationUri (Uri uri)；

设置下载文件的本地目标。 必须是外部存储上路径的文件URI，并且调用应用程序必须具有WRITE_EXTERNAL_STORAGE权限。

MediaScanner不会扫描下载的文件。 但是可以通过调用allowScanningByMediaScanner（）使其可以扫描。

默认情况下，下载将保存到共享下载缓存中生成的文件名中，系统可以随时删除以回收空间。

public DownloadManager.Request setMimeType (String mimeType)；

设置此下载的MIME内容类型。 这将覆盖服务器响应中声明的内容类型。

详细见：HTTP/1.1 Media Types 地址：http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.7

public DownloadManager.Request setNotificationVisibility (int visibility)；

控制下载管理器在下载运行或完成下载时是否发布系统通知。 如果启用，下载管理器将通过系统NotificationManager发布有关下载的通知。 默认情况下，仅在下载过程中显示通知。

DownloadManager.Request.VISIBILITY_HIDDEN:此下载不会显示在UI或通知中。

DownloadManager.Request.VISIBILITY_VISIBLE:此下载是可见的，但仅在通知中显示。

DownloadManager.Request.VISIBILITY_VISIBLE_NOTIFY_COMPLETED:此下载可见，并在进行中和完成后显示在通知中。

DownloadManager.Request.VISIBILITY_VISIBLE_NOTIFY_ONLY_COMPLETION:这个下载只显示在完成后的通知中。

如果设置为VISIBILITY_HIDDEN，则需要权限android.permission.DOWNLOAD_WITHOUT_NOTIFICATION

public DownloadManager.Request setRequiresCharging (boolean requiresCharging);

指定要运行此下载，需要插入设备。默认为false。

public DownloadManager.Request setRequiresDeviceIdle (boolean requiresDeviceIdle);

指定要运行，下载需要设备处于空闲模式。 默认为false。

空闲模式是系统提供的松散定义，这意味着设备未使用，并且一段时间未使用。

public DownloadManager.Request setTitle (CharSequence title);

设置此下载的标题，以显示在通知中（如果已启用）。 如果没有给出标题，则一旦下载开始，将根据下载文件名分配默认标题。

public DownloadManager.Request setVisibleInDownloadsUi (boolean isVisible);

设置是否应在系统的下载UI中显示此下载。 默认情况下为true。

DownloadManager.Query

此类可用于过滤下载管理器查询。

构造方法：

DownloadManager.Query()；

方法介绍：

public DownloadManager.Query setFilterById (long... ids)；

仅包含具有给定ID的下载。

public DownloadManager.Query setFilterByStatus (int flags)；

仅包含状态与任何给定状态标志匹配的下载

参数：STATUS_ *位标志的任意组合

DownloadManager.STATUS_FAILED:当下载失败时（并且不会重新尝试）。

DownloadManager.STATUS_PAUSED:当下载等待重试或恢复时。

DownloadManager.STATUS_PENDING:当下载等待开始的时候。

DownloadManager.STATUS_RUNNING:当下载当前正在运行时。

DownloadManager.STATUS_SUCCESSFUL:当下载成功完成时。