Skip to content

Most visited

Recently visited

navigation
Added in API level 19

DocumentsContract

public final class DocumentsContract
extends Object

java.lang.Object
   ↳ 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 ACTION_OPEN_DOCUMENT, ACTION_CREATE_DOCUMENT, or ACTION_OPEN_DOCUMENT_TREE.

See also:

Summary

Nested classes

class DocumentsContract.Document

Constants related to a document, including Cursor column names and flags. 

class DocumentsContract.Root

Constants related to a root of documents, including Cursor column names and flags. 

Constants

String EXTRA_ERROR

Optional string included in a directory getExtras() providing an error message that should be shown to a user.

String EXTRA_EXCLUDE_SELF

Set this in a DocumentsUI intent to cause a package's own roots to be excluded from the roots list.

String EXTRA_INFO

Optional string included in a directory getExtras() providing an informational message that should be shown to a user.

String EXTRA_LOADING

Optional boolean flag included in a directory getExtras() indicating that a document provider is still loading data.

String EXTRA_PROMPT

Overrides the default prompt text in DocumentsUI when set in an intent.

String PROVIDER_INTERFACE

Intent action used to identify DocumentsProvider instances.

Public methods

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 COLUMN_DOCUMENT_ID in a document provider.

static Uri buildDocumentUriUsingTree(Uri treeUri, String documentId)

Build URI representing the target COLUMN_DOCUMENT_ID in a document provider.

static Uri buildRecentDocumentsUri(String authority, String rootId)

Build URI representing the recently modified documents of a specific root in a document provider.

static Uri buildRootUri(String authority, String rootId)

Build URI representing the given COLUMN_ROOT_ID in a document provider.

static Uri buildRootsUri(String authority)

Build URI representing the roots of 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 COLUMN_DOCUMENT_ID.

static Uri createDocument(ContentResolver resolver, Uri parentDocumentUri, String mimeType, String displayName)

Create a new document with given MIME type and display name.

static boolean deleteDocument(ContentResolver resolver, Uri documentUri)

Delete the given document.

static String getDocumentId(Uri documentUri)

Extract the COLUMN_DOCUMENT_ID from the given URI.

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 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 COLUMN_DOCUMENT_ID from the given URI.

static boolean isDocumentUri(Context context, Uri uri)

Test if the given URI represents a DocumentsContract.Document backed by a DocumentsProvider.

static Uri renameDocument(ContentResolver resolver, Uri documentUri, String displayName)

Change the display name of an existing document.

Inherited methods

From class java.lang.Object

Constants

EXTRA_ERROR

Added in API level 19
String EXTRA_ERROR

Optional string included in a directory 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.

Constant Value: "error"

EXTRA_EXCLUDE_SELF

Added in API level 23
String EXTRA_EXCLUDE_SELF

Set this in a DocumentsUI intent to cause a package's own roots to be excluded from the roots list.

Constant Value: "android.provider.extra.EXCLUDE_SELF"

EXTRA_INFO

Added in API level 19
String EXTRA_INFO

Optional string included in a directory 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.

Constant Value: "info"

EXTRA_LOADING

Added in API level 19
String EXTRA_LOADING

Optional boolean flag included in a directory 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.

See also:

Constant Value: "loading"

EXTRA_PROMPT

Added in API level 23
String EXTRA_PROMPT

Overrides the default prompt text in DocumentsUI when set in an intent.

Constant Value: "android.provider.extra.PROMPT"

PROVIDER_INTERFACE

Added in API level 19
String PROVIDER_INTERFACE

Intent action used to identify DocumentsProvider instances. This is used in the of a .

Constant Value: "android.content.action.DOCUMENTS_PROVIDER"

Public methods

buildChildDocumentsUri

Added in API level 19
Uri buildChildDocumentsUri (String authority, 
                String parentDocumentId)

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 DocumentsContract.Document.

Parameters
authority String
parentDocumentId String: the document to return children for, which must be a directory with MIME type of MIME_TYPE_DIR.
Returns
Uri

See also:

buildChildDocumentsUriUsingTree

Added in API level 21
Uri buildChildDocumentsUriUsingTree (Uri treeUri, 
                String parentDocumentId)

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 DocumentsContract.Document.

However, instead of directly accessing the target directory, the returned URI will leverage access granted through a subtree URI, typically returned by 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 MIME_TYPE_DIR.
Returns
Uri

See also:

buildDocumentUri

Added in API level 19
Uri buildDocumentUri (String authority, 
                String documentId)

Build URI representing the target COLUMN_DOCUMENT_ID in a document provider. When queried, a provider will return a single row with columns defined by DocumentsContract.Document.

Parameters
authority String
documentId String
Returns
Uri

See also:

buildDocumentUriUsingTree

Added in API level 21
Uri buildDocumentUriUsingTree (Uri treeUri, 
                String documentId)

Build URI representing the target 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 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.
Returns
Uri

See also:

buildRecentDocumentsUri

Added in API level 19
Uri buildRecentDocumentsUri (String authority, 
                String rootId)

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 DocumentsContract.Document.

Parameters
authority String
rootId String
Returns
Uri

See also:

buildRootUri

Added in API level 19
Uri buildRootUri (String authority, 
                String rootId)

Build URI representing the given COLUMN_ROOT_ID in a document provider.

Parameters
authority String
rootId String
Returns
Uri

See also:

buildRootsUri

Added in API level 19
Uri buildRootsUri (String authority)

Build URI representing the roots of a document provider. When queried, a provider will return one or more rows with columns defined by DocumentsContract.Root.

Parameters
authority String
Returns
Uri

See also:

buildSearchDocumentsUri

Added in API level 19
Uri buildSearchDocumentsUri (String authority, 
                String rootId, 
                String query)

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 DocumentsContract.Document.

Parameters
authority String
rootId String
query String
Returns
Uri

See also:

buildTreeDocumentUri

Added in API level 21
Uri buildTreeDocumentUri (String authority, 
                String documentId)

Build URI representing access to descendant documents of the given COLUMN_DOCUMENT_ID.

Parameters
authority String
documentId String
Returns
Uri

See also:

createDocument

Added in API level 21
Uri createDocument (ContentResolver resolver, 
                Uri parentDocumentUri, 
                String mimeType, 
                String displayName)

Create a new document with given MIME type and display name.

Parameters
resolver ContentResolver
parentDocumentUri Uri: directory with FLAG_DIR_SUPPORTS_CREATE
mimeType String: MIME type of new document
displayName String: name of new document
Returns
Uri newly created document, or null if failed

deleteDocument

Added in API level 19
boolean deleteDocument (ContentResolver resolver, 
                Uri documentUri)

Delete the given document.

Parameters
resolver ContentResolver
documentUri Uri: document with FLAG_SUPPORTS_DELETE
Returns
boolean if the document was deleted successfully.

getDocumentId

Added in API level 19
String getDocumentId (Uri documentUri)

Extract the COLUMN_DOCUMENT_ID from the given URI.

Parameters
documentUri Uri
Returns
String

See also:

getDocumentThumbnail

Added in API level 19
Bitmap getDocumentThumbnail (ContentResolver resolver, 
                Uri documentUri, 
                Point size, 
                CancellationSignal signal)

Return thumbnail representing the document at the given URI. Callers are responsible for their own in-memory caching.

Parameters
resolver ContentResolver
documentUri Uri: document to return thumbnail for, which must have FLAG_SUPPORTS_THUMBNAIL set.
size Point: optimal thumbnail size desired. A provider may return a thumbnail of a different size, but never more than double the requested size.
signal CancellationSignal: signal used to indicate if caller is no longer interested in the thumbnail.
Returns
Bitmap decoded thumbnail, or null if problem was encountered.

See also:

getRootId

Added in API level 19
String getRootId (Uri rootUri)

Extract the COLUMN_ROOT_ID from the given URI.

Parameters
rootUri Uri
Returns
String

getSearchDocumentsQuery

Added in API level 19
String getSearchDocumentsQuery (Uri searchDocumentsUri)

Extract the search query from a URI built by buildSearchDocumentsUri(String, String, String).

Parameters
searchDocumentsUri Uri
Returns
String

getTreeDocumentId

Added in API level 21
String getTreeDocumentId (Uri documentUri)

Extract the via COLUMN_DOCUMENT_ID from the given URI.

Parameters
documentUri Uri
Returns
String

isDocumentUri

Added in API level 19
boolean isDocumentUri (Context context, 
                Uri uri)

Test if the given URI represents a DocumentsContract.Document backed by a DocumentsProvider.

Parameters
context Context
uri Uri
Returns
boolean

See also:

renameDocument

Added in API level 21
Uri renameDocument (ContentResolver resolver, 
                Uri documentUri, 
                String displayName)

Change the display name of an existing document.

If the underlying provider needs to create a new 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
resolver ContentResolver
documentUri Uri: document with FLAG_SUPPORTS_RENAME
displayName String: updated name for document
Returns
Uri the existing or new document after the rename, or null if failed.
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.