2 * Copyright (C) 2010 The Android Open Source Project
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
19 import android.annotation.Nullable;
20 import android.annotation.SdkConstant;
21 import android.annotation.SdkConstant.SdkConstantType;
22 import android.annotation.SystemApi;
23 import android.annotation.SystemService;
24 import android.content.ContentResolver;
25 import android.content.ContentUris;
26 import android.content.ContentValues;
27 import android.content.Context;
28 import android.content.Intent;
29 import android.database.Cursor;
30 import android.database.CursorWrapper;
31 import android.net.ConnectivityManager;
32 import android.net.NetworkPolicyManager;
33 import android.net.Uri;
34 import android.os.Build;
35 import android.os.Environment;
36 import android.os.FileUtils;
37 import android.os.ParcelFileDescriptor;
38 import android.provider.Downloads;
39 import android.provider.MediaStore.Images;
40 import android.provider.Settings;
41 import android.provider.Settings.SettingNotFoundException;
42 import android.text.TextUtils;
43 import android.util.Pair;
46 import java.io.FileNotFoundException;
47 import java.util.ArrayList;
48 import java.util.List;
51 * The download manager is a system service that handles long-running HTTP downloads. Clients may
52 * request that a URI be downloaded to a particular destination file. The download manager will
53 * conduct the download in the background, taking care of HTTP interactions and retrying downloads
54 * after failures or across connectivity changes and system reboots.
56 * Apps that request downloads through this API should register a broadcast receiver for
57 * {@link #ACTION_NOTIFICATION_CLICKED} to appropriately handle when the user clicks on a running
58 * download in a notification or from the downloads UI.
60 * Note that the application must have the {@link android.Manifest.permission#INTERNET}
61 * permission to use this class.
63 @SystemService(Context.DOWNLOAD_SERVICE)
64 public class DownloadManager {
67 * An identifier for a particular download, unique across the system. Clients use this ID to
68 * make subsequent calls related to the download.
70 public final static String COLUMN_ID = Downloads.Impl._ID;
73 * The client-supplied title for this download. This will be displayed in system notifications.
74 * Defaults to the empty string.
76 public final static String COLUMN_TITLE = Downloads.Impl.COLUMN_TITLE;
79 * The client-supplied description of this download. This will be displayed in system
80 * notifications. Defaults to the empty string.
82 public final static String COLUMN_DESCRIPTION = Downloads.Impl.COLUMN_DESCRIPTION;
85 * URI to be downloaded.
87 public final static String COLUMN_URI = Downloads.Impl.COLUMN_URI;
90 * Internet Media Type of the downloaded file. If no value is provided upon creation, this will
91 * initially be null and will be filled in based on the server's response once the download has
94 * @see <a href="http://www.ietf.org/rfc/rfc1590.txt">RFC 1590, defining Media Types</a>
96 public final static String COLUMN_MEDIA_TYPE = "media_type";
99 * Total size of the download in bytes. This will initially be -1 and will be filled in once
100 * the download starts.
102 public final static String COLUMN_TOTAL_SIZE_BYTES = "total_size";
105 * Uri where downloaded file will be stored. If a destination is supplied by client, that URI
106 * will be used here. Otherwise, the value will initially be null and will be filled in with a
107 * generated URI once the download has started.
109 public final static String COLUMN_LOCAL_URI = "local_uri";
112 * Path to the downloaded file on disk.
114 * Note that apps may not have filesystem permissions to directly access
115 * this path. Instead of trying to open this path directly, apps should use
116 * {@link ContentResolver#openFileDescriptor(Uri, String)} to gain access.
118 * @deprecated apps should transition to using
119 * {@link ContentResolver#openFileDescriptor(Uri, String)}
123 public final static String COLUMN_LOCAL_FILENAME = "local_filename";
126 * Current status of the download, as one of the STATUS_* constants.
128 public final static String COLUMN_STATUS = Downloads.Impl.COLUMN_STATUS;
131 * Provides more detail on the status of the download. Its meaning depends on the value of
132 * {@link #COLUMN_STATUS}.
134 * When {@link #COLUMN_STATUS} is {@link #STATUS_FAILED}, this indicates the type of error that
135 * occurred. If an HTTP error occurred, this will hold the HTTP status code as defined in RFC
136 * 2616. Otherwise, it will hold one of the ERROR_* constants.
138 * When {@link #COLUMN_STATUS} is {@link #STATUS_PAUSED}, this indicates why the download is
139 * paused. It will hold one of the PAUSED_* constants.
141 * If {@link #COLUMN_STATUS} is neither {@link #STATUS_FAILED} nor {@link #STATUS_PAUSED}, this
142 * column's value is undefined.
144 * @see <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html#sec6.1.1">RFC 2616
147 public final static String COLUMN_REASON = "reason";
150 * Number of bytes download so far.
152 public final static String COLUMN_BYTES_DOWNLOADED_SO_FAR = "bytes_so_far";
155 * Timestamp when the download was last modified, in {@link System#currentTimeMillis
156 * System.currentTimeMillis()} (wall clock time in UTC).
158 public final static String COLUMN_LAST_MODIFIED_TIMESTAMP = "last_modified_timestamp";
161 * The URI to the corresponding entry in MediaProvider for this downloaded entry. It is
162 * used to delete the entries from MediaProvider database when it is deleted from the
165 public static final String COLUMN_MEDIAPROVIDER_URI = Downloads.Impl.COLUMN_MEDIAPROVIDER_URI;
170 public final static String COLUMN_ALLOW_WRITE = Downloads.Impl.COLUMN_ALLOW_WRITE;
173 * Value of {@link #COLUMN_STATUS} when the download is waiting to start.
175 public final static int STATUS_PENDING = 1 << 0;
178 * Value of {@link #COLUMN_STATUS} when the download is currently running.
180 public final static int STATUS_RUNNING = 1 << 1;
183 * Value of {@link #COLUMN_STATUS} when the download is waiting to retry or resume.
185 public final static int STATUS_PAUSED = 1 << 2;
188 * Value of {@link #COLUMN_STATUS} when the download has successfully completed.
190 public final static int STATUS_SUCCESSFUL = 1 << 3;
193 * Value of {@link #COLUMN_STATUS} when the download has failed (and will not be retried).
195 public final static int STATUS_FAILED = 1 << 4;
198 * Value of COLUMN_ERROR_CODE when the download has completed with an error that doesn't fit
199 * under any other error code.
201 public final static int ERROR_UNKNOWN = 1000;
204 * Value of {@link #COLUMN_REASON} when a storage issue arises which doesn't fit under any
205 * other error code. Use the more specific {@link #ERROR_INSUFFICIENT_SPACE} and
206 * {@link #ERROR_DEVICE_NOT_FOUND} when appropriate.
208 public final static int ERROR_FILE_ERROR = 1001;
211 * Value of {@link #COLUMN_REASON} when an HTTP code was received that download manager
214 public final static int ERROR_UNHANDLED_HTTP_CODE = 1002;
217 * Value of {@link #COLUMN_REASON} when an error receiving or processing data occurred at
220 public final static int ERROR_HTTP_DATA_ERROR = 1004;
223 * Value of {@link #COLUMN_REASON} when there were too many redirects.
225 public final static int ERROR_TOO_MANY_REDIRECTS = 1005;
228 * Value of {@link #COLUMN_REASON} when there was insufficient storage space. Typically,
229 * this is because the SD card is full.
231 public final static int ERROR_INSUFFICIENT_SPACE = 1006;
234 * Value of {@link #COLUMN_REASON} when no external storage device was found. Typically,
235 * this is because the SD card is not mounted.
237 public final static int ERROR_DEVICE_NOT_FOUND = 1007;
240 * Value of {@link #COLUMN_REASON} when some possibly transient error occurred but we can't
241 * resume the download.
243 public final static int ERROR_CANNOT_RESUME = 1008;
246 * Value of {@link #COLUMN_REASON} when the requested destination file already exists (the
247 * download manager will not overwrite an existing file).
249 public final static int ERROR_FILE_ALREADY_EXISTS = 1009;
252 * Value of {@link #COLUMN_REASON} when the download has failed because of
253 * {@link NetworkPolicyManager} controls on the requesting application.
257 public final static int ERROR_BLOCKED = 1010;
260 * Value of {@link #COLUMN_REASON} when the download is paused because some network error
261 * occurred and the download manager is waiting before retrying the request.
263 public final static int PAUSED_WAITING_TO_RETRY = 1;
266 * Value of {@link #COLUMN_REASON} when the download is waiting for network connectivity to
269 public final static int PAUSED_WAITING_FOR_NETWORK = 2;
272 * Value of {@link #COLUMN_REASON} when the download exceeds a size limit for downloads over
273 * the mobile network and the download manager is waiting for a Wi-Fi connection to proceed.
275 public final static int PAUSED_QUEUED_FOR_WIFI = 3;
278 * Value of {@link #COLUMN_REASON} when the download is paused for some other reason.
280 public final static int PAUSED_UNKNOWN = 4;
283 * Broadcast intent action sent by the download manager when a download completes.
285 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
286 public final static String ACTION_DOWNLOAD_COMPLETE = "android.intent.action.DOWNLOAD_COMPLETE";
289 * Broadcast intent action sent by the download manager when the user clicks on a running
290 * download, either from a system notification or from the downloads UI.
292 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
293 public final static String ACTION_NOTIFICATION_CLICKED =
294 "android.intent.action.DOWNLOAD_NOTIFICATION_CLICKED";
297 * Intent action to launch an activity to display all downloads.
299 @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
300 public final static String ACTION_VIEW_DOWNLOADS = "android.intent.action.VIEW_DOWNLOADS";
303 * Intent extra included with {@link #ACTION_VIEW_DOWNLOADS} to start DownloadApp in
306 public final static String INTENT_EXTRAS_SORT_BY_SIZE =
307 "android.app.DownloadManager.extra_sortBySize";
310 * Intent extra included with {@link #ACTION_DOWNLOAD_COMPLETE} intents, indicating the ID (as a
311 * long) of the download that just completed.
313 public static final String EXTRA_DOWNLOAD_ID = "extra_download_id";
316 * When clicks on multiple notifications are received, the following
317 * provides an array of download ids corresponding to the download notification that was
318 * clicked. It can be retrieved by the receiver of this
319 * Intent using {@link android.content.Intent#getLongArrayExtra(String)}.
321 public static final String EXTRA_NOTIFICATION_CLICK_DOWNLOAD_IDS = "extra_click_download_ids";
325 public static final String ACTION_DOWNLOAD_COMPLETED =
326 "android.intent.action.DOWNLOAD_COMPLETED";
329 * columns to request from DownloadProvider.
332 public static final String[] UNDERLYING_COLUMNS = new String[] {
334 Downloads.Impl._DATA + " AS " + COLUMN_LOCAL_FILENAME,
335 Downloads.Impl.COLUMN_MEDIAPROVIDER_URI,
336 Downloads.Impl.COLUMN_DESTINATION,
337 Downloads.Impl.COLUMN_TITLE,
338 Downloads.Impl.COLUMN_DESCRIPTION,
339 Downloads.Impl.COLUMN_URI,
340 Downloads.Impl.COLUMN_STATUS,
341 Downloads.Impl.COLUMN_FILE_NAME_HINT,
342 Downloads.Impl.COLUMN_MIME_TYPE + " AS " + COLUMN_MEDIA_TYPE,
343 Downloads.Impl.COLUMN_TOTAL_BYTES + " AS " + COLUMN_TOTAL_SIZE_BYTES,
344 Downloads.Impl.COLUMN_LAST_MODIFICATION + " AS " + COLUMN_LAST_MODIFIED_TIMESTAMP,
345 Downloads.Impl.COLUMN_CURRENT_BYTES + " AS " + COLUMN_BYTES_DOWNLOADED_SO_FAR,
346 Downloads.Impl.COLUMN_ALLOW_WRITE,
347 /* add the following 'computed' columns to the cursor.
348 * they are not 'returned' by the database, but their inclusion
349 * eliminates need to have lot of methods in CursorTranslator
351 "'placeholder' AS " + COLUMN_LOCAL_URI,
352 "'placeholder' AS " + COLUMN_REASON
356 * This class contains all the information necessary to request a new download. The URI is the
357 * only required parameter.
359 * Note that the default download destination is a shared volume where the system might delete
360 * your file if it needs to reclaim space for system use. If this is a problem, use a location
361 * on external storage (see {@link #setDestinationUri(Uri)}.
363 public static class Request {
365 * Bit flag for {@link #setAllowedNetworkTypes} corresponding to
366 * {@link ConnectivityManager#TYPE_MOBILE}.
368 public static final int NETWORK_MOBILE = 1 << 0;
371 * Bit flag for {@link #setAllowedNetworkTypes} corresponding to
372 * {@link ConnectivityManager#TYPE_WIFI}.
374 public static final int NETWORK_WIFI = 1 << 1;
377 * Bit flag for {@link #setAllowedNetworkTypes} corresponding to
378 * {@link ConnectivityManager#TYPE_BLUETOOTH}.
382 public static final int NETWORK_BLUETOOTH = 1 << 2;
385 private Uri mDestinationUri;
386 private List<Pair<String, String>> mRequestHeaders = new ArrayList<Pair<String, String>>();
387 private CharSequence mTitle;
388 private CharSequence mDescription;
389 private String mMimeType;
390 private int mAllowedNetworkTypes = ~0; // default to all network types allowed
391 private boolean mRoamingAllowed = true;
392 private boolean mMeteredAllowed = true;
393 private int mFlags = 0;
394 private boolean mIsVisibleInDownloadsUi = true;
395 private boolean mScannable = false;
396 /** if a file is designated as a MediaScanner scannable file, the following value is
397 * stored in the database column {@link Downloads.Impl#COLUMN_MEDIA_SCANNED}.
399 private static final int SCANNABLE_VALUE_YES = 0;
400 // value of 1 is stored in the above column by DownloadProvider after it is scanned by
402 /** if a file is designated as a file that should not be scanned by MediaScanner,
403 * the following value is stored in the database column
404 * {@link Downloads.Impl#COLUMN_MEDIA_SCANNED}.
406 private static final int SCANNABLE_VALUE_NO = 2;
409 * This download is visible but only shows in the notifications
410 * while it's in progress.
412 public static final int VISIBILITY_VISIBLE = 0;
415 * This download is visible and shows in the notifications while
416 * in progress and after completion.
418 public static final int VISIBILITY_VISIBLE_NOTIFY_COMPLETED = 1;
421 * This download doesn't show in the UI or in the notifications.
423 public static final int VISIBILITY_HIDDEN = 2;
426 * This download shows in the notifications after completion ONLY.
427 * It is usuable only with
428 * {@link DownloadManager#addCompletedDownload(String, String,
429 * boolean, String, String, long, boolean)}.
431 public static final int VISIBILITY_VISIBLE_NOTIFY_ONLY_COMPLETION = 3;
433 /** can take any of the following values: {@link #VISIBILITY_HIDDEN}
434 * {@link #VISIBILITY_VISIBLE_NOTIFY_COMPLETED}, {@link #VISIBILITY_VISIBLE},
435 * {@link #VISIBILITY_VISIBLE_NOTIFY_ONLY_COMPLETION}
437 private int mNotificationVisibility = VISIBILITY_VISIBLE;
440 * @param uri the HTTP or HTTPS URI to download.
442 public Request(Uri uri) {
444 throw new NullPointerException();
446 String scheme = uri.getScheme();
447 if (scheme == null || (!scheme.equals("http") && !scheme.equals("https"))) {
448 throw new IllegalArgumentException("Can only download HTTP/HTTPS URIs: " + uri);
453 Request(String uriString) {
454 mUri = Uri.parse(uriString);
458 * Set the local destination for the downloaded file. Must be a file URI to a path on
459 * external storage, and the calling application must have the WRITE_EXTERNAL_STORAGE
462 * The downloaded file is not scanned by MediaScanner.
463 * But it can be made scannable by calling {@link #allowScanningByMediaScanner()}.
465 * By default, downloads are saved to a generated filename in the shared download cache and
466 * may be deleted by the system at any time to reclaim space.
468 * @return this object
470 public Request setDestinationUri(Uri uri) {
471 mDestinationUri = uri;
476 * Set the local destination for the downloaded file to a path within
477 * the application's external files directory (as returned by
478 * {@link Context#getExternalFilesDir(String)}.
480 * The downloaded file is not scanned by MediaScanner. But it can be
481 * made scannable by calling {@link #allowScanningByMediaScanner()}.
483 * @param context the {@link Context} to use in determining the external
485 * @param dirType the directory type to pass to
486 * {@link Context#getExternalFilesDir(String)}
487 * @param subPath the path within the external directory, including the
488 * destination filename
489 * @return this object
490 * @throws IllegalStateException If the external storage directory
491 * cannot be found or created.
493 public Request setDestinationInExternalFilesDir(Context context, String dirType,
495 final File file = context.getExternalFilesDir(dirType);
497 throw new IllegalStateException("Failed to get external storage files directory");
498 } else if (file.exists()) {
499 if (!file.isDirectory()) {
500 throw new IllegalStateException(file.getAbsolutePath() +
501 " already exists and is not a directory");
504 if (!file.mkdirs()) {
505 throw new IllegalStateException("Unable to create directory: "+
506 file.getAbsolutePath());
509 setDestinationFromBase(file, subPath);
514 * Set the local destination for the downloaded file to a path within
515 * the public external storage directory (as returned by
516 * {@link Environment#getExternalStoragePublicDirectory(String)}).
518 * The downloaded file is not scanned by MediaScanner. But it can be
519 * made scannable by calling {@link #allowScanningByMediaScanner()}.
521 * @param dirType the directory type to pass to {@link Environment#getExternalStoragePublicDirectory(String)}
522 * @param subPath the path within the external directory, including the
523 * destination filename
524 * @return this object
525 * @throws IllegalStateException If the external storage directory
526 * cannot be found or created.
528 public Request setDestinationInExternalPublicDir(String dirType, String subPath) {
529 File file = Environment.getExternalStoragePublicDirectory(dirType);
531 throw new IllegalStateException("Failed to get external storage public directory");
532 } else if (file.exists()) {
533 if (!file.isDirectory()) {
534 throw new IllegalStateException(file.getAbsolutePath() +
535 " already exists and is not a directory");
538 if (!file.mkdirs()) {
539 throw new IllegalStateException("Unable to create directory: "+
540 file.getAbsolutePath());
543 setDestinationFromBase(file, subPath);
547 private void setDestinationFromBase(File base, String subPath) {
548 if (subPath == null) {
549 throw new NullPointerException("subPath cannot be null");
551 mDestinationUri = Uri.withAppendedPath(Uri.fromFile(base), subPath);
555 * If the file to be downloaded is to be scanned by MediaScanner, this method
556 * should be called before {@link DownloadManager#enqueue(Request)} is called.
558 public void allowScanningByMediaScanner() {
563 * Add an HTTP header to be included with the download request. The header will be added to
564 * the end of the list.
565 * @param header HTTP header name
566 * @param value header value
567 * @return this object
568 * @see <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2">HTTP/1.1
569 * Message Headers</a>
571 public Request addRequestHeader(String header, String value) {
572 if (header == null) {
573 throw new NullPointerException("header cannot be null");
575 if (header.contains(":")) {
576 throw new IllegalArgumentException("header may not contain ':'");
581 mRequestHeaders.add(Pair.create(header, value));
586 * Set the title of this download, to be displayed in notifications (if enabled). If no
587 * title is given, a default one will be assigned based on the download filename, once the
589 * @return this object
591 public Request setTitle(CharSequence title) {
597 * Set a description of this download, to be displayed in notifications (if enabled)
598 * @return this object
600 public Request setDescription(CharSequence description) {
601 mDescription = description;
606 * Set the MIME content type of this download. This will override the content type declared
607 * in the server's response.
608 * @see <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.7">HTTP/1.1
610 * @return this object
612 public Request setMimeType(String mimeType) {
613 mMimeType = mimeType;
618 * Control whether a system notification is posted by the download manager while this
619 * download is running. If enabled, the download manager posts notifications about downloads
620 * through the system {@link android.app.NotificationManager}. By default, a notification is
623 * If set to false, this requires the permission
624 * android.permission.DOWNLOAD_WITHOUT_NOTIFICATION.
626 * @param show whether the download manager should show a notification for this download.
627 * @return this object
628 * @deprecated use {@link #setNotificationVisibility(int)}
631 public Request setShowRunningNotification(boolean show) {
632 return (show) ? setNotificationVisibility(VISIBILITY_VISIBLE) :
633 setNotificationVisibility(VISIBILITY_HIDDEN);
637 * Control whether a system notification is posted by the download manager while this
638 * download is running or when it is completed.
639 * If enabled, the download manager posts notifications about downloads
640 * through the system {@link android.app.NotificationManager}.
641 * By default, a notification is shown only when the download is in progress.
643 * It can take the following values: {@link #VISIBILITY_HIDDEN},
644 * {@link #VISIBILITY_VISIBLE},
645 * {@link #VISIBILITY_VISIBLE_NOTIFY_COMPLETED}.
647 * If set to {@link #VISIBILITY_HIDDEN}, this requires the permission
648 * android.permission.DOWNLOAD_WITHOUT_NOTIFICATION.
650 * @param visibility the visibility setting value
651 * @return this object
653 public Request setNotificationVisibility(int visibility) {
654 mNotificationVisibility = visibility;
659 * Restrict the types of networks over which this download may proceed.
660 * By default, all network types are allowed. Consider using
661 * {@link #setAllowedOverMetered(boolean)} instead, since it's more
664 * As of {@link android.os.Build.VERSION_CODES#N}, setting only the
665 * {@link #NETWORK_WIFI} flag here is equivalent to calling
666 * {@link #setAllowedOverMetered(boolean)} with {@code false}.
668 * @param flags any combination of the NETWORK_* bit flags.
669 * @return this object
671 public Request setAllowedNetworkTypes(int flags) {
672 mAllowedNetworkTypes = flags;
677 * Set whether this download may proceed over a roaming connection. By default, roaming is
679 * @param allowed whether to allow a roaming connection to be used
680 * @return this object
682 public Request setAllowedOverRoaming(boolean allowed) {
683 mRoamingAllowed = allowed;
688 * Set whether this download may proceed over a metered network
689 * connection. By default, metered networks are allowed.
691 * @see ConnectivityManager#isActiveNetworkMetered()
693 public Request setAllowedOverMetered(boolean allow) {
694 mMeteredAllowed = allow;
699 * Specify that to run this download, the device needs to be plugged in.
700 * This defaults to false.
702 * @param requiresCharging Whether or not the device is plugged in.
703 * @see android.app.job.JobInfo.Builder#setRequiresCharging(boolean)
705 public Request setRequiresCharging(boolean requiresCharging) {
706 if (requiresCharging) {
707 mFlags |= Downloads.Impl.FLAG_REQUIRES_CHARGING;
709 mFlags &= ~Downloads.Impl.FLAG_REQUIRES_CHARGING;
715 * Specify that to run, the download needs the device to be in idle
716 * mode. This defaults to false.
718 * Idle mode is a loose definition provided by the system, which means
719 * that the device is not in use, and has not been in use for some time.
721 * @param requiresDeviceIdle Whether or not the device need be within an
722 * idle maintenance window.
723 * @see android.app.job.JobInfo.Builder#setRequiresDeviceIdle(boolean)
725 public Request setRequiresDeviceIdle(boolean requiresDeviceIdle) {
726 if (requiresDeviceIdle) {
727 mFlags |= Downloads.Impl.FLAG_REQUIRES_DEVICE_IDLE;
729 mFlags &= ~Downloads.Impl.FLAG_REQUIRES_DEVICE_IDLE;
735 * Set whether this download should be displayed in the system's Downloads UI. True by
737 * @param isVisible whether to display this download in the Downloads UI
738 * @return this object
740 public Request setVisibleInDownloadsUi(boolean isVisible) {
741 mIsVisibleInDownloadsUi = isVisible;
746 * @return ContentValues to be passed to DownloadProvider.insert()
748 ContentValues toContentValues(String packageName) {
749 ContentValues values = new ContentValues();
751 values.put(Downloads.Impl.COLUMN_URI, mUri.toString());
752 values.put(Downloads.Impl.COLUMN_IS_PUBLIC_API, true);
753 values.put(Downloads.Impl.COLUMN_NOTIFICATION_PACKAGE, packageName);
755 if (mDestinationUri != null) {
756 values.put(Downloads.Impl.COLUMN_DESTINATION,
757 Downloads.Impl.DESTINATION_FILE_URI);
758 values.put(Downloads.Impl.COLUMN_FILE_NAME_HINT,
759 mDestinationUri.toString());
761 values.put(Downloads.Impl.COLUMN_DESTINATION,
762 Downloads.Impl.DESTINATION_CACHE_PARTITION_PURGEABLE);
764 // is the file supposed to be media-scannable?
765 values.put(Downloads.Impl.COLUMN_MEDIA_SCANNED, (mScannable) ? SCANNABLE_VALUE_YES :
768 if (!mRequestHeaders.isEmpty()) {
769 encodeHttpHeaders(values);
772 putIfNonNull(values, Downloads.Impl.COLUMN_TITLE, mTitle);
773 putIfNonNull(values, Downloads.Impl.COLUMN_DESCRIPTION, mDescription);
774 putIfNonNull(values, Downloads.Impl.COLUMN_MIME_TYPE, mMimeType);
776 values.put(Downloads.Impl.COLUMN_VISIBILITY, mNotificationVisibility);
777 values.put(Downloads.Impl.COLUMN_ALLOWED_NETWORK_TYPES, mAllowedNetworkTypes);
778 values.put(Downloads.Impl.COLUMN_ALLOW_ROAMING, mRoamingAllowed);
779 values.put(Downloads.Impl.COLUMN_ALLOW_METERED, mMeteredAllowed);
780 values.put(Downloads.Impl.COLUMN_FLAGS, mFlags);
781 values.put(Downloads.Impl.COLUMN_IS_VISIBLE_IN_DOWNLOADS_UI, mIsVisibleInDownloadsUi);
786 private void encodeHttpHeaders(ContentValues values) {
788 for (Pair<String, String> header : mRequestHeaders) {
789 String headerString = header.first + ": " + header.second;
790 values.put(Downloads.Impl.RequestHeaders.INSERT_KEY_PREFIX + index, headerString);
795 private void putIfNonNull(ContentValues contentValues, String key, Object value) {
797 contentValues.put(key, value.toString());
803 * This class may be used to filter download manager queries.
805 public static class Query {
807 * Constant for use with {@link #orderBy}
810 public static final int ORDER_ASCENDING = 1;
813 * Constant for use with {@link #orderBy}
816 public static final int ORDER_DESCENDING = 2;
818 private long[] mIds = null;
819 private Integer mStatusFlags = null;
820 private String mFilterString = null;
821 private String mOrderByColumn = Downloads.Impl.COLUMN_LAST_MODIFICATION;
822 private int mOrderDirection = ORDER_DESCENDING;
823 private boolean mOnlyIncludeVisibleInDownloadsUi = false;
826 * Include only the downloads with the given IDs.
827 * @return this object
829 public Query setFilterById(long... ids) {
836 * Include only the downloads that contains the given string in its name.
837 * @return this object
840 public Query setFilterByString(@Nullable String filter) {
841 mFilterString = filter;
846 * Include only downloads with status matching any the given status flags.
847 * @param flags any combination of the STATUS_* bit flags
848 * @return this object
850 public Query setFilterByStatus(int flags) {
851 mStatusFlags = flags;
856 * Controls whether this query includes downloads not visible in the system's Downloads UI.
857 * @param value if true, this query will only include downloads that should be displayed in
858 * the system's Downloads UI; if false (the default), this query will include
859 * both visible and invisible downloads.
860 * @return this object
863 public Query setOnlyIncludeVisibleInDownloadsUi(boolean value) {
864 mOnlyIncludeVisibleInDownloadsUi = value;
869 * Change the sort order of the returned Cursor.
871 * @param column one of the COLUMN_* constants; currently, only
872 * {@link #COLUMN_LAST_MODIFIED_TIMESTAMP} and {@link #COLUMN_TOTAL_SIZE_BYTES} are
874 * @param direction either {@link #ORDER_ASCENDING} or {@link #ORDER_DESCENDING}
875 * @return this object
878 public Query orderBy(String column, int direction) {
879 if (direction != ORDER_ASCENDING && direction != ORDER_DESCENDING) {
880 throw new IllegalArgumentException("Invalid direction: " + direction);
883 if (column.equals(COLUMN_LAST_MODIFIED_TIMESTAMP)) {
884 mOrderByColumn = Downloads.Impl.COLUMN_LAST_MODIFICATION;
885 } else if (column.equals(COLUMN_TOTAL_SIZE_BYTES)) {
886 mOrderByColumn = Downloads.Impl.COLUMN_TOTAL_BYTES;
888 throw new IllegalArgumentException("Cannot order by " + column);
890 mOrderDirection = direction;
895 * Run this query using the given ContentResolver.
896 * @param projection the projection to pass to ContentResolver.query()
897 * @return the Cursor returned by ContentResolver.query()
899 Cursor runQuery(ContentResolver resolver, String[] projection, Uri baseUri) {
901 List<String> selectionParts = new ArrayList<String>();
902 String[] selectionArgs = null;
904 int whereArgsCount = (mIds == null) ? 0 : mIds.length;
905 whereArgsCount = (mFilterString == null) ? whereArgsCount : whereArgsCount + 1;
906 selectionArgs = new String[whereArgsCount];
908 if (whereArgsCount > 0) {
910 selectionParts.add(getWhereClauseForIds(mIds));
911 getWhereArgsForIds(mIds, selectionArgs);
914 if (mFilterString != null) {
915 selectionParts.add(Downloads.Impl.COLUMN_TITLE + " LIKE ?");
916 selectionArgs[selectionArgs.length - 1] = "%" + mFilterString + "%";
920 if (mStatusFlags != null) {
921 List<String> parts = new ArrayList<String>();
922 if ((mStatusFlags & STATUS_PENDING) != 0) {
923 parts.add(statusClause("=", Downloads.Impl.STATUS_PENDING));
925 if ((mStatusFlags & STATUS_RUNNING) != 0) {
926 parts.add(statusClause("=", Downloads.Impl.STATUS_RUNNING));
928 if ((mStatusFlags & STATUS_PAUSED) != 0) {
929 parts.add(statusClause("=", Downloads.Impl.STATUS_PAUSED_BY_APP));
930 parts.add(statusClause("=", Downloads.Impl.STATUS_WAITING_TO_RETRY));
931 parts.add(statusClause("=", Downloads.Impl.STATUS_WAITING_FOR_NETWORK));
932 parts.add(statusClause("=", Downloads.Impl.STATUS_QUEUED_FOR_WIFI));
934 if ((mStatusFlags & STATUS_SUCCESSFUL) != 0) {
935 parts.add(statusClause("=", Downloads.Impl.STATUS_SUCCESS));
937 if ((mStatusFlags & STATUS_FAILED) != 0) {
938 parts.add("(" + statusClause(">=", 400)
939 + " AND " + statusClause("<", 600) + ")");
941 selectionParts.add(joinStrings(" OR ", parts));
944 if (mOnlyIncludeVisibleInDownloadsUi) {
945 selectionParts.add(Downloads.Impl.COLUMN_IS_VISIBLE_IN_DOWNLOADS_UI + " != '0'");
948 // only return rows which are not marked 'deleted = 1'
949 selectionParts.add(Downloads.Impl.COLUMN_DELETED + " != '1'");
951 String selection = joinStrings(" AND ", selectionParts);
952 String orderDirection = (mOrderDirection == ORDER_ASCENDING ? "ASC" : "DESC");
953 String orderBy = mOrderByColumn + " " + orderDirection;
955 return resolver.query(uri, projection, selection, selectionArgs, orderBy);
958 private String joinStrings(String joiner, Iterable<String> parts) {
959 StringBuilder builder = new StringBuilder();
960 boolean first = true;
961 for (String part : parts) {
963 builder.append(joiner);
965 builder.append(part);
968 return builder.toString();
971 private String statusClause(String operator, int value) {
972 return Downloads.Impl.COLUMN_STATUS + operator + "'" + value + "'";
976 private final ContentResolver mResolver;
977 private final String mPackageName;
979 private Uri mBaseUri = Downloads.Impl.CONTENT_URI;
980 private boolean mAccessFilename;
985 public DownloadManager(Context context) {
986 mResolver = context.getContentResolver();
987 mPackageName = context.getPackageName();
989 // Callers can access filename columns when targeting old platform
990 // versions; otherwise we throw telling them it's deprecated.
991 mAccessFilename = context.getApplicationInfo().targetSdkVersion < Build.VERSION_CODES.N;
995 * Makes this object access the download provider through /all_downloads URIs rather than
996 * /my_downloads URIs, for clients that have permission to do so.
999 public void setAccessAllDownloads(boolean accessAllDownloads) {
1000 if (accessAllDownloads) {
1001 mBaseUri = Downloads.Impl.ALL_DOWNLOADS_CONTENT_URI;
1003 mBaseUri = Downloads.Impl.CONTENT_URI;
1008 public void setAccessFilename(boolean accessFilename) {
1009 mAccessFilename = accessFilename;
1013 * Enqueue a new download. The download will start automatically once the download manager is
1014 * ready to execute it and connectivity is available.
1016 * @param request the parameters specifying this download
1017 * @return an ID for the download, unique across the system. This ID is used to make future
1018 * calls related to this download.
1020 public long enqueue(Request request) {
1021 ContentValues values = request.toContentValues(mPackageName);
1022 Uri downloadUri = mResolver.insert(Downloads.Impl.CONTENT_URI, values);
1023 long id = Long.parseLong(downloadUri.getLastPathSegment());
1028 * Marks the specified download as 'to be deleted'. This is done when a completed download
1029 * is to be removed but the row was stored without enough info to delete the corresponding
1030 * metadata from Mediaprovider database. Actual cleanup of this row is done in DownloadService.
1032 * @param ids the IDs of the downloads to be marked 'deleted'
1033 * @return the number of downloads actually updated
1036 public int markRowDeleted(long... ids) {
1037 if (ids == null || ids.length == 0) {
1038 // called with nothing to remove!
1039 throw new IllegalArgumentException("input param 'ids' can't be null");
1041 return mResolver.delete(mBaseUri, getWhereClauseForIds(ids), getWhereArgsForIds(ids));
1045 * Cancel downloads and remove them from the download manager. Each download will be stopped if
1046 * it was running, and it will no longer be accessible through the download manager.
1047 * If there is a downloaded file, partial or complete, it is deleted.
1049 * @param ids the IDs of the downloads to remove
1050 * @return the number of downloads actually removed
1052 public int remove(long... ids) {
1053 return markRowDeleted(ids);
1057 * Query the download manager about downloads that have been requested.
1058 * @param query parameters specifying filters for this query
1059 * @return a Cursor over the result set of downloads, with columns consisting of all the
1060 * COLUMN_* constants.
1062 public Cursor query(Query query) {
1063 Cursor underlyingCursor = query.runQuery(mResolver, UNDERLYING_COLUMNS, mBaseUri);
1064 if (underlyingCursor == null) {
1067 return new CursorTranslator(underlyingCursor, mBaseUri, mAccessFilename);
1071 * Open a downloaded file for reading. The download must have completed.
1072 * @param id the ID of the download
1073 * @return a read-only {@link ParcelFileDescriptor}
1074 * @throws FileNotFoundException if the destination file does not already exist
1076 public ParcelFileDescriptor openDownloadedFile(long id) throws FileNotFoundException {
1077 return mResolver.openFileDescriptor(getDownloadUri(id), "r");
1081 * Returns the {@link Uri} of the given downloaded file id, if the file is
1082 * downloaded successfully. Otherwise, null is returned.
1084 * @param id the id of the downloaded file.
1085 * @return the {@link Uri} of the given downloaded file id, if download was
1086 * successful. null otherwise.
1088 public Uri getUriForDownloadedFile(long id) {
1089 // to check if the file is in cache, get its destination from the database
1090 Query query = new Query().setFilterById(id);
1091 Cursor cursor = null;
1093 cursor = query(query);
1094 if (cursor == null) {
1097 if (cursor.moveToFirst()) {
1098 int status = cursor.getInt(cursor.getColumnIndexOrThrow(COLUMN_STATUS));
1099 if (DownloadManager.STATUS_SUCCESSFUL == status) {
1100 return ContentUris.withAppendedId(Downloads.Impl.ALL_DOWNLOADS_CONTENT_URI, id);
1104 if (cursor != null) {
1108 // downloaded file not found or its status is not 'successfully completed'
1113 * Returns the media type of the given downloaded file id, if the file was
1114 * downloaded successfully. Otherwise, null is returned.
1116 * @param id the id of the downloaded file.
1117 * @return the media type of the given downloaded file id, if download was successful. null
1120 public String getMimeTypeForDownloadedFile(long id) {
1121 Query query = new Query().setFilterById(id);
1122 Cursor cursor = null;
1124 cursor = query(query);
1125 if (cursor == null) {
1128 while (cursor.moveToFirst()) {
1129 return cursor.getString(cursor.getColumnIndexOrThrow(COLUMN_MEDIA_TYPE));
1132 if (cursor != null) {
1136 // downloaded file not found or its status is not 'successfully completed'
1141 * Restart the given downloads, which must have already completed (successfully or not). This
1142 * method will only work when called from within the download manager's process.
1143 * @param ids the IDs of the downloads
1146 public void restartDownload(long... ids) {
1147 Cursor cursor = query(new Query().setFilterById(ids));
1149 for (cursor.moveToFirst(); !cursor.isAfterLast(); cursor.moveToNext()) {
1150 int status = cursor.getInt(cursor.getColumnIndex(COLUMN_STATUS));
1151 if (status != STATUS_SUCCESSFUL && status != STATUS_FAILED) {
1152 throw new IllegalArgumentException("Cannot restart incomplete download: "
1153 + cursor.getLong(cursor.getColumnIndex(COLUMN_ID)));
1160 ContentValues values = new ContentValues();
1161 values.put(Downloads.Impl.COLUMN_CURRENT_BYTES, 0);
1162 values.put(Downloads.Impl.COLUMN_TOTAL_BYTES, -1);
1163 values.putNull(Downloads.Impl._DATA);
1164 values.put(Downloads.Impl.COLUMN_STATUS, Downloads.Impl.STATUS_PENDING);
1165 values.put(Downloads.Impl.COLUMN_FAILED_CONNECTIONS, 0);
1166 mResolver.update(mBaseUri, values, getWhereClauseForIds(ids), getWhereArgsForIds(ids));
1170 * Force the given downloads to proceed even if their size is larger than
1171 * {@link #getMaxBytesOverMobile(Context)}.
1175 public void forceDownload(long... ids) {
1176 ContentValues values = new ContentValues();
1177 values.put(Downloads.Impl.COLUMN_STATUS, Downloads.Impl.STATUS_PENDING);
1178 values.put(Downloads.Impl.COLUMN_CONTROL, Downloads.Impl.CONTROL_RUN);
1179 values.put(Downloads.Impl.COLUMN_BYPASS_RECOMMENDED_SIZE_LIMIT, 1);
1180 mResolver.update(mBaseUri, values, getWhereClauseForIds(ids), getWhereArgsForIds(ids));
1184 * Returns maximum size, in bytes, of downloads that may go over a mobile connection; or null if
1187 * @param context the {@link Context} to use for accessing the {@link ContentResolver}
1188 * @return maximum size, in bytes, of downloads that may go over a mobile connection; or null if
1191 public static Long getMaxBytesOverMobile(Context context) {
1193 return Settings.Global.getLong(context.getContentResolver(),
1194 Settings.Global.DOWNLOAD_MAX_BYTES_OVER_MOBILE);
1195 } catch (SettingNotFoundException exc) {
1201 * Rename the given download if the download has completed
1203 * @param context the {@link Context} to use in case need to update MediaProvider
1204 * @param id the downloaded id
1205 * @param displayName the new name to rename to
1206 * @return true if rename was successful, false otherwise
1209 public boolean rename(Context context, long id, String displayName) {
1210 if (!FileUtils.isValidFatFilename(displayName)) {
1211 throw new SecurityException(displayName + " is not a valid filename");
1214 Query query = new Query().setFilterById(id);
1215 Cursor cursor = null;
1216 String oldDisplayName = null;
1217 String mimeType = null;
1219 cursor = query(query);
1220 if (cursor == null) {
1223 if (cursor.moveToFirst()) {
1224 int status = cursor.getInt(cursor.getColumnIndexOrThrow(COLUMN_STATUS));
1225 if (DownloadManager.STATUS_SUCCESSFUL != status) {
1228 oldDisplayName = cursor.getString(cursor.getColumnIndexOrThrow(COLUMN_TITLE));
1229 mimeType = cursor.getString(cursor.getColumnIndexOrThrow(COLUMN_MEDIA_TYPE));
1232 if (cursor != null) {
1237 if (oldDisplayName == null || mimeType == null) {
1238 throw new IllegalStateException(
1239 "Document with id " + id + " does not exist");
1242 final File parent = Environment.getExternalStoragePublicDirectory(
1243 Environment.DIRECTORY_DOWNLOADS);
1245 final File before = new File(parent, oldDisplayName);
1246 final File after = new File(parent, displayName);
1248 if (after.exists()) {
1249 throw new IllegalStateException("Already exists " + after);
1251 if (!before.renameTo(after)) {
1252 throw new IllegalStateException("Failed to rename to " + after);
1255 // Update MediaProvider if necessary
1256 if (mimeType.startsWith("image/")) {
1257 context.getContentResolver().delete(Images.Media.EXTERNAL_CONTENT_URI,
1258 Images.Media.DATA + "=?",
1260 before.getAbsolutePath()
1263 Intent intent = new Intent(Intent.ACTION_MEDIA_SCANNER_SCAN_FILE);
1264 intent.setData(Uri.fromFile(after));
1265 context.sendBroadcast(intent);
1268 ContentValues values = new ContentValues();
1269 values.put(Downloads.Impl.COLUMN_TITLE, displayName);
1270 values.put(Downloads.Impl._DATA, after.toString());
1271 values.putNull(Downloads.Impl.COLUMN_MEDIAPROVIDER_URI);
1274 return (mResolver.update(mBaseUri, values, getWhereClauseForIds(ids),
1275 getWhereArgsForIds(ids)) == 1);
1279 * Returns recommended maximum size, in bytes, of downloads that may go over a mobile
1280 * connection; or null if there's no recommended limit. The user will have the option to bypass
1283 * @param context the {@link Context} to use for accessing the {@link ContentResolver}
1284 * @return recommended maximum size, in bytes, of downloads that may go over a mobile
1285 * connection; or null if there's no recommended limit.
1287 public static Long getRecommendedMaxBytesOverMobile(Context context) {
1289 return Settings.Global.getLong(context.getContentResolver(),
1290 Settings.Global.DOWNLOAD_RECOMMENDED_MAX_BYTES_OVER_MOBILE);
1291 } catch (SettingNotFoundException exc) {
1297 public static boolean isActiveNetworkExpensive(Context context) {
1298 // TODO: connect to NetworkPolicyManager
1303 public static long getActiveNetworkWarningBytes(Context context) {
1304 // TODO: connect to NetworkPolicyManager
1309 * Adds a file to the downloads database system, so it could appear in Downloads App
1310 * (and thus become eligible for management by the Downloads App).
1312 * It is helpful to make the file scannable by MediaScanner by setting the param
1313 * isMediaScannerScannable to true. It makes the file visible in media managing
1314 * applications such as Gallery App, which could be a useful purpose of using this API.
1316 * @param title the title that would appear for this file in Downloads App.
1317 * @param description the description that would appear for this file in Downloads App.
1318 * @param isMediaScannerScannable true if the file is to be scanned by MediaScanner. Files
1319 * scanned by MediaScanner appear in the applications used to view media (for example,
1321 * @param mimeType mimetype of the file.
1322 * @param path absolute pathname to the file. The file should be world-readable, so that it can
1323 * be managed by the Downloads App and any other app that is used to read it (for example,
1324 * Gallery app to display the file, if the file contents represent a video/image).
1325 * @param length length of the downloaded file
1326 * @param showNotification true if a notification is to be sent, false otherwise
1327 * @return an ID for the download entry added to the downloads app, unique across the system
1328 * This ID is used to make future calls related to this download.
1330 public long addCompletedDownload(String title, String description,
1331 boolean isMediaScannerScannable, String mimeType, String path, long length,
1332 boolean showNotification) {
1333 return addCompletedDownload(title, description, isMediaScannerScannable, mimeType, path,
1334 length, showNotification, false, null, null);
1338 * Adds a file to the downloads database system, so it could appear in Downloads App
1339 * (and thus become eligible for management by the Downloads App).
1341 * It is helpful to make the file scannable by MediaScanner by setting the param
1342 * isMediaScannerScannable to true. It makes the file visible in media managing
1343 * applications such as Gallery App, which could be a useful purpose of using this API.
1345 * @param title the title that would appear for this file in Downloads App.
1346 * @param description the description that would appear for this file in Downloads App.
1347 * @param isMediaScannerScannable true if the file is to be scanned by MediaScanner. Files
1348 * scanned by MediaScanner appear in the applications used to view media (for example,
1350 * @param mimeType mimetype of the file.
1351 * @param path absolute pathname to the file. The file should be world-readable, so that it can
1352 * be managed by the Downloads App and any other app that is used to read it (for example,
1353 * Gallery app to display the file, if the file contents represent a video/image).
1354 * @param length length of the downloaded file
1355 * @param showNotification true if a notification is to be sent, false otherwise
1356 * @param uri the original HTTP URI of the download
1357 * @param referer the HTTP Referer for the download
1358 * @return an ID for the download entry added to the downloads app, unique across the system
1359 * This ID is used to make future calls related to this download.
1361 public long addCompletedDownload(String title, String description,
1362 boolean isMediaScannerScannable, String mimeType, String path, long length,
1363 boolean showNotification, Uri uri, Uri referer) {
1364 return addCompletedDownload(title, description, isMediaScannerScannable, mimeType, path,
1365 length, showNotification, false, uri, referer);
1369 public long addCompletedDownload(String title, String description,
1370 boolean isMediaScannerScannable, String mimeType, String path, long length,
1371 boolean showNotification, boolean allowWrite) {
1372 return addCompletedDownload(title, description, isMediaScannerScannable, mimeType, path,
1373 length, showNotification, allowWrite, null, null);
1377 public long addCompletedDownload(String title, String description,
1378 boolean isMediaScannerScannable, String mimeType, String path, long length,
1379 boolean showNotification, boolean allowWrite, Uri uri, Uri referer) {
1380 // make sure the input args are non-null/non-zero
1381 validateArgumentIsNonEmpty("title", title);
1382 validateArgumentIsNonEmpty("description", description);
1383 validateArgumentIsNonEmpty("path", path);
1384 validateArgumentIsNonEmpty("mimeType", mimeType);
1386 throw new IllegalArgumentException(" invalid value for param: totalBytes");
1389 // if there is already an entry with the given path name in downloads.db, return its id
1392 request = new Request(uri);
1394 request = new Request(NON_DOWNLOADMANAGER_DOWNLOAD);
1396 request.setTitle(title)
1397 .setDescription(description)
1398 .setMimeType(mimeType);
1399 if (referer != null) {
1400 request.addRequestHeader("Referer", referer.toString());
1402 ContentValues values = request.toContentValues(null);
1403 values.put(Downloads.Impl.COLUMN_DESTINATION,
1404 Downloads.Impl.DESTINATION_NON_DOWNLOADMANAGER_DOWNLOAD);
1405 values.put(Downloads.Impl._DATA, path);
1406 values.put(Downloads.Impl.COLUMN_STATUS, Downloads.Impl.STATUS_SUCCESS);
1407 values.put(Downloads.Impl.COLUMN_TOTAL_BYTES, length);
1408 values.put(Downloads.Impl.COLUMN_MEDIA_SCANNED,
1409 (isMediaScannerScannable) ? Request.SCANNABLE_VALUE_YES :
1410 Request.SCANNABLE_VALUE_NO);
1411 values.put(Downloads.Impl.COLUMN_VISIBILITY, (showNotification) ?
1412 Request.VISIBILITY_VISIBLE_NOTIFY_ONLY_COMPLETION : Request.VISIBILITY_HIDDEN);
1413 values.put(Downloads.Impl.COLUMN_ALLOW_WRITE, allowWrite ? 1 : 0);
1414 Uri downloadUri = mResolver.insert(Downloads.Impl.CONTENT_URI, values);
1415 if (downloadUri == null) {
1418 return Long.parseLong(downloadUri.getLastPathSegment());
1421 private static final String NON_DOWNLOADMANAGER_DOWNLOAD =
1422 "non-dwnldmngr-download-dont-retry2download";
1424 private static void validateArgumentIsNonEmpty(String paramName, String val) {
1425 if (TextUtils.isEmpty(val)) {
1426 throw new IllegalArgumentException(paramName + " can't be null");
1431 * Get the DownloadProvider URI for the download with the given ID.
1435 public Uri getDownloadUri(long id) {
1436 return ContentUris.withAppendedId(Downloads.Impl.ALL_DOWNLOADS_CONTENT_URI, id);
1440 * Get a parameterized SQL WHERE clause to select a bunch of IDs.
1442 static String getWhereClauseForIds(long[] ids) {
1443 StringBuilder whereClause = new StringBuilder();
1444 whereClause.append("(");
1445 for (int i = 0; i < ids.length; i++) {
1447 whereClause.append("OR ");
1449 whereClause.append(Downloads.Impl._ID);
1450 whereClause.append(" = ? ");
1452 whereClause.append(")");
1453 return whereClause.toString();
1457 * Get the selection args for a clause returned by {@link #getWhereClauseForIds(long[])}.
1459 static String[] getWhereArgsForIds(long[] ids) {
1460 String[] whereArgs = new String[ids.length];
1461 return getWhereArgsForIds(ids, whereArgs);
1465 * Get selection args for a clause returned by {@link #getWhereClauseForIds(long[])}
1466 * and write it to the supplied args array.
1468 static String[] getWhereArgsForIds(long[] ids, String[] args) {
1469 assert(args.length >= ids.length);
1470 for (int i = 0; i < ids.length; i++) {
1471 args[i] = Long.toString(ids[i]);
1478 * This class wraps a cursor returned by DownloadProvider -- the "underlying cursor" -- and
1479 * presents a different set of columns, those defined in the DownloadManager.COLUMN_* constants.
1480 * Some columns correspond directly to underlying values while others are computed from
1483 private static class CursorTranslator extends CursorWrapper {
1484 private final Uri mBaseUri;
1485 private final boolean mAccessFilename;
1487 public CursorTranslator(Cursor cursor, Uri baseUri, boolean accessFilename) {
1490 mAccessFilename = accessFilename;
1494 public int getInt(int columnIndex) {
1495 return (int) getLong(columnIndex);
1499 public long getLong(int columnIndex) {
1500 if (getColumnName(columnIndex).equals(COLUMN_REASON)) {
1501 return getReason(super.getInt(getColumnIndex(Downloads.Impl.COLUMN_STATUS)));
1502 } else if (getColumnName(columnIndex).equals(COLUMN_STATUS)) {
1503 return translateStatus(super.getInt(getColumnIndex(Downloads.Impl.COLUMN_STATUS)));
1505 return super.getLong(columnIndex);
1510 public String getString(int columnIndex) {
1511 final String columnName = getColumnName(columnIndex);
1512 switch (columnName) {
1513 case COLUMN_LOCAL_URI:
1514 return getLocalUri();
1515 case COLUMN_LOCAL_FILENAME:
1516 if (!mAccessFilename) {
1517 throw new SecurityException(
1518 "COLUMN_LOCAL_FILENAME is deprecated;"
1519 + " use ContentResolver.openFileDescriptor() instead");
1522 return super.getString(columnIndex);
1526 private String getLocalUri() {
1527 long destinationType = getLong(getColumnIndex(Downloads.Impl.COLUMN_DESTINATION));
1528 if (destinationType == Downloads.Impl.DESTINATION_FILE_URI ||
1529 destinationType == Downloads.Impl.DESTINATION_EXTERNAL ||
1530 destinationType == Downloads.Impl.DESTINATION_NON_DOWNLOADMANAGER_DOWNLOAD) {
1531 String localPath = super.getString(getColumnIndex(COLUMN_LOCAL_FILENAME));
1532 if (localPath == null) {
1535 return Uri.fromFile(new File(localPath)).toString();
1538 // return content URI for cache download
1539 long downloadId = getLong(getColumnIndex(Downloads.Impl._ID));
1540 return ContentUris.withAppendedId(Downloads.Impl.ALL_DOWNLOADS_CONTENT_URI, downloadId).toString();
1543 private long getReason(int status) {
1544 switch (translateStatus(status)) {
1546 return getErrorCode(status);
1549 return getPausedReason(status);
1552 return 0; // arbitrary value when status is not an error
1556 private long getPausedReason(int status) {
1558 case Downloads.Impl.STATUS_WAITING_TO_RETRY:
1559 return PAUSED_WAITING_TO_RETRY;
1561 case Downloads.Impl.STATUS_WAITING_FOR_NETWORK:
1562 return PAUSED_WAITING_FOR_NETWORK;
1564 case Downloads.Impl.STATUS_QUEUED_FOR_WIFI:
1565 return PAUSED_QUEUED_FOR_WIFI;
1568 return PAUSED_UNKNOWN;
1572 private long getErrorCode(int status) {
1573 if ((400 <= status && status < Downloads.Impl.MIN_ARTIFICIAL_ERROR_STATUS)
1574 || (500 <= status && status < 600)) {
1580 case Downloads.Impl.STATUS_FILE_ERROR:
1581 return ERROR_FILE_ERROR;
1583 case Downloads.Impl.STATUS_UNHANDLED_HTTP_CODE:
1584 case Downloads.Impl.STATUS_UNHANDLED_REDIRECT:
1585 return ERROR_UNHANDLED_HTTP_CODE;
1587 case Downloads.Impl.STATUS_HTTP_DATA_ERROR:
1588 return ERROR_HTTP_DATA_ERROR;
1590 case Downloads.Impl.STATUS_TOO_MANY_REDIRECTS:
1591 return ERROR_TOO_MANY_REDIRECTS;
1593 case Downloads.Impl.STATUS_INSUFFICIENT_SPACE_ERROR:
1594 return ERROR_INSUFFICIENT_SPACE;
1596 case Downloads.Impl.STATUS_DEVICE_NOT_FOUND_ERROR:
1597 return ERROR_DEVICE_NOT_FOUND;
1599 case Downloads.Impl.STATUS_CANNOT_RESUME:
1600 return ERROR_CANNOT_RESUME;
1602 case Downloads.Impl.STATUS_FILE_ALREADY_EXISTS_ERROR:
1603 return ERROR_FILE_ALREADY_EXISTS;
1606 return ERROR_UNKNOWN;
1610 private int translateStatus(int status) {
1612 case Downloads.Impl.STATUS_PENDING:
1613 return STATUS_PENDING;
1615 case Downloads.Impl.STATUS_RUNNING:
1616 return STATUS_RUNNING;
1618 case Downloads.Impl.STATUS_PAUSED_BY_APP:
1619 case Downloads.Impl.STATUS_WAITING_TO_RETRY:
1620 case Downloads.Impl.STATUS_WAITING_FOR_NETWORK:
1621 case Downloads.Impl.STATUS_QUEUED_FOR_WIFI:
1622 return STATUS_PAUSED;
1624 case Downloads.Impl.STATUS_SUCCESS:
1625 return STATUS_SUCCESSFUL;
1628 assert Downloads.Impl.isStatusError(status);
1629 return STATUS_FAILED;