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