Android 使用 DownloadManager 管理系统下载任务的方法

在红黑联盟上看到的。这几天一直考虑做一个Notification 的带下载功能的自己定义通知。但没搞出来。无意中在论坛看到这个。先Mark，明天试试。

从Android 2.3（API level 9）開始Android用系统服务(Service)的方式提供了Download Manager来优化处理长时间的下载操作。

Download Manager处理HTTP连接并监控连接中的状态变化以及系统重新启动来确保每个下载任务顺利完毕。

在大多数涉及到下载的情况中使用Download Manager都是不错的选择，特别是当用户切换不同的应用以后下载须要在后台继续进行，以及当下载任务顺利完毕非常重要的情况（DownloadManager对于断点续传功能支持非常好）。

要想使用Download Manager。使用getSystemService方法请求系统的DOWNLOAD_SERVICE服务，代码片段例如以下：

String serviceString =Context.DOWNLOAD_SERVICE; 

DownloadManager downloadManager; 

downloadManager = (DownloadManager)getSystemService(serviceString);

下载文件

要请求一个下载操作。须要创建一个DownloadManager.Request对象，将要请求下载的文件的Uri传递给DownloadManager的enqueue方法，代码片段例如以下所看到的：

String serviceString =Context.DOWNLOAD_SERVICE; 

DownloadManager downloadManager; 

downloadManager =(DownloadManager)getSystemService(serviceString); 

  

Uri uri =Uri.parse("http://developer.android.com/shareables/icon_templates-v4.0.zip"); 

DownloadManager.Request request = newRequest(uri); 

long reference =downloadManager.enqueue(request);

在这里返回的reference变量是系统为当前的下载请求分配的一个唯一的ID。我们能够通过这个ID又一次获得这个下载任务，进行一些自己想要进行的操作或者查询下载的状态以及取消下载等等。

我们能够通过addRequestHeader方法为DownloadManager.Request对象request加入HTTP头，也能够通过setMimeType方法重写从server返回的mimetype。

我们还能够指定在什么连接状态下运行下载操作。setAllowedNetworkTypes方法能够用来限定在WiFi还是手机网络下进行下载。setAllowedOverRoaming方法能够用来阻止手机在漫游状态下下载。

以下的代码片段用于指定一个较大的文件仅仅能在WiFi下进行下载：

request.setAllowedNetworkTypes(Request.NETWORK_WIFI);

Android API
level 11 介绍了getRecommendedMaxBytesOverMobile类方法（静态方法）。返回一个当前手机网络连接下的最大建议字节数，能够来推断下载是否应该限定在WiFi条件下。调用enqueue方法之后，仅仅要数据连接可用而且Download Manager可用。下载就会開始。要在下载完毕的时候获得一个系统通知（notification）,注冊一个广播接受者来接收ACTION_DOWNLOAD_COMPLETE广播。这个广播会包括一个EXTRA_DOWNLOAD_ID信息在intent中包括了已经完毕的这个下载的ID,代码片段例如以下所看到的：

IntentFilter filter = newIntentFilter(DownloadManager.ACTION_DOWNLOAD_COMPLETE); 

      

BroadcastReceiver receiver = newBroadcastReceiver() { 

 @Override

 public void onReceive(Context context, Intent intent) { 

   long reference = intent.getLongExtra(DownloadManager.EXTRA_DOWNLOAD_ID,-1); 

   if (myDownloadReference == reference) { 

       

   } 

 } 

}; 

registerReceiver(receiver, filter);

使用Download Manager的openDownloadedFile方法能够打开一个已经下载完毕的文件。返回一个ParcelFileDescriptor对象。我们能够通过Download Manager来查询下载文件的保存地址。假设在下载时制定了路径和文件名称，我们也能够直接操作文件。

我们能够为ACTION_NOTIFICATION_CLICKED
action注冊一个广播接受者，当用户从通知栏点击了一个下载项目或者从Downloads app点击可一个下载的项目的时候，系统就会发出一个点击下载项的广播。

代码片段例如以下：

IntentFilter filter = newIntentFilter(DownloadManager.ACTION_NOTIFICATION_CLICKED); 

  

BroadcastReceiver receiver = newBroadcastReceiver() { 

 @Override

 public void onReceive(Context context, Intent intent) { 

   String extraID =DownloadManager.EXTRA_NOTIFICATION_CLICK_DOWNLOAD_IDS; 

   long[] references = intent.getLongArrayExtra(extraID); 

   for (long reference : references) 

     if (reference == myDownloadReference) { 

       // Do something with downloading file. 

     } 

 } 

};  

registerReceiver(receiver, filter);

定制Download Manager Notifications的样式

默认情况下，通知栏中会显示被Download Manager管理的每个download每个Notification会显示当前的下载进度和文件的名字

通过Download Manager能够为每个download request定制Notification的样式。包含全然隐藏Notification。以下的代码片段显示了通过setTitle和setDescription方法来定制显示在文件下载Notification中显示的文字。

request.setTitle(“Earthquakes”); 

request.setDescription(“EarthquakeXML”);

setNotificationVisibility方法能够用来控制什么时候显示Notification，甚至是隐藏该request的Notification。有下面几个參数：

Request.VISIBILITY_VISIBLE：在下载进行的过程中。通知栏中会一直显示该下载的Notification，当下载完毕时，该Notification会被移除。这是默认的參数值。

Request.VISIBILITY_VISIBLE_NOTIFY_COMPLETED：在下载过程中通知栏会一直显示该下载的Notification。在下载完毕后该Notification会继续显示。直到用户点击该Notification或者消除该Notification。

Request.VISIBILITY_VISIBLE_NOTIFY_ONLY_COMPLETION：仅仅有在下载完毕后该Notification才会被显示。

Request.VISIBILITY_HIDDEN：不显示该下载请求的Notification。假设要使用这个參数，须要在应用的清单文件里加上DOWNLOAD_WITHOUT_NOTIFICATION权限。

指定下载保存地址

默认情况下，全部通过Download Manager下载的文件都保存在一个共享下载缓存中，使用系统生成的文件名称每个Request对象都能够制定一个下载

保存的地址，通常情况下。全部的下载文件都应该保存在外部存储中，所以我们须要在应用清单文件里加上WRITE_EXTERNAL_STORAGE权限：

<uses-permissionandroid:name=”android.permission.write_external_storage”>

以下的代码片段是在外部存储中指定一个随意的保存位置的方法：

request.setDestinationUri(Uri.fromFile(f));

f是一个File对象。

假设下载的这个文件是你的应用所专用的。你可能会希望把这个文件放在你的应用在外部存储中的一个专有目录中。注意这个目录不提供訪问控制。所以其它的应用也能够訪问这个目录。在这样的情况下，假设你的应用卸载了。那么在这个目录也会被删除。

以下的代码片段是指定存储文件的路径是应用在外部存储中的专用目录的方法：

request.setDestinationInExternalFilesDir(this, 

 Environment.DIRECTORY_DOWNLOADS, “Bugdroid.png”);

假设下载的文件希望被其它的应用共享。特别是那些你下载下来希望被Media Scanner扫描到的文件（比方音乐文件），那么你能够指定你的下载路径在外部存储的公共目录之下，以下的代码片段是将文件存放到外部存储中的公共音乐目录的方法：

request.setDestinationInExternalPublicDir(Environment.DIRECTORY_MUSIC, 

 "Android_Rock.mp3");

在默认的情况下。通过Download Manager下载的文件是不能被Media Scanner扫描到的，进而这些下载的文件（音乐、视频等）就不会在Gallery和

Music Player这种应用中看到。

为了让下载的音乐文件能够被其它应用扫描到，我们须要调用Request对象的allowScaningByMediaScanner方法。

假设我们希望下载的文件能够被系统的Downloads应用扫描到并管理，我们须要调用Request对象的setVisibleInDownloadsUi方法，传递參数true。

取消和删除下载

Download Manager的remove方法能够用来取消一个准备进行的下载，中止一个正在进行的下载，或者删除一个已经完毕的下载。

remove方法接受若干个download 的ID作为參数，你能够设置一个或者几个你想要取消的下载的ID，例如以下代码段所看到的：

downloadManager.remove(REFERENCE_1,REFERENCE_2, REFERENCE_3);

该方法返回成功取消的下载的个数，假设一个下载被取消了，全部相关联的文件，部分下载的文件和全然下载的文件都会被删除。

查询Download Manager

你能够通过查询Download Manager来获得下载任务的状态。进度，以及各种细节，通过query方法返回一个包括了下载任务细节的Cursor。query方法传递一个DownloadManager.Query对象作为參数。通过DownloadManager.Query对象的setFilterById方法能够筛选我们希望查询的下载任务的ID。也能够使用setFilterByStatus方法筛选我们希望查询的某一种状态的下载任务，传递的參数是DownloadManager.STATUS_*常量。能够指定

正在进行、暂停、失败、完毕四种状态。

Download Manager包括了一系列COLUMN_*静态String常量。能够用来查询Cursor中的结果列索引。我们能够查询到下载任务的各种细节，包括状态。文件大小。已经下载的字节数。标题，描写叙述，URI。本地文件名称和URI，媒体类型以及Media Provider download URI。

以下的代码段是通过注冊监听下载完毕事件的广播接受者来查询下载完毕文件的本地文件名称和URI的实现方法：

public void onReceive(Context context,Intent intent) { 

 long reference = intent.getLongExtra(DownloadManager.EXTRA_DOWNLOAD_ID,-1); 

  if(myDownloadReference == reference) { 

       

   Query myDownloadQuery = new Query(); 

   myDownloadQuery.setFilterById(reference); 

        

   Cursor myDownload = downloadManager.query(myDownloadQuery); 

   if (myDownload.moveToFirst()) { 

     int fileNameIdx =  

       myDownload.getColumnIndex(DownloadManager.COLUMN_LOCAL_FILENAME); 

     int fileUriIdx =  

       myDownload.getColumnIndex(DownloadManager.COLUMN_LOCAL_URI); 

  

     String fileName = myDownload.getString(fileNameIdx); 

     String fileUri = myDownload.getString(fileUriIdx); 

      

     // TODO Do something with the file. 

     Log.d(TAG, fileName + " : " + fileUri); 

   } 

   myDownload.close(); 

  

 } 

}

对于暂停和失败的下载，我们能够通过查询COLUMN_REASON列查询出原因的整数码。

对于STATUS_PAUSED状态的下载，能够通过DownloadManager.PAUSED_*静态常量来翻译出原因的整数码，进而推断出下载是因为等待网络连接

还是等待WiFi连接还是准备又一次下载三种原因而暂停。

对于STATUS_FAILED状态的下载。我们能够通过DownloadManager.ERROR_*来推断失败的原因。可能是错误码（失败原因）包含没有存储设备。

存储空间不足，反复的文件名称，或者HTTP errors。

以下的代码是怎样查询出当前全部的暂停的下载任务。提取出暂停的原因以及文件名。下载标题以及当前进度的实现方法：

// Obtain the Download ManagerService.
String serviceString =Context.DOWNLOAD_SERVICE;
DownloadManager downloadManager;
downloadManager =(DownloadManager)getSystemService(serviceString); 

// Create a query for pauseddownloads.
Query pausedDownloadQuery = newQuery();
pausedDownloadQuery.setFilterByStatus(DownloadManager.STATUS_PAUSED); 

// Query the Download Manager for pauseddownloads.
Cursor pausedDownloads =downloadManager.query(pausedDownloadQuery); 

// Find the column indexes for the data werequire.
int reasonIdx =pausedDownloads.getColumnIndex(DownloadManager.COLUMN_REASON);
int titleIdx =pausedDownloads.getColumnIndex(DownloadManager.COLUMN_TITLE);
int fileSizeIdx =
 pausedDownloads.getColumnIndex(DownloadManager.COLUMN_TOTAL_SIZE_BYTES);
int bytesDLIdx =
 pausedDownloads.getColumnIndex(DownloadManager.COLUMN_BYTES_DOWNLOADED_SO_FAR); 

// Iterate over the result Cursor.
while (pausedDownloads.moveToNext()) {
  //Extract the data we require from the Cursor.
 String title = pausedDownloads.getString(titleIdx);
  intfileSize = pausedDownloads.getInt(fileSizeIdx);
  intbytesDL = pausedDownloads.getInt(bytesDLIdx); 

  //Translate the pause reason to friendly text.
  intreason = pausedDownloads.getInt(reasonIdx);
 String reasonString = "Unknown";
 switch (reason) {
   case DownloadManager.PAUSED_QUEUED_FOR_WIFI :
     reasonString = "Waiting for WiFi"; break;
   case DownloadManager.PAUSED_WAITING_FOR_NETWORK :
     reasonString = "Waiting for connectivity"; break;
   case DownloadManager.PAUSED_WAITING_TO_RETRY :
     reasonString = "Waiting to retry"; break;
   default : break;
 } 

  //Construct a status summary
 StringBuilder sb = new StringBuilder();
 sb.append(title).append("\n");
 sb.append(reasonString).append("\n");
 sb.append("Downloaded ").append(bytesDL).append(" /" ).append(fileSize); 

  //Display the status
 Log.d("DOWNLOAD", sb.toString());
} 

// Close the result Cursor.
pausedDownloads.close();