DocumentsContract.java revision 1719b3555dc9bff5394045585051e7d5684bceb1
1/* 2 * Copyright (C) 2013 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 17package android.provider; 18 19import static android.net.TrafficStats.KB_IN_BYTES; 20import static android.system.OsConstants.SEEK_SET; 21 22import android.annotation.Nullable; 23import android.content.ContentProviderClient; 24import android.content.ContentResolver; 25import android.content.Context; 26import android.content.Intent; 27import android.content.pm.ResolveInfo; 28import android.content.res.AssetFileDescriptor; 29import android.database.Cursor; 30import android.graphics.Bitmap; 31import android.graphics.BitmapFactory; 32import android.graphics.Matrix; 33import android.graphics.Point; 34import android.media.ExifInterface; 35import android.net.Uri; 36import android.os.Bundle; 37import android.os.CancellationSignal; 38import android.os.OperationCanceledException; 39import android.os.ParcelFileDescriptor; 40import android.os.ParcelFileDescriptor.OnCloseListener; 41import android.os.RemoteException; 42import android.os.storage.StorageVolume; 43import android.system.ErrnoException; 44import android.system.Os; 45import android.util.Log; 46 47import libcore.io.IoUtils; 48 49import java.io.BufferedInputStream; 50import java.io.File; 51import java.io.FileDescriptor; 52import java.io.FileInputStream; 53import java.io.FileNotFoundException; 54import java.io.IOException; 55import java.util.List; 56 57/** 58 * Defines the contract between a documents provider and the platform. 59 * <p> 60 * To create a document provider, extend {@link DocumentsProvider}, which 61 * provides a foundational implementation of this contract. 62 * <p> 63 * All client apps must hold a valid URI permission grant to access documents, 64 * typically issued when a user makes a selection through 65 * {@link Intent#ACTION_OPEN_DOCUMENT}, {@link Intent#ACTION_CREATE_DOCUMENT}, 66 * {@link Intent#ACTION_OPEN_DOCUMENT_TREE}, or 67 * {@link StorageVolume#createAccessIntent(String) StorageVolume.createAccessIntent}. 68 * 69 * @see DocumentsProvider 70 */ 71public final class DocumentsContract { 72 private static final String TAG = "DocumentsContract"; 73 74 // content://com.example/root/ 75 // content://com.example/root/sdcard/ 76 // content://com.example/root/sdcard/recent/ 77 // content://com.example/root/sdcard/search/?query=pony 78 // content://com.example/document/12/ 79 // content://com.example/document/12/children/ 80 // content://com.example/tree/12/document/24/ 81 // content://com.example/tree/12/document/24/children/ 82 83 private DocumentsContract() { 84 } 85 86 /** 87 * Intent action used to identify {@link DocumentsProvider} instances. This 88 * is used in the {@code <intent-filter>} of a {@code <provider>}. 89 */ 90 public static final String PROVIDER_INTERFACE = "android.content.action.DOCUMENTS_PROVIDER"; 91 92 /** {@hide} */ 93 public static final String EXTRA_PACKAGE_NAME = "android.content.extra.PACKAGE_NAME"; 94 95 /** {@hide} */ 96 public static final String EXTRA_SHOW_ADVANCED = "android.content.extra.SHOW_ADVANCED"; 97 98 /** {@hide} */ 99 public static final String EXTRA_SHOW_FILESIZE = "android.content.extra.SHOW_FILESIZE"; 100 101 /** {@hide} */ 102 public static final String EXTRA_TARGET_URI = "android.content.extra.TARGET_URI"; 103 104 /** 105 * Set this in a DocumentsUI intent to cause a package's own roots to be 106 * excluded from the roots list. 107 */ 108 public static final String EXTRA_EXCLUDE_SELF = "android.provider.extra.EXCLUDE_SELF"; 109 110 /** 111 * Included in {@link AssetFileDescriptor#getExtras()} when returned 112 * thumbnail should be rotated. 113 * 114 * @see MediaStore.Images.ImageColumns#ORIENTATION 115 * @hide 116 */ 117 public static final String EXTRA_ORIENTATION = "android.content.extra.ORIENTATION"; 118 119 /** 120 * Overrides the default prompt text in DocumentsUI when set in an intent. 121 */ 122 public static final String EXTRA_PROMPT = "android.provider.extra.PROMPT"; 123 124 /** {@hide} */ 125 public static final String ACTION_MANAGE_DOCUMENT = "android.provider.action.MANAGE_DOCUMENT"; 126 127 /** {@hide} */ 128 public static final String ACTION_BROWSE = "android.provider.action.BROWSE"; 129 130 /** {@hide} */ 131 public static final String 132 ACTION_DOCUMENT_ROOT_SETTINGS = "android.provider.action.DOCUMENT_ROOT_SETTINGS"; 133 134 /** 135 * Buffer is large enough to rewind past any EXIF headers. 136 */ 137 private static final int THUMBNAIL_BUFFER_SIZE = (int) (128 * KB_IN_BYTES); 138 139 /** {@hide} */ 140 public static final String PACKAGE_DOCUMENTS_UI = "com.android.documentsui"; 141 142 /** 143 * Constants related to a document, including {@link Cursor} column names 144 * and flags. 145 * <p> 146 * A document can be either an openable stream (with a specific MIME type), 147 * or a directory containing additional documents (with the 148 * {@link #MIME_TYPE_DIR} MIME type). A directory represents the top of a 149 * subtree containing zero or more documents, which can recursively contain 150 * even more documents and directories. 151 * <p> 152 * All columns are <em>read-only</em> to client applications. 153 */ 154 public final static class Document { 155 private Document() { 156 } 157 158 /** 159 * Unique ID of a document. This ID is both provided by and interpreted 160 * by a {@link DocumentsProvider}, and should be treated as an opaque 161 * value by client applications. This column is required. 162 * <p> 163 * Each document must have a unique ID within a provider, but that 164 * single document may be included as a child of multiple directories. 165 * <p> 166 * A provider must always return durable IDs, since they will be used to 167 * issue long-term URI permission grants when an application interacts 168 * with {@link Intent#ACTION_OPEN_DOCUMENT} and 169 * {@link Intent#ACTION_CREATE_DOCUMENT}. 170 * <p> 171 * Type: STRING 172 */ 173 public static final String COLUMN_DOCUMENT_ID = "document_id"; 174 175 /** 176 * Concrete MIME type of a document. For example, "image/png" or 177 * "application/pdf" for openable files. A document can also be a 178 * directory containing additional documents, which is represented with 179 * the {@link #MIME_TYPE_DIR} MIME type. This column is required. 180 * <p> 181 * Type: STRING 182 * 183 * @see #MIME_TYPE_DIR 184 */ 185 public static final String COLUMN_MIME_TYPE = "mime_type"; 186 187 /** 188 * Display name of a document, used as the primary title displayed to a 189 * user. This column is required. 190 * <p> 191 * Type: STRING 192 */ 193 public static final String COLUMN_DISPLAY_NAME = OpenableColumns.DISPLAY_NAME; 194 195 /** 196 * Summary of a document, which may be shown to a user. This column is 197 * optional, and may be {@code null}. 198 * <p> 199 * Type: STRING 200 */ 201 public static final String COLUMN_SUMMARY = "summary"; 202 203 /** 204 * Timestamp when a document was last modified, in milliseconds since 205 * January 1, 1970 00:00:00.0 UTC. This column is required, and may be 206 * {@code null} if unknown. A {@link DocumentsProvider} can update this 207 * field using events from {@link OnCloseListener} or other reliable 208 * {@link ParcelFileDescriptor} transports. 209 * <p> 210 * Type: INTEGER (long) 211 * 212 * @see System#currentTimeMillis() 213 */ 214 public static final String COLUMN_LAST_MODIFIED = "last_modified"; 215 216 /** 217 * Specific icon resource ID for a document. This column is optional, 218 * and may be {@code null} to use a platform-provided default icon based 219 * on {@link #COLUMN_MIME_TYPE}. 220 * <p> 221 * Type: INTEGER (int) 222 */ 223 public static final String COLUMN_ICON = "icon"; 224 225 /** 226 * Flags that apply to a document. This column is required. 227 * <p> 228 * Type: INTEGER (int) 229 * 230 * @see #FLAG_SUPPORTS_WRITE 231 * @see #FLAG_SUPPORTS_DELETE 232 * @see #FLAG_SUPPORTS_THUMBNAIL 233 * @see #FLAG_DIR_PREFERS_GRID 234 * @see #FLAG_DIR_PREFERS_LAST_MODIFIED 235 * @see #FLAG_VIRTUAL_DOCUMENT 236 * @see #FLAG_ARCHIVE 237 * @see #FLAG_SUPPORTS_COPY 238 * @see #FLAG_SUPPORTS_MOVE 239 * @see #FLAG_SUPPORTS_REMOVE 240 */ 241 public static final String COLUMN_FLAGS = "flags"; 242 243 /** 244 * Size of a document, in bytes, or {@code null} if unknown. This column 245 * is required. 246 * <p> 247 * Type: INTEGER (long) 248 */ 249 public static final String COLUMN_SIZE = OpenableColumns.SIZE; 250 251 /** 252 * MIME type of a document which is a directory that may contain 253 * additional documents. 254 * 255 * @see #COLUMN_MIME_TYPE 256 */ 257 public static final String MIME_TYPE_DIR = "vnd.android.document/directory"; 258 259 /** 260 * Flag indicating that a document can be represented as a thumbnail. 261 * 262 * @see #COLUMN_FLAGS 263 * @see DocumentsContract#getDocumentThumbnail(ContentResolver, Uri, 264 * Point, CancellationSignal) 265 * @see DocumentsProvider#openDocumentThumbnail(String, Point, 266 * android.os.CancellationSignal) 267 */ 268 public static final int FLAG_SUPPORTS_THUMBNAIL = 1; 269 270 /** 271 * Flag indicating that a document supports writing. 272 * <p> 273 * When a document is opened with {@link Intent#ACTION_OPEN_DOCUMENT}, 274 * the calling application is granted both 275 * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION} and 276 * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION}. However, the actual 277 * writability of a document may change over time, for example due to 278 * remote access changes. This flag indicates that a document client can 279 * expect {@link ContentResolver#openOutputStream(Uri)} to succeed. 280 * 281 * @see #COLUMN_FLAGS 282 */ 283 public static final int FLAG_SUPPORTS_WRITE = 1 << 1; 284 285 /** 286 * Flag indicating that a document is deletable. 287 * 288 * @see #COLUMN_FLAGS 289 * @see DocumentsContract#deleteDocument(ContentResolver, Uri) 290 * @see DocumentsProvider#deleteDocument(String) 291 */ 292 public static final int FLAG_SUPPORTS_DELETE = 1 << 2; 293 294 /** 295 * Flag indicating that a document is a directory that supports creation 296 * of new files within it. Only valid when {@link #COLUMN_MIME_TYPE} is 297 * {@link #MIME_TYPE_DIR}. 298 * 299 * @see #COLUMN_FLAGS 300 * @see DocumentsProvider#createDocument(String, String, String) 301 */ 302 public static final int FLAG_DIR_SUPPORTS_CREATE = 1 << 3; 303 304 /** 305 * Flag indicating that a directory prefers its contents be shown in a 306 * larger format grid. Usually suitable when a directory contains mostly 307 * pictures. Only valid when {@link #COLUMN_MIME_TYPE} is 308 * {@link #MIME_TYPE_DIR}. 309 * 310 * @see #COLUMN_FLAGS 311 */ 312 public static final int FLAG_DIR_PREFERS_GRID = 1 << 4; 313 314 /** 315 * Flag indicating that a directory prefers its contents be sorted by 316 * {@link #COLUMN_LAST_MODIFIED}. Only valid when 317 * {@link #COLUMN_MIME_TYPE} is {@link #MIME_TYPE_DIR}. 318 * 319 * @see #COLUMN_FLAGS 320 */ 321 public static final int FLAG_DIR_PREFERS_LAST_MODIFIED = 1 << 5; 322 323 /** 324 * Flag indicating that a document can be renamed. 325 * 326 * @see #COLUMN_FLAGS 327 * @see DocumentsContract#renameDocument(ContentProviderClient, Uri, 328 * String) 329 * @see DocumentsProvider#renameDocument(String, String) 330 */ 331 public static final int FLAG_SUPPORTS_RENAME = 1 << 6; 332 333 /** 334 * Flag indicating that a document can be copied to another location 335 * within the same document provider. 336 * 337 * @see #COLUMN_FLAGS 338 * @see DocumentsContract#copyDocument(ContentProviderClient, Uri, Uri) 339 * @see DocumentsProvider#copyDocument(String, String) 340 */ 341 public static final int FLAG_SUPPORTS_COPY = 1 << 7; 342 343 /** 344 * Flag indicating that a document can be moved to another location 345 * within the same document provider. 346 * 347 * @see #COLUMN_FLAGS 348 * @see DocumentsContract#moveDocument(ContentProviderClient, Uri, Uri, Uri) 349 * @see DocumentsProvider#moveDocument(String, String, String) 350 */ 351 public static final int FLAG_SUPPORTS_MOVE = 1 << 8; 352 353 /** 354 * Flag indicating that a document is virtual, and doesn't have byte 355 * representation in the MIME type specified as {@link #COLUMN_MIME_TYPE}. 356 * 357 * @see #COLUMN_FLAGS 358 * @see #COLUMN_MIME_TYPE 359 * @see DocumentsProvider#openTypedDocument(String, String, Bundle, 360 * android.os.CancellationSignal) 361 * @see DocumentsProvider#getDocumentStreamTypes(String, String) 362 */ 363 public static final int FLAG_VIRTUAL_DOCUMENT = 1 << 9; 364 365 /** 366 * Flag indicating that a document can be removed from a parent. 367 * 368 * @see #COLUMN_FLAGS 369 * @see DocumentsContract#removeDocument(ContentProviderClient, Uri, Uri) 370 * @see DocumentsProvider#removeDocument(String, String) 371 */ 372 public static final int FLAG_SUPPORTS_REMOVE = 1 << 10; 373 374 /** 375 * Flag indicating that a document is an archive, and it's contents can be 376 * obtained via {@link DocumentsProvider#queryChildDocuments}. 377 * <p> 378 * The <em>provider</em> support library offers utility classes to add common 379 * archive support. 380 * 381 * @see #COLUMN_FLAGS 382 * @see DocumentsProvider#queryChildDocuments(String, String[], String) 383 * @hide 384 */ 385 public static final int FLAG_ARCHIVE = 1 << 15; 386 387 /** 388 * Flag indicating that a document is not complete, likely its 389 * contents are being downloaded. Partial files cannot be opened, 390 * copied, moved in the UI. But they can be deleted and retried 391 * if they represent a failed download. 392 * 393 * @see #COLUMN_FLAGS 394 * @hide 395 */ 396 public static final int FLAG_PARTIAL = 1 << 16; 397 } 398 399 /** 400 * Constants related to a root of documents, including {@link Cursor} column 401 * names and flags. A root is the start of a tree of documents, such as a 402 * physical storage device, or an account. Each root starts at the directory 403 * referenced by {@link Root#COLUMN_DOCUMENT_ID}, which can recursively 404 * contain both documents and directories. 405 * <p> 406 * All columns are <em>read-only</em> to client applications. 407 */ 408 public final static class Root { 409 private Root() { 410 } 411 412 /** 413 * Unique ID of a root. This ID is both provided by and interpreted by a 414 * {@link DocumentsProvider}, and should be treated as an opaque value 415 * by client applications. This column is required. 416 * <p> 417 * Type: STRING 418 */ 419 public static final String COLUMN_ROOT_ID = "root_id"; 420 421 /** 422 * Flags that apply to a root. This column is required. 423 * <p> 424 * Type: INTEGER (int) 425 * 426 * @see #FLAG_LOCAL_ONLY 427 * @see #FLAG_SUPPORTS_CREATE 428 * @see #FLAG_SUPPORTS_RECENTS 429 * @see #FLAG_SUPPORTS_SEARCH 430 */ 431 public static final String COLUMN_FLAGS = "flags"; 432 433 /** 434 * Icon resource ID for a root. This column is required. 435 * <p> 436 * Type: INTEGER (int) 437 */ 438 public static final String COLUMN_ICON = "icon"; 439 440 /** 441 * Title for a root, which will be shown to a user. This column is 442 * required. For a single storage service surfacing multiple accounts as 443 * different roots, this title should be the name of the service. 444 * <p> 445 * Type: STRING 446 */ 447 public static final String COLUMN_TITLE = "title"; 448 449 /** 450 * Summary for this root, which may be shown to a user. This column is 451 * optional, and may be {@code null}. For a single storage service 452 * surfacing multiple accounts as different roots, this summary should 453 * be the name of the account. 454 * <p> 455 * Type: STRING 456 */ 457 public static final String COLUMN_SUMMARY = "summary"; 458 459 /** 460 * Document which is a directory that represents the top directory of 461 * this root. This column is required. 462 * <p> 463 * Type: STRING 464 * 465 * @see Document#COLUMN_DOCUMENT_ID 466 */ 467 public static final String COLUMN_DOCUMENT_ID = "document_id"; 468 469 /** 470 * Number of bytes available in this root. This column is optional, and 471 * may be {@code null} if unknown or unbounded. 472 * <p> 473 * Type: INTEGER (long) 474 */ 475 public static final String COLUMN_AVAILABLE_BYTES = "available_bytes"; 476 477 /** 478 * Capacity of a root in bytes. This column is optional, and may be 479 * {@code null} if unknown or unbounded. 480 * <p> 481 * Type: INTEGER (long) 482 */ 483 public static final String COLUMN_CAPACITY_BYTES = "capacity_bytes"; 484 485 /** 486 * MIME types supported by this root. This column is optional, and if 487 * {@code null} the root is assumed to support all MIME types. Multiple 488 * MIME types can be separated by a newline. For example, a root 489 * supporting audio might return "audio/*\napplication/x-flac". 490 * <p> 491 * Type: STRING 492 */ 493 public static final String COLUMN_MIME_TYPES = "mime_types"; 494 495 /** {@hide} */ 496 public static final String MIME_TYPE_ITEM = "vnd.android.document/root"; 497 498 /** 499 * Flag indicating that at least one directory under this root supports 500 * creating content. Roots with this flag will be shown when an 501 * application interacts with {@link Intent#ACTION_CREATE_DOCUMENT}. 502 * 503 * @see #COLUMN_FLAGS 504 */ 505 public static final int FLAG_SUPPORTS_CREATE = 1; 506 507 /** 508 * Flag indicating that this root offers content that is strictly local 509 * on the device. That is, no network requests are made for the content. 510 * 511 * @see #COLUMN_FLAGS 512 * @see Intent#EXTRA_LOCAL_ONLY 513 */ 514 public static final int FLAG_LOCAL_ONLY = 1 << 1; 515 516 /** 517 * Flag indicating that this root can be queried to provide recently 518 * modified documents. 519 * 520 * @see #COLUMN_FLAGS 521 * @see DocumentsContract#buildRecentDocumentsUri(String, String) 522 * @see DocumentsProvider#queryRecentDocuments(String, String[]) 523 */ 524 public static final int FLAG_SUPPORTS_RECENTS = 1 << 2; 525 526 /** 527 * Flag indicating that this root supports search. 528 * 529 * @see #COLUMN_FLAGS 530 * @see DocumentsContract#buildSearchDocumentsUri(String, String, 531 * String) 532 * @see DocumentsProvider#querySearchDocuments(String, String, 533 * String[]) 534 */ 535 public static final int FLAG_SUPPORTS_SEARCH = 1 << 3; 536 537 /** 538 * Flag indicating that this root supports testing parent child 539 * relationships. 540 * 541 * @see #COLUMN_FLAGS 542 * @see DocumentsProvider#isChildDocument(String, String) 543 */ 544 public static final int FLAG_SUPPORTS_IS_CHILD = 1 << 4; 545 546 /** 547 * Flag indicating that this root is currently empty. This may be used 548 * to hide the root when opening documents, but the root will still be 549 * shown when creating documents and {@link #FLAG_SUPPORTS_CREATE} is 550 * also set. If the value of this flag changes, such as when a root 551 * becomes non-empty, you must send a content changed notification for 552 * {@link DocumentsContract#buildRootsUri(String)}. 553 * 554 * @see #COLUMN_FLAGS 555 * @see ContentResolver#notifyChange(Uri, 556 * android.database.ContentObserver, boolean) 557 * @hide 558 */ 559 public static final int FLAG_EMPTY = 1 << 16; 560 561 /** 562 * Flag indicating that this root should only be visible to advanced 563 * users. 564 * 565 * @see #COLUMN_FLAGS 566 * @hide 567 */ 568 public static final int FLAG_ADVANCED = 1 << 17; 569 570 /** 571 * Flag indicating that this root has settings. 572 * 573 * @see #COLUMN_FLAGS 574 * @see DocumentsContract#ACTION_DOCUMENT_ROOT_SETTINGS 575 * @hide 576 */ 577 public static final int FLAG_HAS_SETTINGS = 1 << 18; 578 579 /** 580 * Flag indicating that this root is on removable SD card storage. 581 * 582 * @see #COLUMN_FLAGS 583 * @hide 584 */ 585 public static final int FLAG_REMOVABLE_SD = 1 << 19; 586 587 /** 588 * Flag indicating that this root is on removable USB storage. 589 * 590 * @see #COLUMN_FLAGS 591 * @hide 592 */ 593 public static final int FLAG_REMOVABLE_USB = 1 << 20; 594 } 595 596 /** 597 * Optional boolean flag included in a directory {@link Cursor#getExtras()} 598 * indicating that a document provider is still loading data. For example, a 599 * provider has returned some results, but is still waiting on an 600 * outstanding network request. The provider must send a content changed 601 * notification when loading is finished. 602 * 603 * @see ContentResolver#notifyChange(Uri, android.database.ContentObserver, 604 * boolean) 605 */ 606 public static final String EXTRA_LOADING = "loading"; 607 608 /** 609 * Optional string included in a directory {@link Cursor#getExtras()} 610 * providing an informational message that should be shown to a user. For 611 * example, a provider may wish to indicate that not all documents are 612 * available. 613 */ 614 public static final String EXTRA_INFO = "info"; 615 616 /** 617 * Optional string included in a directory {@link Cursor#getExtras()} 618 * providing an error message that should be shown to a user. For example, a 619 * provider may wish to indicate that a network error occurred. The user may 620 * choose to retry, resulting in a new query. 621 */ 622 public static final String EXTRA_ERROR = "error"; 623 624 /** 625 * Optional result (I'm thinking boolean) answer to a question. 626 * {@hide} 627 */ 628 public static final String EXTRA_RESULT = "result"; 629 630 /** {@hide} */ 631 public static final String METHOD_CREATE_DOCUMENT = "android:createDocument"; 632 /** {@hide} */ 633 public static final String METHOD_RENAME_DOCUMENT = "android:renameDocument"; 634 /** {@hide} */ 635 public static final String METHOD_DELETE_DOCUMENT = "android:deleteDocument"; 636 /** {@hide} */ 637 public static final String METHOD_COPY_DOCUMENT = "android:copyDocument"; 638 /** {@hide} */ 639 public static final String METHOD_MOVE_DOCUMENT = "android:moveDocument"; 640 /** {@hide} */ 641 public static final String METHOD_IS_CHILD_DOCUMENT = "android:isChildDocument"; 642 /** {@hide} */ 643 public static final String METHOD_REMOVE_DOCUMENT = "android:removeDocument"; 644 645 /** {@hide} */ 646 public static final String EXTRA_PARENT_URI = "parentUri"; 647 /** {@hide} */ 648 public static final String EXTRA_URI = "uri"; 649 650 private static final String PATH_ROOT = "root"; 651 private static final String PATH_RECENT = "recent"; 652 private static final String PATH_DOCUMENT = "document"; 653 private static final String PATH_CHILDREN = "children"; 654 private static final String PATH_SEARCH = "search"; 655 private static final String PATH_TREE = "tree"; 656 657 private static final String PARAM_QUERY = "query"; 658 private static final String PARAM_MANAGE = "manage"; 659 660 /** 661 * Build URI representing the roots of a document provider. When queried, a 662 * provider will return one or more rows with columns defined by 663 * {@link Root}. 664 * 665 * @see DocumentsProvider#queryRoots(String[]) 666 */ 667 public static Uri buildRootsUri(String authority) { 668 return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT) 669 .authority(authority).appendPath(PATH_ROOT).build(); 670 } 671 672 /** 673 * Build URI representing the given {@link Root#COLUMN_ROOT_ID} in a 674 * document provider. 675 * 676 * @see #getRootId(Uri) 677 */ 678 public static Uri buildRootUri(String authority, String rootId) { 679 return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT) 680 .authority(authority).appendPath(PATH_ROOT).appendPath(rootId).build(); 681 } 682 683 /** 684 * Builds URI for user home directory on external (local) storage. 685 * {@hide} 686 */ 687 public static Uri buildHomeUri() { 688 // TODO: Avoid this type of interpackage copying. Added here to avoid 689 // direct coupling, but not ideal. 690 return DocumentsContract.buildRootUri("com.android.externalstorage.documents", "home"); 691 } 692 693 /** 694 * Build URI representing the recently modified documents of a specific root 695 * in a document provider. When queried, a provider will return zero or more 696 * rows with columns defined by {@link Document}. 697 * 698 * @see DocumentsProvider#queryRecentDocuments(String, String[]) 699 * @see #getRootId(Uri) 700 */ 701 public static Uri buildRecentDocumentsUri(String authority, String rootId) { 702 return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT) 703 .authority(authority).appendPath(PATH_ROOT).appendPath(rootId) 704 .appendPath(PATH_RECENT).build(); 705 } 706 707 /** 708 * Build URI representing access to descendant documents of the given 709 * {@link Document#COLUMN_DOCUMENT_ID}. 710 * 711 * @see #getTreeDocumentId(Uri) 712 */ 713 public static Uri buildTreeDocumentUri(String authority, String documentId) { 714 return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT).authority(authority) 715 .appendPath(PATH_TREE).appendPath(documentId).build(); 716 } 717 718 /** 719 * Build URI representing the target {@link Document#COLUMN_DOCUMENT_ID} in 720 * a document provider. When queried, a provider will return a single row 721 * with columns defined by {@link Document}. 722 * 723 * @see DocumentsProvider#queryDocument(String, String[]) 724 * @see #getDocumentId(Uri) 725 */ 726 public static Uri buildDocumentUri(String authority, String documentId) { 727 return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT) 728 .authority(authority).appendPath(PATH_DOCUMENT).appendPath(documentId).build(); 729 } 730 731 /** 732 * Build URI representing the target {@link Document#COLUMN_DOCUMENT_ID} in 733 * a document provider. When queried, a provider will return a single row 734 * with columns defined by {@link Document}. 735 * <p> 736 * However, instead of directly accessing the target document, the returned 737 * URI will leverage access granted through a subtree URI, typically 738 * returned by {@link Intent#ACTION_OPEN_DOCUMENT_TREE}. The target document 739 * must be a descendant (child, grandchild, etc) of the subtree. 740 * <p> 741 * This is typically used to access documents under a user-selected 742 * directory tree, since it doesn't require the user to separately confirm 743 * each new document access. 744 * 745 * @param treeUri the subtree to leverage to gain access to the target 746 * document. The target directory must be a descendant of this 747 * subtree. 748 * @param documentId the target document, which the caller may not have 749 * direct access to. 750 * @see Intent#ACTION_OPEN_DOCUMENT_TREE 751 * @see DocumentsProvider#isChildDocument(String, String) 752 * @see #buildDocumentUri(String, String) 753 */ 754 public static Uri buildDocumentUriUsingTree(Uri treeUri, String documentId) { 755 return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT) 756 .authority(treeUri.getAuthority()).appendPath(PATH_TREE) 757 .appendPath(getTreeDocumentId(treeUri)).appendPath(PATH_DOCUMENT) 758 .appendPath(documentId).build(); 759 } 760 761 /** {@hide} */ 762 public static Uri buildDocumentUriMaybeUsingTree(Uri baseUri, String documentId) { 763 if (isTreeUri(baseUri)) { 764 return buildDocumentUriUsingTree(baseUri, documentId); 765 } else { 766 return buildDocumentUri(baseUri.getAuthority(), documentId); 767 } 768 } 769 770 /** 771 * Build URI representing the children of the target directory in a document 772 * provider. When queried, a provider will return zero or more rows with 773 * columns defined by {@link Document}. 774 * 775 * @param parentDocumentId the document to return children for, which must 776 * be a directory with MIME type of 777 * {@link Document#MIME_TYPE_DIR}. 778 * @see DocumentsProvider#queryChildDocuments(String, String[], String) 779 * @see #getDocumentId(Uri) 780 */ 781 public static Uri buildChildDocumentsUri(String authority, String parentDocumentId) { 782 return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT).authority(authority) 783 .appendPath(PATH_DOCUMENT).appendPath(parentDocumentId).appendPath(PATH_CHILDREN) 784 .build(); 785 } 786 787 /** 788 * Build URI representing the children of the target directory in a document 789 * provider. When queried, a provider will return zero or more rows with 790 * columns defined by {@link Document}. 791 * <p> 792 * However, instead of directly accessing the target directory, the returned 793 * URI will leverage access granted through a subtree URI, typically 794 * returned by {@link Intent#ACTION_OPEN_DOCUMENT_TREE}. The target 795 * directory must be a descendant (child, grandchild, etc) of the subtree. 796 * <p> 797 * This is typically used to access documents under a user-selected 798 * directory tree, since it doesn't require the user to separately confirm 799 * each new document access. 800 * 801 * @param treeUri the subtree to leverage to gain access to the target 802 * document. The target directory must be a descendant of this 803 * subtree. 804 * @param parentDocumentId the document to return children for, which the 805 * caller may not have direct access to, and which must be a 806 * directory with MIME type of {@link Document#MIME_TYPE_DIR}. 807 * @see Intent#ACTION_OPEN_DOCUMENT_TREE 808 * @see DocumentsProvider#isChildDocument(String, String) 809 * @see #buildChildDocumentsUri(String, String) 810 */ 811 public static Uri buildChildDocumentsUriUsingTree(Uri treeUri, String parentDocumentId) { 812 return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT) 813 .authority(treeUri.getAuthority()).appendPath(PATH_TREE) 814 .appendPath(getTreeDocumentId(treeUri)).appendPath(PATH_DOCUMENT) 815 .appendPath(parentDocumentId).appendPath(PATH_CHILDREN).build(); 816 } 817 818 /** 819 * Build URI representing a search for matching documents under a specific 820 * root in a document provider. When queried, a provider will return zero or 821 * more rows with columns defined by {@link Document}. 822 * 823 * @see DocumentsProvider#querySearchDocuments(String, String, String[]) 824 * @see #getRootId(Uri) 825 * @see #getSearchDocumentsQuery(Uri) 826 */ 827 public static Uri buildSearchDocumentsUri( 828 String authority, String rootId, String query) { 829 return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT).authority(authority) 830 .appendPath(PATH_ROOT).appendPath(rootId).appendPath(PATH_SEARCH) 831 .appendQueryParameter(PARAM_QUERY, query).build(); 832 } 833 834 /** 835 * Test if the given URI represents a {@link Document} backed by a 836 * {@link DocumentsProvider}. 837 * 838 * @see #buildDocumentUri(String, String) 839 * @see #buildDocumentUriUsingTree(Uri, String) 840 */ 841 public static boolean isDocumentUri(Context context, @Nullable Uri uri) { 842 if (isContentUri(uri) && isDocumentsProvider(context, uri.getAuthority())) { 843 final List<String> paths = uri.getPathSegments(); 844 if (paths.size() == 2) { 845 return PATH_DOCUMENT.equals(paths.get(0)); 846 } else if (paths.size() == 4) { 847 return PATH_TREE.equals(paths.get(0)) && PATH_DOCUMENT.equals(paths.get(2)); 848 } 849 } 850 return false; 851 } 852 853 /** {@hide} */ 854 public static boolean isRootUri(Context context, @Nullable Uri uri) { 855 if (isContentUri(uri) && isDocumentsProvider(context, uri.getAuthority())) { 856 final List<String> paths = uri.getPathSegments(); 857 return (paths.size() == 2 && PATH_ROOT.equals(paths.get(0))); 858 } 859 return false; 860 } 861 862 /** {@hide} */ 863 public static boolean isContentUri(@Nullable Uri uri) { 864 return uri != null && ContentResolver.SCHEME_CONTENT.equals(uri.getScheme()); 865 } 866 867 /** 868 * Test if the given URI represents a {@link Document} tree. 869 * 870 * @see #buildTreeDocumentUri(String, String) 871 * @see #getTreeDocumentId(Uri, String) 872 */ 873 public static boolean isTreeUri(Uri uri) { 874 final List<String> paths = uri.getPathSegments(); 875 return (paths.size() >= 2 && PATH_TREE.equals(paths.get(0))); 876 } 877 878 private static boolean isDocumentsProvider(Context context, String authority) { 879 final Intent intent = new Intent(PROVIDER_INTERFACE); 880 final List<ResolveInfo> infos = context.getPackageManager() 881 .queryIntentContentProviders(intent, 0); 882 for (ResolveInfo info : infos) { 883 if (authority.equals(info.providerInfo.authority)) { 884 return true; 885 } 886 } 887 return false; 888 } 889 890 /** 891 * Extract the {@link Root#COLUMN_ROOT_ID} from the given URI. 892 */ 893 public static String getRootId(Uri rootUri) { 894 final List<String> paths = rootUri.getPathSegments(); 895 if (paths.size() >= 2 && PATH_ROOT.equals(paths.get(0))) { 896 return paths.get(1); 897 } 898 throw new IllegalArgumentException("Invalid URI: " + rootUri); 899 } 900 901 /** 902 * Extract the {@link Document#COLUMN_DOCUMENT_ID} from the given URI. 903 * 904 * @see #isDocumentUri(Context, Uri) 905 */ 906 public static String getDocumentId(Uri documentUri) { 907 final List<String> paths = documentUri.getPathSegments(); 908 if (paths.size() >= 2 && PATH_DOCUMENT.equals(paths.get(0))) { 909 return paths.get(1); 910 } 911 if (paths.size() >= 4 && PATH_TREE.equals(paths.get(0)) 912 && PATH_DOCUMENT.equals(paths.get(2))) { 913 return paths.get(3); 914 } 915 throw new IllegalArgumentException("Invalid URI: " + documentUri); 916 } 917 918 /** 919 * Extract the via {@link Document#COLUMN_DOCUMENT_ID} from the given URI. 920 */ 921 public static String getTreeDocumentId(Uri documentUri) { 922 final List<String> paths = documentUri.getPathSegments(); 923 if (paths.size() >= 2 && PATH_TREE.equals(paths.get(0))) { 924 return paths.get(1); 925 } 926 throw new IllegalArgumentException("Invalid URI: " + documentUri); 927 } 928 929 /** 930 * Extract the search query from a URI built by 931 * {@link #buildSearchDocumentsUri(String, String, String)}. 932 */ 933 public static String getSearchDocumentsQuery(Uri searchDocumentsUri) { 934 return searchDocumentsUri.getQueryParameter(PARAM_QUERY); 935 } 936 937 /** {@hide} */ 938 public static Uri setManageMode(Uri uri) { 939 return uri.buildUpon().appendQueryParameter(PARAM_MANAGE, "true").build(); 940 } 941 942 /** {@hide} */ 943 public static boolean isManageMode(Uri uri) { 944 return uri.getBooleanQueryParameter(PARAM_MANAGE, false); 945 } 946 947 /** 948 * Return thumbnail representing the document at the given URI. Callers are 949 * responsible for their own in-memory caching. 950 * 951 * @param documentUri document to return thumbnail for, which must have 952 * {@link Document#FLAG_SUPPORTS_THUMBNAIL} set. 953 * @param size optimal thumbnail size desired. A provider may return a 954 * thumbnail of a different size, but never more than double the 955 * requested size. 956 * @param signal signal used to indicate if caller is no longer interested 957 * in the thumbnail. 958 * @return decoded thumbnail, or {@code null} if problem was encountered. 959 * @see DocumentsProvider#openDocumentThumbnail(String, Point, 960 * android.os.CancellationSignal) 961 */ 962 public static Bitmap getDocumentThumbnail( 963 ContentResolver resolver, Uri documentUri, Point size, CancellationSignal signal) { 964 final ContentProviderClient client = resolver.acquireUnstableContentProviderClient( 965 documentUri.getAuthority()); 966 try { 967 return getDocumentThumbnail(client, documentUri, size, signal); 968 } catch (Exception e) { 969 if (!(e instanceof OperationCanceledException)) { 970 Log.w(TAG, "Failed to load thumbnail for " + documentUri + ": " + e); 971 } 972 return null; 973 } finally { 974 ContentProviderClient.releaseQuietly(client); 975 } 976 } 977 978 /** {@hide} */ 979 public static Bitmap getDocumentThumbnail( 980 ContentProviderClient client, Uri documentUri, Point size, CancellationSignal signal) 981 throws RemoteException, IOException { 982 final Bundle openOpts = new Bundle(); 983 openOpts.putParcelable(ContentResolver.EXTRA_SIZE, size); 984 985 AssetFileDescriptor afd = null; 986 Bitmap bitmap = null; 987 try { 988 afd = client.openTypedAssetFileDescriptor(documentUri, "image/*", openOpts, signal); 989 990 final FileDescriptor fd = afd.getFileDescriptor(); 991 final long offset = afd.getStartOffset(); 992 993 // Try seeking on the returned FD, since it gives us the most 994 // optimal decode path; otherwise fall back to buffering. 995 BufferedInputStream is = null; 996 try { 997 Os.lseek(fd, offset, SEEK_SET); 998 } catch (ErrnoException e) { 999 is = new BufferedInputStream(new FileInputStream(fd), THUMBNAIL_BUFFER_SIZE); 1000 is.mark(THUMBNAIL_BUFFER_SIZE); 1001 } 1002 1003 // We requested a rough thumbnail size, but the remote size may have 1004 // returned something giant, so defensively scale down as needed. 1005 final BitmapFactory.Options opts = new BitmapFactory.Options(); 1006 opts.inJustDecodeBounds = true; 1007 if (is != null) { 1008 BitmapFactory.decodeStream(is, null, opts); 1009 } else { 1010 BitmapFactory.decodeFileDescriptor(fd, null, opts); 1011 } 1012 1013 final int widthSample = opts.outWidth / size.x; 1014 final int heightSample = opts.outHeight / size.y; 1015 1016 opts.inJustDecodeBounds = false; 1017 opts.inSampleSize = Math.min(widthSample, heightSample); 1018 if (is != null) { 1019 is.reset(); 1020 bitmap = BitmapFactory.decodeStream(is, null, opts); 1021 } else { 1022 try { 1023 Os.lseek(fd, offset, SEEK_SET); 1024 } catch (ErrnoException e) { 1025 e.rethrowAsIOException(); 1026 } 1027 bitmap = BitmapFactory.decodeFileDescriptor(fd, null, opts); 1028 } 1029 1030 // Transform the bitmap if requested. We use a side-channel to 1031 // communicate the orientation, since EXIF thumbnails don't contain 1032 // the rotation flags of the original image. 1033 final Bundle extras = afd.getExtras(); 1034 final int orientation = (extras != null) ? extras.getInt(EXTRA_ORIENTATION, 0) : 0; 1035 if (orientation != 0) { 1036 final int width = bitmap.getWidth(); 1037 final int height = bitmap.getHeight(); 1038 1039 final Matrix m = new Matrix(); 1040 m.setRotate(orientation, width / 2, height / 2); 1041 bitmap = Bitmap.createBitmap(bitmap, 0, 0, width, height, m, false); 1042 } 1043 } finally { 1044 IoUtils.closeQuietly(afd); 1045 } 1046 1047 return bitmap; 1048 } 1049 1050 /** 1051 * Create a new document with given MIME type and display name. 1052 * 1053 * @param parentDocumentUri directory with 1054 * {@link Document#FLAG_DIR_SUPPORTS_CREATE} 1055 * @param mimeType MIME type of new document 1056 * @param displayName name of new document 1057 * @return newly created document, or {@code null} if failed 1058 */ 1059 public static Uri createDocument(ContentResolver resolver, Uri parentDocumentUri, 1060 String mimeType, String displayName) { 1061 final ContentProviderClient client = resolver.acquireUnstableContentProviderClient( 1062 parentDocumentUri.getAuthority()); 1063 try { 1064 return createDocument(client, parentDocumentUri, mimeType, displayName); 1065 } catch (Exception e) { 1066 Log.w(TAG, "Failed to create document", e); 1067 return null; 1068 } finally { 1069 ContentProviderClient.releaseQuietly(client); 1070 } 1071 } 1072 1073 /** {@hide} */ 1074 public static Uri createDocument(ContentProviderClient client, Uri parentDocumentUri, 1075 String mimeType, String displayName) throws RemoteException { 1076 final Bundle in = new Bundle(); 1077 in.putParcelable(DocumentsContract.EXTRA_URI, parentDocumentUri); 1078 in.putString(Document.COLUMN_MIME_TYPE, mimeType); 1079 in.putString(Document.COLUMN_DISPLAY_NAME, displayName); 1080 1081 final Bundle out = client.call(METHOD_CREATE_DOCUMENT, null, in); 1082 return out.getParcelable(DocumentsContract.EXTRA_URI); 1083 } 1084 1085 /** {@hide} */ 1086 public static boolean isChildDocument(ContentProviderClient client, Uri parentDocumentUri, 1087 Uri childDocumentUri) throws RemoteException { 1088 1089 final Bundle in = new Bundle(); 1090 in.putParcelable(DocumentsContract.EXTRA_URI, parentDocumentUri); 1091 in.putParcelable(DocumentsContract.EXTRA_TARGET_URI, childDocumentUri); 1092 1093 final Bundle out = client.call(METHOD_IS_CHILD_DOCUMENT, null, in); 1094 if (out == null) { 1095 throw new RemoteException("Failed to get a reponse from isChildDocument query."); 1096 } 1097 if (!out.containsKey(DocumentsContract.EXTRA_RESULT)) { 1098 throw new RemoteException("Response did not include result field.."); 1099 } 1100 return out.getBoolean(DocumentsContract.EXTRA_RESULT); 1101 } 1102 1103 /** 1104 * Change the display name of an existing document. 1105 * <p> 1106 * If the underlying provider needs to create a new 1107 * {@link Document#COLUMN_DOCUMENT_ID} to represent the updated display 1108 * name, that new document is returned and the original document is no 1109 * longer valid. Otherwise, the original document is returned. 1110 * 1111 * @param documentUri document with {@link Document#FLAG_SUPPORTS_RENAME} 1112 * @param displayName updated name for document 1113 * @return the existing or new document after the rename, or {@code null} if 1114 * failed. 1115 */ 1116 public static Uri renameDocument(ContentResolver resolver, Uri documentUri, 1117 String displayName) { 1118 final ContentProviderClient client = resolver.acquireUnstableContentProviderClient( 1119 documentUri.getAuthority()); 1120 try { 1121 return renameDocument(client, documentUri, displayName); 1122 } catch (Exception e) { 1123 Log.w(TAG, "Failed to rename document", e); 1124 return null; 1125 } finally { 1126 ContentProviderClient.releaseQuietly(client); 1127 } 1128 } 1129 1130 /** {@hide} */ 1131 public static Uri renameDocument(ContentProviderClient client, Uri documentUri, 1132 String displayName) throws RemoteException { 1133 final Bundle in = new Bundle(); 1134 in.putParcelable(DocumentsContract.EXTRA_URI, documentUri); 1135 in.putString(Document.COLUMN_DISPLAY_NAME, displayName); 1136 1137 final Bundle out = client.call(METHOD_RENAME_DOCUMENT, null, in); 1138 final Uri outUri = out.getParcelable(DocumentsContract.EXTRA_URI); 1139 return (outUri != null) ? outUri : documentUri; 1140 } 1141 1142 /** 1143 * Delete the given document. 1144 * 1145 * @param documentUri document with {@link Document#FLAG_SUPPORTS_DELETE} 1146 * @return if the document was deleted successfully. 1147 */ 1148 public static boolean deleteDocument(ContentResolver resolver, Uri documentUri) { 1149 final ContentProviderClient client = resolver.acquireUnstableContentProviderClient( 1150 documentUri.getAuthority()); 1151 try { 1152 deleteDocument(client, documentUri); 1153 return true; 1154 } catch (Exception e) { 1155 Log.w(TAG, "Failed to delete document", e); 1156 return false; 1157 } finally { 1158 ContentProviderClient.releaseQuietly(client); 1159 } 1160 } 1161 1162 /** {@hide} */ 1163 public static void deleteDocument(ContentProviderClient client, Uri documentUri) 1164 throws RemoteException { 1165 final Bundle in = new Bundle(); 1166 in.putParcelable(DocumentsContract.EXTRA_URI, documentUri); 1167 1168 client.call(METHOD_DELETE_DOCUMENT, null, in); 1169 } 1170 1171 /** 1172 * Copies the given document. 1173 * 1174 * @param sourceDocumentUri document with {@link Document#FLAG_SUPPORTS_COPY} 1175 * @param targetParentDocumentUri document which will become a parent of the source 1176 * document's copy. 1177 * @return the copied document, or {@code null} if failed. 1178 */ 1179 public static Uri copyDocument(ContentResolver resolver, Uri sourceDocumentUri, 1180 Uri targetParentDocumentUri) { 1181 final ContentProviderClient client = resolver.acquireUnstableContentProviderClient( 1182 sourceDocumentUri.getAuthority()); 1183 try { 1184 return copyDocument(client, sourceDocumentUri, targetParentDocumentUri); 1185 } catch (Exception e) { 1186 Log.w(TAG, "Failed to copy document", e); 1187 return null; 1188 } finally { 1189 ContentProviderClient.releaseQuietly(client); 1190 } 1191 } 1192 1193 /** {@hide} */ 1194 public static Uri copyDocument(ContentProviderClient client, Uri sourceDocumentUri, 1195 Uri targetParentDocumentUri) throws RemoteException { 1196 final Bundle in = new Bundle(); 1197 in.putParcelable(DocumentsContract.EXTRA_URI, sourceDocumentUri); 1198 in.putParcelable(DocumentsContract.EXTRA_TARGET_URI, targetParentDocumentUri); 1199 1200 final Bundle out = client.call(METHOD_COPY_DOCUMENT, null, in); 1201 return out.getParcelable(DocumentsContract.EXTRA_URI); 1202 } 1203 1204 /** 1205 * Moves the given document under a new parent. 1206 * 1207 * @param sourceDocumentUri document with {@link Document#FLAG_SUPPORTS_MOVE} 1208 * @param sourceParentDocumentUri parent document of the document to move. 1209 * @param targetParentDocumentUri document which will become a new parent of the source 1210 * document. 1211 * @return the moved document, or {@code null} if failed. 1212 */ 1213 public static Uri moveDocument(ContentResolver resolver, Uri sourceDocumentUri, 1214 Uri sourceParentDocumentUri, Uri targetParentDocumentUri) { 1215 final ContentProviderClient client = resolver.acquireUnstableContentProviderClient( 1216 sourceDocumentUri.getAuthority()); 1217 try { 1218 return moveDocument(client, sourceDocumentUri, sourceParentDocumentUri, 1219 targetParentDocumentUri); 1220 } catch (Exception e) { 1221 Log.w(TAG, "Failed to move document", e); 1222 return null; 1223 } finally { 1224 ContentProviderClient.releaseQuietly(client); 1225 } 1226 } 1227 1228 /** {@hide} */ 1229 public static Uri moveDocument(ContentProviderClient client, Uri sourceDocumentUri, 1230 Uri sourceParentDocumentUri, Uri targetParentDocumentUri) throws RemoteException { 1231 final Bundle in = new Bundle(); 1232 in.putParcelable(DocumentsContract.EXTRA_URI, sourceDocumentUri); 1233 in.putParcelable(DocumentsContract.EXTRA_PARENT_URI, sourceParentDocumentUri); 1234 in.putParcelable(DocumentsContract.EXTRA_TARGET_URI, targetParentDocumentUri); 1235 1236 final Bundle out = client.call(METHOD_MOVE_DOCUMENT, null, in); 1237 return out.getParcelable(DocumentsContract.EXTRA_URI); 1238 } 1239 1240 /** 1241 * Removes the given document from a parent directory. 1242 * 1243 * <p>In contrast to {@link #deleteDocument} it requires specifying the parent. 1244 * This method is especially useful if the document can be in multiple parents. 1245 * 1246 * @param documentUri document with {@link Document#FLAG_SUPPORTS_REMOVE} 1247 * @param parentDocumentUri parent document of the document to remove. 1248 * @return true if the document was removed successfully. 1249 */ 1250 public static boolean removeDocument(ContentResolver resolver, Uri documentUri, 1251 Uri parentDocumentUri) { 1252 final ContentProviderClient client = resolver.acquireUnstableContentProviderClient( 1253 documentUri.getAuthority()); 1254 try { 1255 removeDocument(client, documentUri, parentDocumentUri); 1256 return true; 1257 } catch (Exception e) { 1258 Log.w(TAG, "Failed to remove document", e); 1259 return false; 1260 } finally { 1261 ContentProviderClient.releaseQuietly(client); 1262 } 1263 } 1264 1265 /** {@hide} */ 1266 public static void removeDocument(ContentProviderClient client, Uri documentUri, 1267 Uri parentDocumentUri) throws RemoteException { 1268 final Bundle in = new Bundle(); 1269 in.putParcelable(DocumentsContract.EXTRA_URI, documentUri); 1270 in.putParcelable(DocumentsContract.EXTRA_PARENT_URI, parentDocumentUri); 1271 1272 client.call(METHOD_REMOVE_DOCUMENT, null, in); 1273 } 1274 1275 /** 1276 * Open the given image for thumbnail purposes, using any embedded EXIF 1277 * thumbnail if available, and providing orientation hints from the parent 1278 * image. 1279 * 1280 * @hide 1281 */ 1282 public static AssetFileDescriptor openImageThumbnail(File file) throws FileNotFoundException { 1283 final ParcelFileDescriptor pfd = ParcelFileDescriptor.open( 1284 file, ParcelFileDescriptor.MODE_READ_ONLY); 1285 Bundle extras = null; 1286 1287 try { 1288 final ExifInterface exif = new ExifInterface(file.getAbsolutePath()); 1289 1290 switch (exif.getAttributeInt(ExifInterface.TAG_ORIENTATION, -1)) { 1291 case ExifInterface.ORIENTATION_ROTATE_90: 1292 extras = new Bundle(1); 1293 extras.putInt(EXTRA_ORIENTATION, 90); 1294 break; 1295 case ExifInterface.ORIENTATION_ROTATE_180: 1296 extras = new Bundle(1); 1297 extras.putInt(EXTRA_ORIENTATION, 180); 1298 break; 1299 case ExifInterface.ORIENTATION_ROTATE_270: 1300 extras = new Bundle(1); 1301 extras.putInt(EXTRA_ORIENTATION, 270); 1302 break; 1303 } 1304 1305 final long[] thumb = exif.getThumbnailRange(); 1306 if (thumb != null) { 1307 return new AssetFileDescriptor(pfd, thumb[0], thumb[1], extras); 1308 } 1309 } catch (IOException e) { 1310 } 1311 1312 return new AssetFileDescriptor(pfd, 0, AssetFileDescriptor.UNKNOWN_LENGTH, extras); 1313 } 1314} 1315