DocumentsContract
class DocumentsContract
kotlin.Any | |
↳ | android.provider.DocumentsContract |
Defines the contract between a documents provider and the platform.
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
, or Intent#ACTION_OPEN_DOCUMENT_TREE
.
Summary
Nested classes | |
---|---|
Constants related to a document, including |
|
Holds a path from a document to a particular document under it. |
|
Constants related to a root of documents, including |
Constants | |
---|---|
static String |
Action of intent issued by DocumentsUI when user wishes to open/configure/manage a particular document in the provider application. |
static String |
Optional string included in a directory |
static String |
Set this in a DocumentsUI intent to cause a package's own roots to be excluded from the roots list. |
static String |
Optional string included in a directory |
static String |
Sets the desired initial location visible to user when file chooser is shown. |
static String |
Optional boolean flag included in a directory |
static String |
An extra number of degrees that an image should be rotated during the decode process to be presented correctly. |
static String |
Overrides the default prompt text in DocumentsUI when set in an intent. |
static String |
Get Exif information using DocumentsContract#getDocumentMetadata. |
static String |
Get total count of all documents currently stored under the given directory tree. |
static String |
Get total size of all documents currently stored under the given directory tree. |
static String |
Get string array identifies the type or types of metadata returned using DocumentsContract#getDocumentMetadata. |
static String |
Intent action used to identify |
static String |
Key for |
static String |
Key for |
static String |
Key for |
static String |
Key for |
static String |
Key for |
Public methods | |
---|---|
static Uri! |
buildChildDocumentsUri(authority: String!, parentDocumentId: String!) Build URI representing the children of the target directory in a document provider. |
static Uri! |
buildChildDocumentsUriUsingTree(treeUri: Uri!, parentDocumentId: String!) Build URI representing the children of the target directory in a document provider. |
static Uri! |
buildDocumentUri(authority: String!, documentId: String!) Build URI representing the target |
static Uri! |
buildDocumentUriUsingTree(treeUri: Uri!, documentId: String!) Build URI representing the target |
static Uri! |
buildRecentDocumentsUri(authority: String!, rootId: String!) Build URI representing the recently modified documents of a specific root in a document provider. |
static Uri! |
buildRootUri(authority: String!, rootId: String!) Build URI representing the given |
static Uri! |
buildRootsUri(authority: String!) Build URI representing the roots of a document provider. |
static Uri! |
buildSearchDocumentsUri(authority: String!, rootId: String!, query: String!) Build URI representing a search for matching documents under a specific root in a document provider. |
static Uri! |
buildTreeDocumentUri(authority: String!, documentId: String!) Build URI representing access to descendant documents of the given |
static Uri? |
copyDocument(content: ContentResolver, sourceDocumentUri: Uri, targetParentDocumentUri: Uri) Copies the given document. |
static Uri? |
createDocument(content: ContentResolver, parentDocumentUri: Uri, mimeType: String, displayName: String) Create a new document with given MIME type and display name. |
static IntentSender? |
createWebLinkIntent(content: ContentResolver, uri: Uri, options: Bundle?) Creates an intent for obtaining a web link for the specified document. |
static Boolean |
deleteDocument(content: ContentResolver, documentUri: Uri) Delete the given document. |
static Unit |
ejectRoot(content: ContentResolver, rootUri: Uri) Ejects the given root. |
static DocumentsContract.Path? |
findDocumentPath(content: ContentResolver, treeUri: Uri) Finds the canonical path from the top of the document tree. |
static String! |
getDocumentId(documentUri: Uri!) Extract the |
static Bundle? |
getDocumentMetadata(content: ContentResolver, documentUri: Uri) Returns metadata associated with the document. |
static Bitmap? |
getDocumentThumbnail(content: ContentResolver, documentUri: Uri, size: Point, signal: CancellationSignal?) Return thumbnail representing the document at the given URI. |
static String! |
Extract the |
static String! |
getSearchDocumentsQuery(searchDocumentsUri: Uri!) Extract the search query from a URI built by |
static String! |
getTreeDocumentId(documentUri: Uri!) Extract the via |
static Boolean |
isChildDocument(content: ContentResolver, parentDocumentUri: Uri, childDocumentUri: Uri) Test if a document is descendant (child, grandchild, etc) from the given parent. |
static Boolean |
isDocumentUri(context: Context!, uri: Uri?) Test if the given URI represents a |
static Boolean |
Test if the given URI represents specific root backed by |
static Boolean |
isRootsUri(context: Context, uri: Uri?) Test if the given URI represents all roots of the authority backed by |
static Boolean |
Test if the given URI represents a |
static Uri? |
moveDocument(content: ContentResolver, sourceDocumentUri: Uri, sourceParentDocumentUri: Uri, targetParentDocumentUri: Uri) Moves the given document under a new parent. |
static Boolean |
removeDocument(content: ContentResolver, documentUri: Uri, parentDocumentUri: Uri) Removes the given document from a parent directory. |
static Uri? |
renameDocument(content: ContentResolver, documentUri: Uri, displayName: String) Change the display name of an existing document. |
Constants
ACTION_DOCUMENT_SETTINGS
static val ACTION_DOCUMENT_SETTINGS: String
Action of intent issued by DocumentsUI when user wishes to open/configure/manage a particular document in the provider application.
When issued, the intent will include the URI of the document as the intent data.
A provider wishing to provide support for this action should do two things.
<intent-filter>
matching this action. Document#FLAG_SUPPORTS_SETTINGS
in the flags for each document that supports settings.Value: "android.provider.action.DOCUMENT_SETTINGS"
EXTRA_ERROR
static val EXTRA_ERROR: String
Optional string included in a directory 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.
Value: "error"
EXTRA_EXCLUDE_SELF
static val EXTRA_EXCLUDE_SELF: String
Set this in a DocumentsUI intent to cause a package's own roots to be excluded from the roots list.
Value: "android.provider.extra.EXCLUDE_SELF"
EXTRA_INFO
static val EXTRA_INFO: String
Optional string included in a directory 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.
Value: "info"
EXTRA_INITIAL_URI
static val EXTRA_INITIAL_URI: String
Sets the desired initial location visible to user when file chooser is shown.
Applicable to Intent
with actions:
Location should specify a document URI or a tree URI with document ID. If this URI identifies a non-directory, document navigator will attempt to use the parent of the document as the initial location.
The initial location is system specific if this extra is missing or document navigator failed to locate the desired initial location.
Value: "android.provider.extra.INITIAL_URI"
EXTRA_LOADING
static val EXTRA_LOADING: String
Optional boolean flag included in a directory 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.
Value: "loading"
EXTRA_ORIENTATION
static val EXTRA_ORIENTATION: String
An extra number of degrees that an image should be rotated during the decode process to be presented correctly.
Value: "android.provider.extra.ORIENTATION"
EXTRA_PROMPT
static val EXTRA_PROMPT: String
Overrides the default prompt text in DocumentsUI when set in an intent.
Value: "android.provider.extra.PROMPT"
METADATA_EXIF
static val METADATA_EXIF: String
Get Exif information using DocumentsContract#getDocumentMetadata.
Value: "android:documentExif"
METADATA_TREE_COUNT
static val METADATA_TREE_COUNT: String
Get total count of all documents currently stored under the given directory tree. Only valid for Document#MIME_TYPE_DIR
documents.
Value: "android:metadataTreeCount"
METADATA_TREE_SIZE
static val METADATA_TREE_SIZE: String
Get total size of all documents currently stored under the given directory tree. Only valid for Document#MIME_TYPE_DIR
documents.
Value: "android:metadataTreeSize"
METADATA_TYPES
static val METADATA_TYPES: String
Get string array identifies the type or types of metadata returned using DocumentsContract#getDocumentMetadata.
Value: "android:documentMetadataTypes"
PROVIDER_INTERFACE
static val PROVIDER_INTERFACE: String
Intent action used to identify DocumentsProvider
instances. This is used in the <intent-filter>
of a <provider>
.
Value: "android.content.action.DOCUMENTS_PROVIDER"
QUERY_ARG_DISPLAY_NAME
static val QUERY_ARG_DISPLAY_NAME: String
Key for DocumentsProvider
to query display name is matched. The match of display name is partial matching and case-insensitive. Ex: The value is "o", the display name of the results will contain both "foo" and "Open".
Value: "android:query-arg-display-name"
QUERY_ARG_EXCLUDE_MEDIA
static val QUERY_ARG_EXCLUDE_MEDIA: String
Key for DocumentsProvider
to decide whether the files that have been added to MediaStore should be excluded. If the value is true, exclude them. Otherwise, include them.
Value: "android:query-arg-exclude-media"
QUERY_ARG_FILE_SIZE_OVER
static val QUERY_ARG_FILE_SIZE_OVER: String
Key for DocumentsProvider
to query the file size in bytes is larger than the value.
Value: "android:query-arg-file-size-over"
QUERY_ARG_LAST_MODIFIED_AFTER
static val QUERY_ARG_LAST_MODIFIED_AFTER: String
Key for DocumentsProvider
to query the last modified time is newer than the value. The unit is in milliseconds since January 1, 1970 00:00:00.0 UTC.
Value: "android:query-arg-last-modified-after"
QUERY_ARG_MIME_TYPES
static val QUERY_ARG_MIME_TYPES: String
Key for DocumentsProvider
to query mime types is matched. The value is a string array, it can support different mime types. Each items will be treated as "OR" condition. Ex: {"image/*" , "video/*"}. The mime types of the results will contain both image type and video type.
Value: "android:query-arg-mime-types"
Public methods
buildChildDocumentsUri
static fun buildChildDocumentsUri(
authority: String!,
parentDocumentId: String!
): Uri!
Build URI representing the children of the target directory in a document provider. When queried, a provider will return zero or more rows with columns defined by Document
.
Parameters | |
---|---|
parentDocumentId |
String!: the document to return children for, which must be a directory with MIME type of Document#MIME_TYPE_DIR . |
buildChildDocumentsUriUsingTree
static fun buildChildDocumentsUriUsingTree(
treeUri: Uri!,
parentDocumentId: String!
): Uri!
Build URI representing the children of the target directory in a document provider. When queried, a provider will return zero or more rows with columns defined by 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.
Parameters | |
---|---|
treeUri |
Uri!: the subtree to leverage to gain access to the target document. The target directory must be a descendant of this subtree. |
parentDocumentId |
String!: 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 Document#MIME_TYPE_DIR . |
buildDocumentUri
static fun buildDocumentUri(
authority: String!,
documentId: String!
): Uri!
Build URI representing the target Document#COLUMN_DOCUMENT_ID
in a document provider. When queried, a provider will return a single row with columns defined by Document
.
buildDocumentUriUsingTree
static fun buildDocumentUriUsingTree(
treeUri: Uri!,
documentId: String!
): Uri!
Build URI representing the target Document#COLUMN_DOCUMENT_ID
in a document provider. When queried, a provider will return a single row with columns defined by 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.
Parameters | |
---|---|
treeUri |
Uri!: the subtree to leverage to gain access to the target document. The target directory must be a descendant of this subtree. |
documentId |
String!: the target document, which the caller may not have direct access to. |
buildRecentDocumentsUri
static fun buildRecentDocumentsUri(
authority: String!,
rootId: String!
): Uri!
Build URI representing the recently modified documents of a specific root in a document provider. When queried, a provider will return zero or more rows with columns defined by Document
.
buildRootUri
static fun buildRootUri(
authority: String!,
rootId: String!
): Uri!
Build URI representing the given Root#COLUMN_ROOT_ID
in a document provider.
See Also
buildRootsUri
static fun buildRootsUri(authority: String!): Uri!
Build URI representing the roots of a document provider. When queried, a provider will return one or more rows with columns defined by Root
.
buildSearchDocumentsUri
static fun buildSearchDocumentsUri(
authority: String!,
rootId: String!,
query: String!
): Uri!
Build URI representing a search for matching documents under a specific root in a document provider. When queried, a provider will return zero or more rows with columns defined by Document
.
buildTreeDocumentUri
static fun buildTreeDocumentUri(
authority: String!,
documentId: String!
): Uri!
Build URI representing access to descendant documents of the given Document#COLUMN_DOCUMENT_ID
.
See Also
copyDocument
static fun copyDocument(
content: ContentResolver,
sourceDocumentUri: Uri,
targetParentDocumentUri: Uri
): Uri?
Copies the given document.
Parameters | |
---|---|
sourceDocumentUri |
Uri: document with Document#FLAG_SUPPORTS_COPY This value cannot be null . |
targetParentDocumentUri |
Uri: document which will become a parent of the source document's copy. This value cannot be null . |
content |
ContentResolver: This value cannot be null . |
Return | |
---|---|
Uri? |
the copied document, or null if failed. |
createDocument
static fun createDocument(
content: ContentResolver,
parentDocumentUri: Uri,
mimeType: String,
displayName: String
): Uri?
Create a new document with given MIME type and display name.
Parameters | |
---|---|
parentDocumentUri |
Uri: directory with Document#FLAG_DIR_SUPPORTS_CREATE This value cannot be null . |
mimeType |
String: MIME type of new document This value cannot be null . |
displayName |
String: name of new document This value cannot be null . |
content |
ContentResolver: This value cannot be null . |
Return | |
---|---|
Uri? |
newly created document, or null if failed |
createWebLinkIntent
static fun createWebLinkIntent(
content: ContentResolver,
uri: Uri,
options: Bundle?
): IntentSender?
Creates an intent for obtaining a web link for the specified document.
Note, that due to internal limitations, if there is already a web link intent created for the specified document but with different options, then it may be overridden.
Providers are required to show confirmation UI for all new permissions granted for the linked document.
If list of recipients is known, then it should be passed in options as Intent#EXTRA_EMAIL
as a list of email addresses. Note, that this is just a hint for the provider, which can ignore the list. In either case the provider is required to show a UI for letting the user confirm any new permission grants.
Note, that the entire options
bundle will be sent to the provider backing the passed uri
. Make sure that you trust the provider before passing any sensitive information.
Since this API may show a UI, it cannot be called from background.
In order to obtain the Web Link use code like this:
<code> void onSomethingHappened() { IntentSender sender = DocumentsContract.createWebLinkIntent(<i>...</i>); if (sender != null) { startIntentSenderForResult( sender, WEB_LINK_REQUEST_CODE, null, 0, 0, 0, null); } } <i>(...)</i> void onActivityResult(int requestCode, int resultCode, Intent data) { if (requestCode == WEB_LINK_REQUEST_CODE && resultCode == RESULT_OK) { Uri weblinkUri = data.getData(); <i>...</i> } } </code>
Parameters | |
---|---|
uri |
Uri: uri for the document to create a link to. This value cannot be null . |
options |
Bundle?: Extra information for generating the link. This value may be null . |
content |
ContentResolver: This value cannot be null . |
Return | |
---|---|
IntentSender? |
an intent sender to obtain the web link, or null if the document is not linkable, or creating the intent sender failed. |
deleteDocument
static fun deleteDocument(
content: ContentResolver,
documentUri: Uri
): Boolean
Delete the given document.
Parameters | |
---|---|
documentUri |
Uri: document with Document#FLAG_SUPPORTS_DELETE This value cannot be null . |
content |
ContentResolver: This value cannot be null . |
Return | |
---|---|
Boolean |
if the document was deleted successfully. |
ejectRoot
static fun ejectRoot(
content: ContentResolver,
rootUri: Uri
): Unit
Ejects the given root. It throws IllegalStateException
when ejection failed.
Parameters | |
---|---|
rootUri |
Uri: root with Root#FLAG_SUPPORTS_EJECT to be ejected This value cannot be null . |
content |
ContentResolver: This value cannot be null . |
findDocumentPath
static fun findDocumentPath(
content: ContentResolver,
treeUri: Uri
): DocumentsContract.Path?
Finds the canonical path from the top of the document tree. The Path#getPath()
of the return value contains the document ID of all documents along the path from the top the document tree to the requested document, both inclusive. The Path#getRootId()
of the return value returns null
.
Parameters | |
---|---|
treeUri |
Uri: treeUri of the document which path is requested. This value cannot be null . |
content |
ContentResolver: This value cannot be null . |
Return | |
---|---|
DocumentsContract.Path? |
the path of the document, or null if failed. |
getDocumentId
static fun getDocumentId(documentUri: Uri!): String!
Extract the Document#COLUMN_DOCUMENT_ID
from the given URI.
See Also
getDocumentMetadata
static fun getDocumentMetadata(
content: ContentResolver,
documentUri: Uri
): Bundle?
Returns metadata associated with the document. The type of metadata returned is specific to the document type. For example the data returned for an image file will likely consist primarily or solely of EXIF metadata.
The returned Bundle
will contain zero or more entries depending on the type of data supported by the document provider.
- A
DocumentsContract#METADATA_TYPES
containing aString[]
value. The string array identifies the type or types of metadata returned. Each value in the can be used to access aBundle
of data containing that type of data. - An entry each for each type of returned metadata. Each set of metadata is itself represented as a bundle and accessible via a string key naming the type of data.
Example:
<code> Bundle metadata = DocumentsContract.getDocumentMetadata(client, imageDocUri, tags); if (metadata.containsKey(DocumentsContract.METADATA_EXIF)) { Bundle exif = metadata.getBundle(DocumentsContract.METADATA_EXIF); int imageLength = exif.getInt(ExifInterface.TAG_IMAGE_LENGTH); } </code>
Parameters | |
---|---|
documentUri |
Uri: a Document URI This value cannot be null . |
content |
ContentResolver: This value cannot be null . |
Return | |
---|---|
Bundle? |
a Bundle of Bundles. This value may be null . |
getDocumentThumbnail
static fun getDocumentThumbnail(
content: ContentResolver,
documentUri: Uri,
size: Point,
signal: CancellationSignal?
): Bitmap?
Return thumbnail representing the document at the given URI. Callers are responsible for their own in-memory caching.
Parameters | |
---|---|
documentUri |
Uri: document to return thumbnail for, which must have Document#FLAG_SUPPORTS_THUMBNAIL set. This value cannot be null . |
size |
Point: optimal thumbnail size desired. A provider may return a thumbnail of a different size, but never more than double the requested size. This value cannot be null . |
signal |
CancellationSignal?: signal used to indicate if caller is no longer interested in the thumbnail. This value may be null . |
content |
ContentResolver: This value cannot be null . |
Return | |
---|---|
Bitmap? |
decoded thumbnail, or null if problem was encountered. |
getRootId
static fun getRootId(rootUri: Uri!): String!
Extract the Root#COLUMN_ROOT_ID
from the given URI.
getSearchDocumentsQuery
static fun getSearchDocumentsQuery(searchDocumentsUri: Uri!): String!
Extract the search query from a URI built by buildSearchDocumentsUri(java.lang.String,java.lang.String,java.lang.String)
.
getTreeDocumentId
static fun getTreeDocumentId(documentUri: Uri!): String!
Extract the via Document#COLUMN_DOCUMENT_ID
from the given URI.
isChildDocument
static fun isChildDocument(
content: ContentResolver,
parentDocumentUri: Uri,
childDocumentUri: Uri
): Boolean
Test if a document is descendant (child, grandchild, etc) from the given parent.
Parameters | |
---|---|
parentDocumentUri |
Uri: parent to verify against. This value cannot be null . |
childDocumentUri |
Uri: child to verify. This value cannot be null . |
content |
ContentResolver: This value cannot be null . |
Return | |
---|---|
Boolean |
if given document is a descendant of the given parent. |
isDocumentUri
static fun isDocumentUri(
context: Context!,
uri: Uri?
): Boolean
Test if the given URI represents a Document
backed by a DocumentsProvider
.
Parameters | |
---|---|
uri |
Uri?: This value may be null . |
isRootUri
static fun isRootUri(
context: Context,
uri: Uri?
): Boolean
Test if the given URI represents specific root backed by DocumentsProvider
.
Parameters | |
---|---|
context |
Context: This value cannot be null . |
uri |
Uri?: This value may be null . |
See Also
isRootsUri
static fun isRootsUri(
context: Context,
uri: Uri?
): Boolean
Test if the given URI represents all roots of the authority backed by DocumentsProvider
.
Parameters | |
---|---|
context |
Context: This value cannot be null . |
uri |
Uri?: This value may be null . |
See Also
isTreeUri
static fun isTreeUri(uri: Uri!): Boolean
Test if the given URI represents a Document
tree.
moveDocument
static fun moveDocument(
content: ContentResolver,
sourceDocumentUri: Uri,
sourceParentDocumentUri: Uri,
targetParentDocumentUri: Uri
): Uri?
Moves the given document under a new parent.
Parameters | |
---|---|
sourceDocumentUri |
Uri: document with Document#FLAG_SUPPORTS_MOVE This value cannot be null . |
sourceParentDocumentUri |
Uri: parent document of the document to move. This value cannot be null . |
targetParentDocumentUri |
Uri: document which will become a new parent of the source document. This value cannot be null . |
content |
ContentResolver: This value cannot be null . |
Return | |
---|---|
Uri? |
the moved document, or null if failed. |
removeDocument
static fun removeDocument(
content: ContentResolver,
documentUri: Uri,
parentDocumentUri: Uri
): Boolean
Removes the given document from a parent directory.
In contrast to deleteDocument
it requires specifying the parent. This method is especially useful if the document can be in multiple parents.
Parameters | |
---|---|
documentUri |
Uri: document with Document#FLAG_SUPPORTS_REMOVE This value cannot be null . |
parentDocumentUri |
Uri: parent document of the document to remove. This value cannot be null . |
content |
ContentResolver: This value cannot be null . |
Return | |
---|---|
Boolean |
true if the document was removed successfully. |
renameDocument
static fun renameDocument(
content: ContentResolver,
documentUri: Uri,
displayName: String
): Uri?
Change the display name of an existing document.
If the underlying provider needs to create a new 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.
Parameters | |
---|---|
documentUri |
Uri: document with Document#FLAG_SUPPORTS_RENAME This value cannot be null . |
displayName |
String: updated name for document This value cannot be null . |
content |
ContentResolver: This value cannot be null . |
Return | |
---|---|
Uri? |
the existing or new document after the rename, or null if failed. |