2010年12月19日日曜日

Android Android2.3 - DownloadManager を使う

DownloadManager は long-running HTTP ダウンロード用のシステムサービス

・ダウンロードするファイルのURIを指定してリクエストする

・ダウンロードはバックグラウンドで行われる

・接続が変わったり、リブートしたり、ダウンロードに失敗した場合は再試行される

・getSystemService(String) メソッドの引数に DOWNLOAD_SERVICE を渡してインスタンスを取得する

・このAPIを使ってダウンロードをリクエストするアプリは、ユーザーが notification や downloads UI からダウンロードを開始したことを適切にハンドルするために、ACTION_NOTIFICATION_CLICKED に対する broadcast receiver を登録しておかなければならない



# DownloadManager.Query に渡す URI が https だと怒られた。http じゃないとだめみたい。

# AndoridManifest.xml に <uses-permission android:name="android.permission.INTERNET"/> が必要なのですが、これを書かない時の logcat のエラーメッセージが requires android.permission.ACCESS_ALL_DOWNLOADS or android.permission.ACCESS_ALL_DOWNLOADS (エミュレータで、ですけど。)という(トンチンカン?な internal permission を表示してしまう)ものなので、ちょっと紛らわしいです。


保存先を明示しない場合は、cache にだけ保存されます。

$ adb -e shell
# ls cache
image1-3.png
image1-2.png
image1-1.png
image1.png
backup
lost+found



永続化する場合は、外部メディアのURIを指定します。


// save with uri
File file = new File(getExternalFilesDir(Environment.DIRECTORY_DOWNLOADS), "image1.png");
mRequest.setDestinationUri(Uri.fromFile(file));


# setDestinationUri() の引数に内部メディアのURIを入れると怒られます。。。


保存先を外部メディアの Application's Directory にした場合は /mnt/sdcard/ とかの下の Android/data/package-name/files/ の下の setDestinationInExternalPublicDir() の第1引数で指定したディレクトリの中になります。


mRequest.setDestinationInExternalFilesDir(this, Environment.DIRECTORY_DOWNLOADS, "image1.png");
File pathExternalDir = getExternalFilesDir(Environment.DIRECTORY_DOWNLOADS);
pathExternalDir.mkdirs();



$ adb -e shell
# ls mnt/sdcard/Android/data/yanzm.example.downloadmanagersample/files/Download
image1.png



保存先を外部メディアの Public Directory にした場合は /mnt/sdcard/ とかの下の setDestinationInExternalPublicDir() の第1引数で指定したディレクトリの中になります。


mRequest.setDestinationInExternalPublicDir(Environment.DIRECTORY_DOWNLOADS, "image1.png");
File pathExternalPublicDir = Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_DOWNLOADS);
pathExternalPublicDir.mkdirs();



$ adb -e shell
# ls mnt/sdcard/Download
image1.png



# mkdirs() でディレクトリ作っておかないとダウンロードに失敗するので気をつけて。。。


全ソースはこちら

package yanzm.example.downloadmanagersample;

import java.io.File;

import android.app.Activity;
import android.app.DownloadManager;
import android.content.Context;
import android.net.Uri;
import android.os.Bundle;
import android.os.Environment;
import android.util.Log;
import android.view.View;

public class MyActivity extends Activity {

private int downloadDestination = DESTINATION_EXTERNAL_PUBLICDIR;

private static final int CACHE = 0;
private static final int DESTINATION_URI = 1;
private static final int DESTINATION_EXTERNAL_DIR = 2;
private static final int DESTINATION_EXTERNAL_PUBLICDIR = 3;

@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
}

public void startDownload(View v) {
DownloadManager mDownloadManager = (DownloadManager) getSystemService(Context.DOWNLOAD_SERVICE);

Uri uri = Uri.parse("http://sites.google.com/site/yukianzm/tmp/image1.png");

DownloadManager.Request mRequest = new DownloadManager.Request(uri);
mRequest.setAllowedNetworkTypes(DownloadManager.Request.NETWORK_MOBILE);
// mRequest.setAllowedNetworkTypes(DownloadManager.Request.NETWORK_WIFI);
// mRequest.setAllowedOverRoaming(false);
mRequest.setTitle("Test Download!");
mRequest.setDescription("sample of using download manager");

switch (downloadDestination) {
case CACHE:
break;
case DESTINATION_URI:
// save with uri
File file = new File(getExternalFilesDir(Environment.DIRECTORY_DOWNLOADS), "image1.png");
mRequest.setDestinationUri(Uri.fromFile(file));
break;
case DESTINATION_EXTERNAL_DIR:
// save in external storage application's directory
mRequest.setDestinationInExternalFilesDir(this,Environment.DIRECTORY_DOWNLOADS, "image1.png");
File pathExternalDir = getExternalFilesDir(Environment.DIRECTORY_DOWNLOADS);
pathExternalDir.mkdirs();
break;
case DESTINATION_EXTERNAL_PUBLICDIR:
// save in external storage public directory
mRequest.setDestinationInExternalPublicDir(Environment.DIRECTORY_DOWNLOADS, "image1.png");
File pathExternalPublicDir = Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_DOWNLOADS);
pathExternalPublicDir.mkdirs();
break;
}

// mRequest.setMimeType(HTTP.OCTET_STREAM_TYPE);
mRequest.setShowRunningNotification(true);
mRequest.setVisibleInDownloadsUi(true);

long downloadId = mDownloadManager.enqueue(mRequest);

Log.d("DownloadManagerSample", "Start Download download Id = " + downloadId);
}
}



# broadcast receiver 部分についてはまた今度。。。

2.3 の Built-in Application の Downloads でみてみるとこんな感じ。






■ Nested Classes
 - DownloadManager.Query
    ダウンロードマネジャークエリーをフィルターするのに使う

 - DwonloadManager.Request
    新しいダウンロードのリクエストに必要な全ての情報を含む


■Constants
 - ACTION_DOWNLOAD_COMPLETE
    ダウンロードが完了したときに download manager によって
    発行される broadcast intent action

 - ACTION_NOTIFICATION_CLICKED
    ユーザーが system notification や downloads UI から
    実行中のダウンロードをクリックしたときに download manager
    から発行される broadcast intent action

 - ACTION_VIEW_DOWNLOADS
    全ダウンロードを表示するための Activity を起動する intent action

 - COLUMN_BYTES_DOWNLOADED_SO_FAR
    これまでのダウンロードバイト数

 - COLUMN_DESCRIPTION
    クライアントが提供するこのダウンロードの詳細

 - COLUMN_ID
    特定のダウンロードの識別子。システム上でユニーク

 - COLUMN_LAST_MODIFIED_TIMESTAMP
    最後にダウンロードが編集されたタイムスタンプ
     (System.currentTimeMillis() UTC)

 - COLUMN_LOCAL_URI
    ダウンロードされたファイルが保存される場所のUri

 - COLUMN_MEDIAPROVIDER_URI
    このダウンロードエントリに対応する MediaProvider でのエントリへのURI

 - COLUMN_MEDIA_TYPE
    このダウンロードファイルの Internet Media Type

 - COLUMN_REASON
    ダウンロードのステータスの詳細を提供する
    ERROR_* か PAUSED_* の定数の1つ

    - ERROR_CANNNOT_RESUME
       一時的なエラーでダウンロードを再開できない

    - ERROR_DEVICE_NOT_FOUND
       外部ストレージデバイスがみつからない

    - ERROR_FILE_ALREADY_EXISTS
       リクエスト先のファイルがすでに存在している
       (download manager はすでに存在している
       ファイルを上書きしない)

    - ERROR_FILE_ERROR
       他のエラーコードに合致しないストレージ問題が起こった

    - ERROR_HTTP_DATA_ERROR
       データを受信もしくは解析中にHTTPレベルでエラーが起こった

    - ERROR_INSUFFICIENT_SPACE
       十分なストレージ領域がない

    - ERROR_TOO_MANY_REDIRECTS
       リダイレクトが多すぎる

    - ERROR_UNHANDLED_HTTP_CODE
       download manager がハンドルできない HTTP code を受信した

    - ERROR_UNKNOWN
       他のエラーコードに合致しないエラーでダウンロードが完了した

    - PAUSED_QUEUED_FOR_WIFI
       ダウンロードが mobile network を介すときのリミットサイズ
       を超えたので、download manager は Wi-Fi 接続による再開を
       待っている

    - PAUSED_UNKNOWN
       ダウンロードは何かの理由で一時停止している

    - PAUSED_WAITING_FOR_NETWORK
       ダウンロードは再開のためにネットワーク接続を待っている

    - PAUSED_WAITING_TO_RETRY
       ネットワークエラーが発生し、download manager はリクエストを
       再試行する前に待っているので、ダウンロードが一時停止している

 - COLUMN_STATUS
    ダウンロードの現在の状態。STATUS_* 定数の1つ

    - STATUS_FAILED
       ダウンロードが失敗したときの値
       (再試行はされない)

    - STATUS_PAUSED
       ダウンロードが再試行か再開を待っているときの値

    - STATUS_PENDING
       ダウンロードが開始されるのを待っているときの値

    - STATUS_RUNNING
       ダウンロードが実行されているときの値

    - STATUS_SUCCESSFUL
       ダウンロードが成功し完了したときの値


 - COLUMN_TITLE
    クライアントが提供するこのダウンロードのタイトル

 - COLUMN_TOTAL_SIZE_BYTES
    ダウンロードのトータルバイト数

 - COLUMN_URI
    ダンロードする URI

 - EXTRA_DOWNLOAD_ID
    ACTION_DOWNLOAD_COMPLETE intents に含まれる
    intent extra
    今完了したダウンロードのID (long値)

■ Public Methods

 - long enqueue(DownloadManager.Request request)
    新しいダウンロードをキューに入れる

 - ParcelFileDescriptor openDonwloadedFile(long id)
    ダウンロードしたファイルを読むために開く

 - Cursor query(DownloadManager.Query query)
    リクエストされているダウンロードについてのクエリ

 - int remove(long... ids)
    ダウンロードをキャンセルし、download manager から削除する

3 件のコメント: