public final class DocumentsContract extends Object
To create a document provider, extend DocumentsProvider
, which
provides a foundational implementation of this contract.
All client apps must hold a valid URI permission grant to access documents,
typically issued when a user makes a selection through
Intent.ACTION_OPEN_DOCUMENT
, Intent.ACTION_CREATE_DOCUMENT
,
Intent.ACTION_OPEN_DOCUMENT_TREE
, or
StorageVolume.createAccessIntent
.
DocumentsProvider
Modifier and Type | Class and Description |
---|---|
static class |
DocumentsContract.Document
Constants related to a document, including
Cursor column names
and flags. |
static class |
DocumentsContract.Root
Constants related to a root of documents, including
Cursor column
names and flags. |
Modifier and Type | Field and Description |
---|---|
static String |
ACTION_BROWSE |
static String |
ACTION_DOCUMENT_ROOT_SETTINGS |
static String |
ACTION_MANAGE_DOCUMENT |
static String |
EXTRA_ERROR
Optional string included in a directory
Cursor.getExtras()
providing an error message that should be shown to a user. |
static String |
EXTRA_EXCLUDE_SELF
Set this in a DocumentsUI intent to cause a package's own roots to be
excluded from the roots list.
|
static String |
EXTRA_FANCY_FEATURES |
static String |
EXTRA_INFO
Optional string included in a directory
Cursor.getExtras()
providing an informational message that should be shown to a user. |
static String |
EXTRA_LOADING
Optional boolean flag included in a directory
Cursor.getExtras()
indicating that a document provider is still loading data. |
static String |
EXTRA_ORIENTATION
Included in
AssetFileDescriptor.getExtras() when returned
thumbnail should be rotated. |
static String |
EXTRA_PACKAGE_NAME |
static String |
EXTRA_PARENT_URI |
static String |
EXTRA_PROMPT
Overrides the default prompt text in DocumentsUI when set in an intent.
|
static String |
EXTRA_RESULT
Optional result (I'm thinking boolean) answer to a question.
|
static String |
EXTRA_SHOW_ADVANCED |
static String |
EXTRA_SHOW_FILESIZE |
static String |
EXTRA_TARGET_URI |
static String |
EXTRA_URI |
static String |
METHOD_COPY_DOCUMENT |
static String |
METHOD_CREATE_DOCUMENT |
static String |
METHOD_DELETE_DOCUMENT |
static String |
METHOD_IS_CHILD_DOCUMENT |
static String |
METHOD_MOVE_DOCUMENT |
static String |
METHOD_REMOVE_DOCUMENT |
static String |
METHOD_RENAME_DOCUMENT |
static String |
PACKAGE_DOCUMENTS_UI |
static String |
PROVIDER_INTERFACE
Intent action used to identify
DocumentsProvider instances. |
Modifier and Type | Method and Description |
---|---|
static Uri |
buildChildDocumentsUri(String authority,
String parentDocumentId)
Build URI representing the children of the target directory in a document
provider.
|
static Uri |
buildChildDocumentsUriUsingTree(Uri treeUri,
String parentDocumentId)
Build URI representing the children of the target directory in a document
provider.
|
static Uri |
buildDocumentUri(String authority,
String documentId)
Build URI representing the target
DocumentsContract.Document.COLUMN_DOCUMENT_ID in
a document provider. |
static Uri |
buildDocumentUriMaybeUsingTree(Uri baseUri,
String documentId) |
static Uri |
buildDocumentUriUsingTree(Uri treeUri,
String documentId)
Build URI representing the target
DocumentsContract.Document.COLUMN_DOCUMENT_ID in
a document provider. |
static Uri |
buildHomeUri()
Builds URI for user home directory on external (local) storage.
|
static Uri |
buildRecentDocumentsUri(String authority,
String rootId)
Build URI representing the recently modified documents of a specific root
in a document provider.
|
static Uri |
buildRootsUri(String authority)
Build URI representing the roots of a document provider.
|
static Uri |
buildRootUri(String authority,
String rootId)
Build URI representing the given
DocumentsContract.Root.COLUMN_ROOT_ID in a
document provider. |
static Uri |
buildSearchDocumentsUri(String authority,
String rootId,
String query)
Build URI representing a search for matching documents under a specific
root in a document provider.
|
static Uri |
buildTreeDocumentUri(String authority,
String documentId)
Build URI representing access to descendant documents of the given
DocumentsContract.Document.COLUMN_DOCUMENT_ID . |
static Uri |
copyDocument(ContentProviderClient client,
Uri sourceDocumentUri,
Uri targetParentDocumentUri) |
static Uri |
copyDocument(ContentResolver resolver,
Uri sourceDocumentUri,
Uri targetParentDocumentUri)
Copies the given document.
|
static Uri |
createDocument(ContentProviderClient client,
Uri parentDocumentUri,
String mimeType,
String displayName) |
static Uri |
createDocument(ContentResolver resolver,
Uri parentDocumentUri,
String mimeType,
String displayName)
Create a new document with given MIME type and display name.
|
static void |
deleteDocument(ContentProviderClient client,
Uri documentUri) |
static boolean |
deleteDocument(ContentResolver resolver,
Uri documentUri)
Delete the given document.
|
static String |
getDocumentId(Uri documentUri)
Extract the
DocumentsContract.Document.COLUMN_DOCUMENT_ID from the given URI. |
static Bitmap |
getDocumentThumbnail(ContentProviderClient client,
Uri documentUri,
Point size,
CancellationSignal signal) |
static Bitmap |
getDocumentThumbnail(ContentResolver resolver,
Uri documentUri,
Point size,
CancellationSignal signal)
Return thumbnail representing the document at the given URI.
|
static String |
getRootId(Uri rootUri)
Extract the
DocumentsContract.Root.COLUMN_ROOT_ID from the given URI. |
static String |
getSearchDocumentsQuery(Uri searchDocumentsUri)
Extract the search query from a URI built by
buildSearchDocumentsUri(String, String, String) . |
static String |
getTreeDocumentId(Uri documentUri)
Extract the via
DocumentsContract.Document.COLUMN_DOCUMENT_ID from the given URI. |
static boolean |
isChildDocument(ContentProviderClient client,
Uri parentDocumentUri,
Uri childDocumentUri) |
static boolean |
isContentUri(Uri uri) |
static boolean |
isDocumentUri(Context context,
Uri uri)
Test if the given URI represents a
DocumentsContract.Document backed by a
DocumentsProvider . |
static boolean |
isManageMode(Uri uri) |
static boolean |
isRootUri(Context context,
Uri uri) |
static boolean |
isTreeUri(Uri uri)
Test if the given URI represents a
DocumentsContract.Document tree. |
static Uri |
moveDocument(ContentProviderClient client,
Uri sourceDocumentUri,
Uri sourceParentDocumentUri,
Uri targetParentDocumentUri) |
static Uri |
moveDocument(ContentResolver resolver,
Uri sourceDocumentUri,
Uri sourceParentDocumentUri,
Uri targetParentDocumentUri)
Moves the given document under a new parent.
|
static AssetFileDescriptor |
openImageThumbnail(File file)
Open the given image for thumbnail purposes, using any embedded EXIF
thumbnail if available, and providing orientation hints from the parent
image.
|
static void |
removeDocument(ContentProviderClient client,
Uri documentUri,
Uri parentDocumentUri) |
static boolean |
removeDocument(ContentResolver resolver,
Uri documentUri,
Uri parentDocumentUri)
Removes the given document from a parent directory.
|
static Uri |
renameDocument(ContentProviderClient client,
Uri documentUri,
String displayName) |
static Uri |
renameDocument(ContentResolver resolver,
Uri documentUri,
String displayName)
Change the display name of an existing document.
|
static Uri |
setManageMode(Uri uri) |
public static final String PROVIDER_INTERFACE
DocumentsProvider
instances. This
is used in the <intent-filter>
of a <provider>
.public static final String EXTRA_PACKAGE_NAME
public static final String EXTRA_SHOW_ADVANCED
public static final String EXTRA_SHOW_FILESIZE
public static final String EXTRA_FANCY_FEATURES
public static final String EXTRA_TARGET_URI
public static final String EXTRA_EXCLUDE_SELF
public static final String EXTRA_ORIENTATION
AssetFileDescriptor.getExtras()
when returned
thumbnail should be rotated.public static final String EXTRA_PROMPT
public static final String ACTION_MANAGE_DOCUMENT
public static final String ACTION_BROWSE
public static final String ACTION_DOCUMENT_ROOT_SETTINGS
public static final String PACKAGE_DOCUMENTS_UI
public static final String EXTRA_LOADING
Cursor.getExtras()
indicating that a document provider is still loading data. For example, a
provider has returned some results, but is still waiting on an
outstanding network request. The provider must send a content changed
notification when loading is finished.public static final String EXTRA_INFO
Cursor.getExtras()
providing an informational message that should be shown to a user. For
example, a provider may wish to indicate that not all documents are
available.public static final String EXTRA_ERROR
Cursor.getExtras()
providing an error message that should be shown to a user. For example, a
provider may wish to indicate that a network error occurred. The user may
choose to retry, resulting in a new query.public static final String EXTRA_RESULT
public static final String METHOD_CREATE_DOCUMENT
public static final String METHOD_RENAME_DOCUMENT
public static final String METHOD_DELETE_DOCUMENT
public static final String METHOD_COPY_DOCUMENT
public static final String METHOD_MOVE_DOCUMENT
public static final String METHOD_IS_CHILD_DOCUMENT
public static final String METHOD_REMOVE_DOCUMENT
public static final String EXTRA_PARENT_URI
public static final String EXTRA_URI
public static Uri buildRootsUri(String authority)
DocumentsContract.Root
.DocumentsProvider.queryRoots(String[])
public static Uri buildRootUri(String authority, String rootId)
DocumentsContract.Root.COLUMN_ROOT_ID
in a
document provider.getRootId(Uri)
public static Uri buildHomeUri()
public static Uri buildRecentDocumentsUri(String authority, String rootId)
DocumentsContract.Document
.public static Uri buildTreeDocumentUri(String authority, String documentId)
DocumentsContract.Document.COLUMN_DOCUMENT_ID
.getTreeDocumentId(Uri)
public static Uri buildDocumentUri(String authority, String documentId)
DocumentsContract.Document.COLUMN_DOCUMENT_ID
in
a document provider. When queried, a provider will return a single row
with columns defined by DocumentsContract.Document
.public static Uri buildDocumentUriUsingTree(Uri treeUri, String documentId)
DocumentsContract.Document.COLUMN_DOCUMENT_ID
in
a document provider. When queried, a provider will return a single row
with columns defined by DocumentsContract.Document
.
However, instead of directly accessing the target document, the returned
URI will leverage access granted through a subtree URI, typically
returned by Intent.ACTION_OPEN_DOCUMENT_TREE
. The target document
must be a descendant (child, grandchild, etc) of the subtree.
This is typically used to access documents under a user-selected directory tree, since it doesn't require the user to separately confirm each new document access.
treeUri
- the subtree to leverage to gain access to the target
document. The target directory must be a descendant of this
subtree.documentId
- the target document, which the caller may not have
direct access to.Intent.ACTION_OPEN_DOCUMENT_TREE
,
DocumentsProvider.isChildDocument(String, String)
,
buildDocumentUri(String, String)
public static Uri buildDocumentUriMaybeUsingTree(Uri baseUri, String documentId)
public static Uri buildChildDocumentsUri(String authority, String parentDocumentId)
DocumentsContract.Document
.parentDocumentId
- the document to return children for, which must
be a directory with MIME type of
DocumentsContract.Document.MIME_TYPE_DIR
.DocumentsProvider.queryChildDocuments(String, String[], String)
,
getDocumentId(Uri)
public static Uri buildChildDocumentsUriUsingTree(Uri treeUri, String parentDocumentId)
DocumentsContract.Document
.
However, instead of directly accessing the target directory, the returned
URI will leverage access granted through a subtree URI, typically
returned by Intent.ACTION_OPEN_DOCUMENT_TREE
. The target
directory must be a descendant (child, grandchild, etc) of the subtree.
This is typically used to access documents under a user-selected directory tree, since it doesn't require the user to separately confirm each new document access.
treeUri
- the subtree to leverage to gain access to the target
document. The target directory must be a descendant of this
subtree.parentDocumentId
- the document to return children for, which the
caller may not have direct access to, and which must be a
directory with MIME type of DocumentsContract.Document.MIME_TYPE_DIR
.Intent.ACTION_OPEN_DOCUMENT_TREE
,
DocumentsProvider.isChildDocument(String, String)
,
buildChildDocumentsUri(String, String)
public static Uri buildSearchDocumentsUri(String authority, String rootId, String query)
DocumentsContract.Document
.public static boolean isDocumentUri(Context context, Uri uri)
DocumentsContract.Document
backed by a
DocumentsProvider
.public static boolean isContentUri(Uri uri)
public static boolean isTreeUri(Uri uri)
DocumentsContract.Document
tree.public static String getRootId(Uri rootUri)
DocumentsContract.Root.COLUMN_ROOT_ID
from the given URI.public static String getDocumentId(Uri documentUri)
DocumentsContract.Document.COLUMN_DOCUMENT_ID
from the given URI.isDocumentUri(Context, Uri)
public static String getTreeDocumentId(Uri documentUri)
DocumentsContract.Document.COLUMN_DOCUMENT_ID
from the given URI.public static String getSearchDocumentsQuery(Uri searchDocumentsUri)
buildSearchDocumentsUri(String, String, String)
.public static boolean isManageMode(Uri uri)
public static Bitmap getDocumentThumbnail(ContentResolver resolver, Uri documentUri, Point size, CancellationSignal signal)
documentUri
- document to return thumbnail for, which must have
DocumentsContract.Document.FLAG_SUPPORTS_THUMBNAIL
set.size
- optimal thumbnail size desired. A provider may return a
thumbnail of a different size, but never more than double the
requested size.signal
- signal used to indicate if caller is no longer interested
in the thumbnail.null
if problem was encountered.DocumentsProvider.openDocumentThumbnail(String, Point,
android.os.CancellationSignal)
public static Bitmap getDocumentThumbnail(ContentProviderClient client, Uri documentUri, Point size, CancellationSignal signal) throws RemoteException, IOException
RemoteException
IOException
public static Uri createDocument(ContentResolver resolver, Uri parentDocumentUri, String mimeType, String displayName)
parentDocumentUri
- directory with
DocumentsContract.Document.FLAG_DIR_SUPPORTS_CREATE
mimeType
- MIME type of new documentdisplayName
- name of new documentnull
if failedpublic static Uri createDocument(ContentProviderClient client, Uri parentDocumentUri, String mimeType, String displayName) throws RemoteException
RemoteException
public static boolean isChildDocument(ContentProviderClient client, Uri parentDocumentUri, Uri childDocumentUri) throws RemoteException
RemoteException
public static Uri renameDocument(ContentResolver resolver, Uri documentUri, String displayName)
If the underlying provider needs to create a new
DocumentsContract.Document.COLUMN_DOCUMENT_ID
to represent the updated display
name, that new document is returned and the original document is no
longer valid. Otherwise, the original document is returned.
documentUri
- document with DocumentsContract.Document.FLAG_SUPPORTS_RENAME
displayName
- updated name for documentnull
if
failed.public static Uri renameDocument(ContentProviderClient client, Uri documentUri, String displayName) throws RemoteException
RemoteException
public static boolean deleteDocument(ContentResolver resolver, Uri documentUri)
documentUri
- document with DocumentsContract.Document.FLAG_SUPPORTS_DELETE
public static void deleteDocument(ContentProviderClient client, Uri documentUri) throws RemoteException
RemoteException
public static Uri copyDocument(ContentResolver resolver, Uri sourceDocumentUri, Uri targetParentDocumentUri)
sourceDocumentUri
- document with DocumentsContract.Document.FLAG_SUPPORTS_COPY
targetParentDocumentUri
- document which will become a parent of the source
document's copy.null
if failed.public static Uri copyDocument(ContentProviderClient client, Uri sourceDocumentUri, Uri targetParentDocumentUri) throws RemoteException
RemoteException
public static Uri moveDocument(ContentResolver resolver, Uri sourceDocumentUri, Uri sourceParentDocumentUri, Uri targetParentDocumentUri)
sourceDocumentUri
- document with DocumentsContract.Document.FLAG_SUPPORTS_MOVE
sourceParentDocumentUri
- parent document of the document to move.targetParentDocumentUri
- document which will become a new parent of the source
document.null
if failed.public static Uri moveDocument(ContentProviderClient client, Uri sourceDocumentUri, Uri sourceParentDocumentUri, Uri targetParentDocumentUri) throws RemoteException
RemoteException
public static boolean removeDocument(ContentResolver resolver, Uri documentUri, Uri parentDocumentUri)
In contrast to deleteDocument(android.content.ContentResolver, android.net.Uri)
it requires specifying the parent.
This method is especially useful if the document can be in multiple parents.
documentUri
- document with DocumentsContract.Document.FLAG_SUPPORTS_REMOVE
parentDocumentUri
- parent document of the document to remove.public static void removeDocument(ContentProviderClient client, Uri documentUri, Uri parentDocumentUri) throws RemoteException
RemoteException
public static AssetFileDescriptor openImageThumbnail(File file) throws FileNotFoundException
FileNotFoundException