1 /* 2 * Copyright (C) 2010 The Android Open Source Project 3 * 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 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 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. 15 */ 16 17 package android.app; 18 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; 44 45 import java.io.File; 46 import java.io.FileNotFoundException; 47 import java.util.ArrayList; 48 import java.util.List; 49 50 /** 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. 55 * <p> 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. 59 * <p> 60 * Note that the application must have the {@link android.Manifest.permission#INTERNET} 61 * permission to use this class. 62 */ 63 @SystemService(Context.DOWNLOAD_SERVICE) 64 public class DownloadManager { 65 66 /** 67 * An identifier for a particular download, unique across the system. Clients use this ID to 68 * make subsequent calls related to the download. 69 */ 70 public final static String COLUMN_ID = Downloads.Impl._ID; 71 72 /** 73 * The client-supplied title for this download. This will be displayed in system notifications. 74 * Defaults to the empty string. 75 */ 76 public final static String COLUMN_TITLE = Downloads.Impl.COLUMN_TITLE; 77 78 /** 79 * The client-supplied description of this download. This will be displayed in system 80 * notifications. Defaults to the empty string. 81 */ 82 public final static String COLUMN_DESCRIPTION = Downloads.Impl.COLUMN_DESCRIPTION; 83 84 /** 85 * URI to be downloaded. 86 */ 87 public final static String COLUMN_URI = Downloads.Impl.COLUMN_URI; 88 89 /** 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 92 * started. 93 * 94 * @see <a href="http://www.ietf.org/rfc/rfc1590.txt">RFC 1590, defining Media Types</a> 95 */ 96 public final static String COLUMN_MEDIA_TYPE = "media_type"; 97 98 /** 99 * Total size of the download in bytes. This will initially be -1 and will be filled in once 100 * the download starts. 101 */ 102 public final static String COLUMN_TOTAL_SIZE_BYTES = "total_size"; 103 104 /** 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. 108 */ 109 public final static String COLUMN_LOCAL_URI = "local_uri"; 110 111 /** 112 * Path to the downloaded file on disk. 113 * <p> 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. 117 * 118 * @deprecated apps should transition to using 119 * {@link ContentResolver#openFileDescriptor(Uri, String)} 120 * instead. 121 */ 122 @Deprecated 123 public final static String COLUMN_LOCAL_FILENAME = "local_filename"; 124 125 /** 126 * Current status of the download, as one of the STATUS_* constants. 127 */ 128 public final static String COLUMN_STATUS = Downloads.Impl.COLUMN_STATUS; 129 130 /** 131 * Provides more detail on the status of the download. Its meaning depends on the value of 132 * {@link #COLUMN_STATUS}. 133 * 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. 137 * 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. 140 * 141 * If {@link #COLUMN_STATUS} is neither {@link #STATUS_FAILED} nor {@link #STATUS_PAUSED}, this 142 * column's value is undefined. 143 * 144 * @see <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html#sec6.1.1">RFC 2616 145 * status codes</a> 146 */ 147 public final static String COLUMN_REASON = "reason"; 148 149 /** 150 * Number of bytes download so far. 151 */ 152 public final static String COLUMN_BYTES_DOWNLOADED_SO_FAR = "bytes_so_far"; 153 154 /** 155 * Timestamp when the download was last modified, in {@link System#currentTimeMillis 156 * System.currentTimeMillis()} (wall clock time in UTC). 157 */ 158 public final static String COLUMN_LAST_MODIFIED_TIMESTAMP = "last_modified_timestamp"; 159 160 /** 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 163 * downloaded list. 164 */ 165 public static final String COLUMN_MEDIAPROVIDER_URI = Downloads.Impl.COLUMN_MEDIAPROVIDER_URI; 166 167 /** 168 * @hide 169 */ 170 public final static String COLUMN_ALLOW_WRITE = Downloads.Impl.COLUMN_ALLOW_WRITE; 171 172 /** 173 * Value of {@link #COLUMN_STATUS} when the download is waiting to start. 174 */ 175 public final static int STATUS_PENDING = 1 << 0; 176 177 /** 178 * Value of {@link #COLUMN_STATUS} when the download is currently running. 179 */ 180 public final static int STATUS_RUNNING = 1 << 1; 181 182 /** 183 * Value of {@link #COLUMN_STATUS} when the download is waiting to retry or resume. 184 */ 185 public final static int STATUS_PAUSED = 1 << 2; 186 187 /** 188 * Value of {@link #COLUMN_STATUS} when the download has successfully completed. 189 */ 190 public final static int STATUS_SUCCESSFUL = 1 << 3; 191 192 /** 193 * Value of {@link #COLUMN_STATUS} when the download has failed (and will not be retried). 194 */ 195 public final static int STATUS_FAILED = 1 << 4; 196 197 /** 198 * Value of COLUMN_ERROR_CODE when the download has completed with an error that doesn't fit 199 * under any other error code. 200 */ 201 public final static int ERROR_UNKNOWN = 1000; 202 203 /** 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. 207 */ 208 public final static int ERROR_FILE_ERROR = 1001; 209 210 /** 211 * Value of {@link #COLUMN_REASON} when an HTTP code was received that download manager 212 * can't handle. 213 */ 214 public final static int ERROR_UNHANDLED_HTTP_CODE = 1002; 215 216 /** 217 * Value of {@link #COLUMN_REASON} when an error receiving or processing data occurred at 218 * the HTTP level. 219 */ 220 public final static int ERROR_HTTP_DATA_ERROR = 1004; 221 222 /** 223 * Value of {@link #COLUMN_REASON} when there were too many redirects. 224 */ 225 public final static int ERROR_TOO_MANY_REDIRECTS = 1005; 226 227 /** 228 * Value of {@link #COLUMN_REASON} when there was insufficient storage space. Typically, 229 * this is because the SD card is full. 230 */ 231 public final static int ERROR_INSUFFICIENT_SPACE = 1006; 232 233 /** 234 * Value of {@link #COLUMN_REASON} when no external storage device was found. Typically, 235 * this is because the SD card is not mounted. 236 */ 237 public final static int ERROR_DEVICE_NOT_FOUND = 1007; 238 239 /** 240 * Value of {@link #COLUMN_REASON} when some possibly transient error occurred but we can't 241 * resume the download. 242 */ 243 public final static int ERROR_CANNOT_RESUME = 1008; 244 245 /** 246 * Value of {@link #COLUMN_REASON} when the requested destination file already exists (the 247 * download manager will not overwrite an existing file). 248 */ 249 public final static int ERROR_FILE_ALREADY_EXISTS = 1009; 250 251 /** 252 * Value of {@link #COLUMN_REASON} when the download has failed because of 253 * {@link NetworkPolicyManager} controls on the requesting application. 254 * 255 * @hide 256 */ 257 public final static int ERROR_BLOCKED = 1010; 258 259 /** 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. 262 */ 263 public final static int PAUSED_WAITING_TO_RETRY = 1; 264 265 /** 266 * Value of {@link #COLUMN_REASON} when the download is waiting for network connectivity to 267 * proceed. 268 */ 269 public final static int PAUSED_WAITING_FOR_NETWORK = 2; 270 271 /** 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. 274 */ 275 public final static int PAUSED_QUEUED_FOR_WIFI = 3; 276 277 /** 278 * Value of {@link #COLUMN_REASON} when the download is paused for some other reason. 279 */ 280 public final static int PAUSED_UNKNOWN = 4; 281 282 /** 283 * Broadcast intent action sent by the download manager when a download completes. 284 */ 285 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 286 public final static String ACTION_DOWNLOAD_COMPLETE = "android.intent.action.DOWNLOAD_COMPLETE"; 287 288 /** 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. 291 */ 292 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 293 public final static String ACTION_NOTIFICATION_CLICKED = 294 "android.intent.action.DOWNLOAD_NOTIFICATION_CLICKED"; 295 296 /** 297 * Intent action to launch an activity to display all downloads. 298 */ 299 @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) 300 public final static String ACTION_VIEW_DOWNLOADS = "android.intent.action.VIEW_DOWNLOADS"; 301 302 /** 303 * Intent extra included with {@link #ACTION_VIEW_DOWNLOADS} to start DownloadApp in 304 * sort-by-size mode. 305 */ 306 public final static String INTENT_EXTRAS_SORT_BY_SIZE = 307 "android.app.DownloadManager.extra_sortBySize"; 308 309 /** 310 * Intent extra included with {@link #ACTION_DOWNLOAD_COMPLETE} intents, indicating the ID (as a 311 * long) of the download that just completed. 312 */ 313 public static final String EXTRA_DOWNLOAD_ID = "extra_download_id"; 314 315 /** 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)}. 320 */ 321 public static final String EXTRA_NOTIFICATION_CLICK_DOWNLOAD_IDS = "extra_click_download_ids"; 322 323 /** {@hide} */ 324 @SystemApi 325 public static final String ACTION_DOWNLOAD_COMPLETED = 326 "android.intent.action.DOWNLOAD_COMPLETED"; 327 328 /** 329 * columns to request from DownloadProvider. 330 * @hide 331 */ 332 public static final String[] UNDERLYING_COLUMNS = new String[] { 333 Downloads.Impl._ID, 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 350 */ 351 "'placeholder' AS " + COLUMN_LOCAL_URI, 352 "'placeholder' AS " + COLUMN_REASON 353 }; 354 355 /** 356 * This class contains all the information necessary to request a new download. The URI is the 357 * only required parameter. 358 * 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)}. 362 */ 363 public static class Request { 364 /** 365 * Bit flag for {@link #setAllowedNetworkTypes} corresponding to 366 * {@link ConnectivityManager#TYPE_MOBILE}. 367 */ 368 public static final int NETWORK_MOBILE = 1 << 0; 369 370 /** 371 * Bit flag for {@link #setAllowedNetworkTypes} corresponding to 372 * {@link ConnectivityManager#TYPE_WIFI}. 373 */ 374 public static final int NETWORK_WIFI = 1 << 1; 375 376 /** 377 * Bit flag for {@link #setAllowedNetworkTypes} corresponding to 378 * {@link ConnectivityManager#TYPE_BLUETOOTH}. 379 * @hide 380 */ 381 @Deprecated 382 public static final int NETWORK_BLUETOOTH = 1 << 2; 383 384 private Uri mUri; 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}. 398 */ 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 401 // MediaScanner 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}. 405 */ 406 private static final int SCANNABLE_VALUE_NO = 2; 407 408 /** 409 * This download is visible but only shows in the notifications 410 * while it's in progress. 411 */ 412 public static final int VISIBILITY_VISIBLE = 0; 413 414 /** 415 * This download is visible and shows in the notifications while 416 * in progress and after completion. 417 */ 418 public static final int VISIBILITY_VISIBLE_NOTIFY_COMPLETED = 1; 419 420 /** 421 * This download doesn't show in the UI or in the notifications. 422 */ 423 public static final int VISIBILITY_HIDDEN = 2; 424 425 /** 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)}. 430 */ 431 public static final int VISIBILITY_VISIBLE_NOTIFY_ONLY_COMPLETION = 3; 432 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} 436 */ 437 private int mNotificationVisibility = VISIBILITY_VISIBLE; 438 439 /** 440 * @param uri the HTTP or HTTPS URI to download. 441 */ 442 public Request(Uri uri) { 443 if (uri == null) { 444 throw new NullPointerException(); 445 } 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); 449 } 450 mUri = uri; 451 } 452 453 Request(String uriString) { 454 mUri = Uri.parse(uriString); 455 } 456 457 /** 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 460 * permission. 461 * <p> 462 * The downloaded file is not scanned by MediaScanner. 463 * But it can be made scannable by calling {@link #allowScanningByMediaScanner()}. 464 * <p> 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. 467 * 468 * @return this object 469 */ 470 public Request setDestinationUri(Uri uri) { 471 mDestinationUri = uri; 472 return this; 473 } 474 475 /** 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)}. 479 * <p> 480 * The downloaded file is not scanned by MediaScanner. But it can be 481 * made scannable by calling {@link #allowScanningByMediaScanner()}. 482 * 483 * @param context the {@link Context} to use in determining the external 484 * files directory 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. 492 */ 493 public Request setDestinationInExternalFilesDir(Context context, String dirType, 494 String subPath) { 495 final File file = context.getExternalFilesDir(dirType); 496 if (file == null) { 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"); 502 } 503 } else { 504 if (!file.mkdirs()) { 505 throw new IllegalStateException("Unable to create directory: "+ 506 file.getAbsolutePath()); 507 } 508 } 509 setDestinationFromBase(file, subPath); 510 return this; 511 } 512 513 /** 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)}). 517 * <p> 518 * The downloaded file is not scanned by MediaScanner. But it can be 519 * made scannable by calling {@link #allowScanningByMediaScanner()}. 520 * 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. 527 */ 528 public Request setDestinationInExternalPublicDir(String dirType, String subPath) { 529 File file = Environment.getExternalStoragePublicDirectory(dirType); 530 if (file == null) { 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"); 536 } 537 } else { 538 if (!file.mkdirs()) { 539 throw new IllegalStateException("Unable to create directory: "+ 540 file.getAbsolutePath()); 541 } 542 } 543 setDestinationFromBase(file, subPath); 544 return this; 545 } 546 547 private void setDestinationFromBase(File base, String subPath) { 548 if (subPath == null) { 549 throw new NullPointerException("subPath cannot be null"); 550 } 551 mDestinationUri = Uri.withAppendedPath(Uri.fromFile(base), subPath); 552 } 553 554 /** 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. 557 */ 558 public void allowScanningByMediaScanner() { 559 mScannable = true; 560 } 561 562 /** 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> 570 */ 571 public Request addRequestHeader(String header, String value) { 572 if (header == null) { 573 throw new NullPointerException("header cannot be null"); 574 } 575 if (header.contains(":")) { 576 throw new IllegalArgumentException("header may not contain ':'"); 577 } 578 if (value == null) { 579 value = ""; 580 } 581 mRequestHeaders.add(Pair.create(header, value)); 582 return this; 583 } 584 585 /** 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 588 * download starts. 589 * @return this object 590 */ 591 public Request setTitle(CharSequence title) { 592 mTitle = title; 593 return this; 594 } 595 596 /** 597 * Set a description of this download, to be displayed in notifications (if enabled) 598 * @return this object 599 */ 600 public Request setDescription(CharSequence description) { 601 mDescription = description; 602 return this; 603 } 604 605 /** 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 609 * Media Types</a> 610 * @return this object 611 */ 612 public Request setMimeType(String mimeType) { 613 mMimeType = mimeType; 614 return this; 615 } 616 617 /** 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 621 * shown. 622 * 623 * If set to false, this requires the permission 624 * android.permission.DOWNLOAD_WITHOUT_NOTIFICATION. 625 * 626 * @param show whether the download manager should show a notification for this download. 627 * @return this object 628 * @deprecated use {@link #setNotificationVisibility(int)} 629 */ 630 @Deprecated 631 public Request setShowRunningNotification(boolean show) { 632 return (show) ? setNotificationVisibility(VISIBILITY_VISIBLE) : 633 setNotificationVisibility(VISIBILITY_HIDDEN); 634 } 635 636 /** 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. 642 *<p> 643 * It can take the following values: {@link #VISIBILITY_HIDDEN}, 644 * {@link #VISIBILITY_VISIBLE}, 645 * {@link #VISIBILITY_VISIBLE_NOTIFY_COMPLETED}. 646 *<p> 647 * If set to {@link #VISIBILITY_HIDDEN}, this requires the permission 648 * android.permission.DOWNLOAD_WITHOUT_NOTIFICATION. 649 * 650 * @param visibility the visibility setting value 651 * @return this object 652 */ 653 public Request setNotificationVisibility(int visibility) { 654 mNotificationVisibility = visibility; 655 return this; 656 } 657 658 /** 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 662 * flexible. 663 * <p> 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}. 667 * 668 * @param flags any combination of the NETWORK_* bit flags. 669 * @return this object 670 */ 671 public Request setAllowedNetworkTypes(int flags) { 672 mAllowedNetworkTypes = flags; 673 return this; 674 } 675 676 /** 677 * Set whether this download may proceed over a roaming connection. By default, roaming is 678 * allowed. 679 * @param allowed whether to allow a roaming connection to be used 680 * @return this object 681 */ 682 public Request setAllowedOverRoaming(boolean allowed) { 683 mRoamingAllowed = allowed; 684 return this; 685 } 686 687 /** 688 * Set whether this download may proceed over a metered network 689 * connection. By default, metered networks are allowed. 690 * 691 * @see ConnectivityManager#isActiveNetworkMetered() 692 */ 693 public Request setAllowedOverMetered(boolean allow) { 694 mMeteredAllowed = allow; 695 return this; 696 } 697 698 /** 699 * Specify that to run this download, the device needs to be plugged in. 700 * This defaults to false. 701 * 702 * @param requiresCharging Whether or not the device is plugged in. 703 * @see android.app.job.JobInfo.Builder#setRequiresCharging(boolean) 704 */ 705 public Request setRequiresCharging(boolean requiresCharging) { 706 if (requiresCharging) { 707 mFlags |= Downloads.Impl.FLAG_REQUIRES_CHARGING; 708 } else { 709 mFlags &= ~Downloads.Impl.FLAG_REQUIRES_CHARGING; 710 } 711 return this; 712 } 713 714 /** 715 * Specify that to run, the download needs the device to be in idle 716 * mode. This defaults to false. 717 * <p> 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. 720 * 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) 724 */ 725 public Request setRequiresDeviceIdle(boolean requiresDeviceIdle) { 726 if (requiresDeviceIdle) { 727 mFlags |= Downloads.Impl.FLAG_REQUIRES_DEVICE_IDLE; 728 } else { 729 mFlags &= ~Downloads.Impl.FLAG_REQUIRES_DEVICE_IDLE; 730 } 731 return this; 732 } 733 734 /** 735 * Set whether this download should be displayed in the system's Downloads UI. True by 736 * default. 737 * @param isVisible whether to display this download in the Downloads UI 738 * @return this object 739 */ 740 public Request setVisibleInDownloadsUi(boolean isVisible) { 741 mIsVisibleInDownloadsUi = isVisible; 742 return this; 743 } 744 745 /** 746 * @return ContentValues to be passed to DownloadProvider.insert() 747 */ 748 ContentValues toContentValues(String packageName) { 749 ContentValues values = new ContentValues(); 750 assert mUri != null; 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); 754 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()); 760 } else { 761 values.put(Downloads.Impl.COLUMN_DESTINATION, 762 Downloads.Impl.DESTINATION_CACHE_PARTITION_PURGEABLE); 763 } 764 // is the file supposed to be media-scannable? 765 values.put(Downloads.Impl.COLUMN_MEDIA_SCANNED, (mScannable) ? SCANNABLE_VALUE_YES : 766 SCANNABLE_VALUE_NO); 767 768 if (!mRequestHeaders.isEmpty()) { 769 encodeHttpHeaders(values); 770 } 771 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); 775 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); 782 783 return values; 784 } 785 786 private void encodeHttpHeaders(ContentValues values) { 787 int index = 0; 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); 791 index++; 792 } 793 } 794 795 private void putIfNonNull(ContentValues contentValues, String key, Object value) { 796 if (value != null) { 797 contentValues.put(key, value.toString()); 798 } 799 } 800 } 801 802 /** 803 * This class may be used to filter download manager queries. 804 */ 805 public static class Query { 806 /** 807 * Constant for use with {@link #orderBy} 808 * @hide 809 */ 810 public static final int ORDER_ASCENDING = 1; 811 812 /** 813 * Constant for use with {@link #orderBy} 814 * @hide 815 */ 816 public static final int ORDER_DESCENDING = 2; 817 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; 824 825 /** 826 * Include only the downloads with the given IDs. 827 * @return this object 828 */ 829 public Query setFilterById(long... ids) { 830 mIds = ids; 831 return this; 832 } 833 834 /** 835 * 836 * Include only the downloads that contains the given string in its name. 837 * @return this object 838 * @hide 839 */ 840 public Query setFilterByString(@Nullable String filter) { 841 mFilterString = filter; 842 return this; 843 } 844 845 /** 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 849 */ 850 public Query setFilterByStatus(int flags) { 851 mStatusFlags = flags; 852 return this; 853 } 854 855 /** 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 861 * @hide 862 */ 863 public Query setOnlyIncludeVisibleInDownloadsUi(boolean value) { 864 mOnlyIncludeVisibleInDownloadsUi = value; 865 return this; 866 } 867 868 /** 869 * Change the sort order of the returned Cursor. 870 * 871 * @param column one of the COLUMN_* constants; currently, only 872 * {@link #COLUMN_LAST_MODIFIED_TIMESTAMP} and {@link #COLUMN_TOTAL_SIZE_BYTES} are 873 * supported. 874 * @param direction either {@link #ORDER_ASCENDING} or {@link #ORDER_DESCENDING} 875 * @return this object 876 * @hide 877 */ 878 public Query orderBy(String column, int direction) { 879 if (direction != ORDER_ASCENDING && direction != ORDER_DESCENDING) { 880 throw new IllegalArgumentException("Invalid direction: " + direction); 881 } 882 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; 887 } else { 888 throw new IllegalArgumentException("Cannot order by " + column); 889 } 890 mOrderDirection = direction; 891 return this; 892 } 893 894 /** 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() 898 */ 899 Cursor runQuery(ContentResolver resolver, String[] projection, Uri baseUri) { 900 Uri uri = baseUri; 901 List<String> selectionParts = new ArrayList<String>(); 902 String[] selectionArgs = null; 903 904 int whereArgsCount = (mIds == null) ? 0 : mIds.length; 905 whereArgsCount = (mFilterString == null) ? whereArgsCount : whereArgsCount + 1; 906 selectionArgs = new String[whereArgsCount]; 907 908 if (whereArgsCount > 0) { 909 if (mIds != null) { 910 selectionParts.add(getWhereClauseForIds(mIds)); 911 getWhereArgsForIds(mIds, selectionArgs); 912 } 913 914 if (mFilterString != null) { 915 selectionParts.add(Downloads.Impl.COLUMN_TITLE + " LIKE ?"); 916 selectionArgs[selectionArgs.length - 1] = "%" + mFilterString + "%"; 917 } 918 } 919 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)); 924 } 925 if ((mStatusFlags & STATUS_RUNNING) != 0) { 926 parts.add(statusClause("=", Downloads.Impl.STATUS_RUNNING)); 927 } 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)); 933 } 934 if ((mStatusFlags & STATUS_SUCCESSFUL) != 0) { 935 parts.add(statusClause("=", Downloads.Impl.STATUS_SUCCESS)); 936 } 937 if ((mStatusFlags & STATUS_FAILED) != 0) { 938 parts.add("(" + statusClause(">=", 400) 939 + " AND " + statusClause("<", 600) + ")"); 940 } 941 selectionParts.add(joinStrings(" OR ", parts)); 942 } 943 944 if (mOnlyIncludeVisibleInDownloadsUi) { 945 selectionParts.add(Downloads.Impl.COLUMN_IS_VISIBLE_IN_DOWNLOADS_UI + " != '0'"); 946 } 947 948 // only return rows which are not marked 'deleted = 1' 949 selectionParts.add(Downloads.Impl.COLUMN_DELETED + " != '1'"); 950 951 String selection = joinStrings(" AND ", selectionParts); 952 String orderDirection = (mOrderDirection == ORDER_ASCENDING ? "ASC" : "DESC"); 953 String orderBy = mOrderByColumn + " " + orderDirection; 954 955 return resolver.query(uri, projection, selection, selectionArgs, orderBy); 956 } 957 958 private String joinStrings(String joiner, Iterable<String> parts) { 959 StringBuilder builder = new StringBuilder(); 960 boolean first = true; 961 for (String part : parts) { 962 if (!first) { 963 builder.append(joiner); 964 } 965 builder.append(part); 966 first = false; 967 } 968 return builder.toString(); 969 } 970 971 private String statusClause(String operator, int value) { 972 return Downloads.Impl.COLUMN_STATUS + operator + "'" + value + "'"; 973 } 974 } 975 976 private final ContentResolver mResolver; 977 private final String mPackageName; 978 979 private Uri mBaseUri = Downloads.Impl.CONTENT_URI; 980 private boolean mAccessFilename; 981 982 /** 983 * @hide 984 */ 985 public DownloadManager(Context context) { 986 mResolver = context.getContentResolver(); 987 mPackageName = context.getPackageName(); 988 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; 992 } 993 994 /** 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. 997 * @hide 998 */ 999 public void setAccessAllDownloads(boolean accessAllDownloads) { 1000 if (accessAllDownloads) { 1001 mBaseUri = Downloads.Impl.ALL_DOWNLOADS_CONTENT_URI; 1002 } else { 1003 mBaseUri = Downloads.Impl.CONTENT_URI; 1004 } 1005 } 1006 1007 /** {@hide} */ 1008 public void setAccessFilename(boolean accessFilename) { 1009 mAccessFilename = accessFilename; 1010 } 1011 1012 /** 1013 * Enqueue a new download. The download will start automatically once the download manager is 1014 * ready to execute it and connectivity is available. 1015 * 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. 1019 */ 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()); 1024 return id; 1025 } 1026 1027 /** 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. 1031 * 1032 * @param ids the IDs of the downloads to be marked 'deleted' 1033 * @return the number of downloads actually updated 1034 * @hide 1035 */ 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"); 1040 } 1041 return mResolver.delete(mBaseUri, getWhereClauseForIds(ids), getWhereArgsForIds(ids)); 1042 } 1043 1044 /** 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. 1048 * 1049 * @param ids the IDs of the downloads to remove 1050 * @return the number of downloads actually removed 1051 */ 1052 public int remove(long... ids) { 1053 return markRowDeleted(ids); 1054 } 1055 1056 /** 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. 1061 */ 1062 public Cursor query(Query query) { 1063 Cursor underlyingCursor = query.runQuery(mResolver, UNDERLYING_COLUMNS, mBaseUri); 1064 if (underlyingCursor == null) { 1065 return null; 1066 } 1067 return new CursorTranslator(underlyingCursor, mBaseUri, mAccessFilename); 1068 } 1069 1070 /** 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 1075 */ 1076 public ParcelFileDescriptor openDownloadedFile(long id) throws FileNotFoundException { 1077 return mResolver.openFileDescriptor(getDownloadUri(id), "r"); 1078 } 1079 1080 /** 1081 * Returns the {@link Uri} of the given downloaded file id, if the file is 1082 * downloaded successfully. Otherwise, null is returned. 1083 * 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. 1087 */ 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; 1092 try { 1093 cursor = query(query); 1094 if (cursor == null) { 1095 return null; 1096 } 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); 1101 } 1102 } 1103 } finally { 1104 if (cursor != null) { 1105 cursor.close(); 1106 } 1107 } 1108 // downloaded file not found or its status is not 'successfully completed' 1109 return null; 1110 } 1111 1112 /** 1113 * Returns the media type of the given downloaded file id, if the file was 1114 * downloaded successfully. Otherwise, null is returned. 1115 * 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 1118 * otherwise. 1119 */ 1120 public String getMimeTypeForDownloadedFile(long id) { 1121 Query query = new Query().setFilterById(id); 1122 Cursor cursor = null; 1123 try { 1124 cursor = query(query); 1125 if (cursor == null) { 1126 return null; 1127 } 1128 while (cursor.moveToFirst()) { 1129 return cursor.getString(cursor.getColumnIndexOrThrow(COLUMN_MEDIA_TYPE)); 1130 } 1131 } finally { 1132 if (cursor != null) { 1133 cursor.close(); 1134 } 1135 } 1136 // downloaded file not found or its status is not 'successfully completed' 1137 return null; 1138 } 1139 1140 /** 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 1144 * @hide 1145 */ 1146 public void restartDownload(long... ids) { 1147 Cursor cursor = query(new Query().setFilterById(ids)); 1148 try { 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))); 1154 } 1155 } 1156 } finally { 1157 cursor.close(); 1158 } 1159 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)); 1167 } 1168 1169 /** 1170 * Force the given downloads to proceed even if their size is larger than 1171 * {@link #getMaxBytesOverMobile(Context)}. 1172 * 1173 * @hide 1174 */ 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)); 1181 } 1182 1183 /** 1184 * Returns maximum size, in bytes, of downloads that may go over a mobile connection; or null if 1185 * there's no limit 1186 * 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 1189 * there's no limit 1190 */ 1191 public static Long getMaxBytesOverMobile(Context context) { 1192 try { 1193 return Settings.Global.getLong(context.getContentResolver(), 1194 Settings.Global.DOWNLOAD_MAX_BYTES_OVER_MOBILE); 1195 } catch (SettingNotFoundException exc) { 1196 return null; 1197 } 1198 } 1199 1200 /** 1201 * Rename the given download if the download has completed 1202 * 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 1207 * @hide 1208 */ 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"); 1212 } 1213 1214 Query query = new Query().setFilterById(id); 1215 Cursor cursor = null; 1216 String oldDisplayName = null; 1217 String mimeType = null; 1218 try { 1219 cursor = query(query); 1220 if (cursor == null) { 1221 return false; 1222 } 1223 if (cursor.moveToFirst()) { 1224 int status = cursor.getInt(cursor.getColumnIndexOrThrow(COLUMN_STATUS)); 1225 if (DownloadManager.STATUS_SUCCESSFUL != status) { 1226 return false; 1227 } 1228 oldDisplayName = cursor.getString(cursor.getColumnIndexOrThrow(COLUMN_TITLE)); 1229 mimeType = cursor.getString(cursor.getColumnIndexOrThrow(COLUMN_MEDIA_TYPE)); 1230 } 1231 } finally { 1232 if (cursor != null) { 1233 cursor.close(); 1234 } 1235 } 1236 1237 if (oldDisplayName == null || mimeType == null) { 1238 throw new IllegalStateException( 1239 "Document with id " + id + " does not exist"); 1240 } 1241 1242 final File parent = Environment.getExternalStoragePublicDirectory( 1243 Environment.DIRECTORY_DOWNLOADS); 1244 1245 final File before = new File(parent, oldDisplayName); 1246 final File after = new File(parent, displayName); 1247 1248 if (after.exists()) { 1249 throw new IllegalStateException("Already exists " + after); 1250 } 1251 if (!before.renameTo(after)) { 1252 throw new IllegalStateException("Failed to rename to " + after); 1253 } 1254 1255 // Update MediaProvider if necessary 1256 if (mimeType.startsWith("image/")) { 1257 context.getContentResolver().delete(Images.Media.EXTERNAL_CONTENT_URI, 1258 Images.Media.DATA + "=?", 1259 new String[] { 1260 before.getAbsolutePath() 1261 }); 1262 1263 Intent intent = new Intent(Intent.ACTION_MEDIA_SCANNER_SCAN_FILE); 1264 intent.setData(Uri.fromFile(after)); 1265 context.sendBroadcast(intent); 1266 } 1267 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); 1272 long[] ids = {id}; 1273 1274 return (mResolver.update(mBaseUri, values, getWhereClauseForIds(ids), 1275 getWhereArgsForIds(ids)) == 1); 1276 } 1277 1278 /** 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 1281 * this limit. 1282 * 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. 1286 */ 1287 public static Long getRecommendedMaxBytesOverMobile(Context context) { 1288 try { 1289 return Settings.Global.getLong(context.getContentResolver(), 1290 Settings.Global.DOWNLOAD_RECOMMENDED_MAX_BYTES_OVER_MOBILE); 1291 } catch (SettingNotFoundException exc) { 1292 return null; 1293 } 1294 } 1295 1296 /** {@hide} */ 1297 public static boolean isActiveNetworkExpensive(Context context) { 1298 // TODO: connect to NetworkPolicyManager 1299 return false; 1300 } 1301 1302 /** {@hide} */ 1303 public static long getActiveNetworkWarningBytes(Context context) { 1304 // TODO: connect to NetworkPolicyManager 1305 return -1; 1306 } 1307 1308 /** 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). 1311 * <p> 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. 1315 * 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, 1320 * Gallery app). 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. 1329 */ 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); 1335 } 1336 1337 /** 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). 1340 * <p> 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. 1344 * 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, 1349 * Gallery app). 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. 1360 */ 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); 1366 } 1367 1368 /** {@hide} */ 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); 1374 } 1375 1376 /** {@hide} */ 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); 1385 if (length < 0) { 1386 throw new IllegalArgumentException(" invalid value for param: totalBytes"); 1387 } 1388 1389 // if there is already an entry with the given path name in downloads.db, return its id 1390 Request request; 1391 if (uri != null) { 1392 request = new Request(uri); 1393 } else { 1394 request = new Request(NON_DOWNLOADMANAGER_DOWNLOAD); 1395 } 1396 request.setTitle(title) 1397 .setDescription(description) 1398 .setMimeType(mimeType); 1399 if (referer != null) { 1400 request.addRequestHeader("Referer", referer.toString()); 1401 } 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) { 1416 return -1; 1417 } 1418 return Long.parseLong(downloadUri.getLastPathSegment()); 1419 } 1420 1421 private static final String NON_DOWNLOADMANAGER_DOWNLOAD = 1422 "non-dwnldmngr-download-dont-retry2download"; 1423 1424 private static void validateArgumentIsNonEmpty(String paramName, String val) { 1425 if (TextUtils.isEmpty(val)) { 1426 throw new IllegalArgumentException(paramName + " can't be null"); 1427 } 1428 } 1429 1430 /** 1431 * Get the DownloadProvider URI for the download with the given ID. 1432 * 1433 * @hide 1434 */ 1435 public Uri getDownloadUri(long id) { 1436 return ContentUris.withAppendedId(Downloads.Impl.ALL_DOWNLOADS_CONTENT_URI, id); 1437 } 1438 1439 /** 1440 * Get a parameterized SQL WHERE clause to select a bunch of IDs. 1441 */ 1442 static String getWhereClauseForIds(long[] ids) { 1443 StringBuilder whereClause = new StringBuilder(); 1444 whereClause.append("("); 1445 for (int i = 0; i < ids.length; i++) { 1446 if (i > 0) { 1447 whereClause.append("OR "); 1448 } 1449 whereClause.append(Downloads.Impl._ID); 1450 whereClause.append(" = ? "); 1451 } 1452 whereClause.append(")"); 1453 return whereClause.toString(); 1454 } 1455 1456 /** 1457 * Get the selection args for a clause returned by {@link #getWhereClauseForIds(long[])}. 1458 */ 1459 static String[] getWhereArgsForIds(long[] ids) { 1460 String[] whereArgs = new String[ids.length]; 1461 return getWhereArgsForIds(ids, whereArgs); 1462 } 1463 1464 /** 1465 * Get selection args for a clause returned by {@link #getWhereClauseForIds(long[])} 1466 * and write it to the supplied args array. 1467 */ 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]); 1472 } 1473 return args; 1474 } 1475 1476 1477 /** 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 1481 * underlying data. 1482 */ 1483 private static class CursorTranslator extends CursorWrapper { 1484 private final Uri mBaseUri; 1485 private final boolean mAccessFilename; 1486 1487 public CursorTranslator(Cursor cursor, Uri baseUri, boolean accessFilename) { 1488 super(cursor); 1489 mBaseUri = baseUri; 1490 mAccessFilename = accessFilename; 1491 } 1492 1493 @Override 1494 public int getInt(int columnIndex) { 1495 return (int) getLong(columnIndex); 1496 } 1497 1498 @Override 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))); 1504 } else { 1505 return super.getLong(columnIndex); 1506 } 1507 } 1508 1509 @Override 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"); 1520 } 1521 default: 1522 return super.getString(columnIndex); 1523 } 1524 } 1525 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) { 1533 return null; 1534 } 1535 return Uri.fromFile(new File(localPath)).toString(); 1536 } 1537 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(); 1541 } 1542 1543 private long getReason(int status) { 1544 switch (translateStatus(status)) { 1545 case STATUS_FAILED: 1546 return getErrorCode(status); 1547 1548 case STATUS_PAUSED: 1549 return getPausedReason(status); 1550 1551 default: 1552 return 0; // arbitrary value when status is not an error 1553 } 1554 } 1555 1556 private long getPausedReason(int status) { 1557 switch (status) { 1558 case Downloads.Impl.STATUS_WAITING_TO_RETRY: 1559 return PAUSED_WAITING_TO_RETRY; 1560 1561 case Downloads.Impl.STATUS_WAITING_FOR_NETWORK: 1562 return PAUSED_WAITING_FOR_NETWORK; 1563 1564 case Downloads.Impl.STATUS_QUEUED_FOR_WIFI: 1565 return PAUSED_QUEUED_FOR_WIFI; 1566 1567 default: 1568 return PAUSED_UNKNOWN; 1569 } 1570 } 1571 1572 private long getErrorCode(int status) { 1573 if ((400 <= status && status < Downloads.Impl.MIN_ARTIFICIAL_ERROR_STATUS) 1574 || (500 <= status && status < 600)) { 1575 // HTTP status code 1576 return status; 1577 } 1578 1579 switch (status) { 1580 case Downloads.Impl.STATUS_FILE_ERROR: 1581 return ERROR_FILE_ERROR; 1582 1583 case Downloads.Impl.STATUS_UNHANDLED_HTTP_CODE: 1584 case Downloads.Impl.STATUS_UNHANDLED_REDIRECT: 1585 return ERROR_UNHANDLED_HTTP_CODE; 1586 1587 case Downloads.Impl.STATUS_HTTP_DATA_ERROR: 1588 return ERROR_HTTP_DATA_ERROR; 1589 1590 case Downloads.Impl.STATUS_TOO_MANY_REDIRECTS: 1591 return ERROR_TOO_MANY_REDIRECTS; 1592 1593 case Downloads.Impl.STATUS_INSUFFICIENT_SPACE_ERROR: 1594 return ERROR_INSUFFICIENT_SPACE; 1595 1596 case Downloads.Impl.STATUS_DEVICE_NOT_FOUND_ERROR: 1597 return ERROR_DEVICE_NOT_FOUND; 1598 1599 case Downloads.Impl.STATUS_CANNOT_RESUME: 1600 return ERROR_CANNOT_RESUME; 1601 1602 case Downloads.Impl.STATUS_FILE_ALREADY_EXISTS_ERROR: 1603 return ERROR_FILE_ALREADY_EXISTS; 1604 1605 default: 1606 return ERROR_UNKNOWN; 1607 } 1608 } 1609 1610 private int translateStatus(int status) { 1611 switch (status) { 1612 case Downloads.Impl.STATUS_PENDING: 1613 return STATUS_PENDING; 1614 1615 case Downloads.Impl.STATUS_RUNNING: 1616 return STATUS_RUNNING; 1617 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; 1623 1624 case Downloads.Impl.STATUS_SUCCESS: 1625 return STATUS_SUCCESSFUL; 1626 1627 default: 1628 assert Downloads.Impl.isStatusError(status); 1629 return STATUS_FAILED; 1630 } 1631 } 1632 } 1633 } 1634
