Android APIs
public final class

DocumentsContract

extends Object
java.lang.Object
   ↳ android.provider.DocumentsContract

Class Overview

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_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 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.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String EXTRA_ERROR

Added in API level 19

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"

public static final String EXTRA_INFO

Added in API level 19

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"

public static final String EXTRA_LOADING

Added in API level 19

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"

public static final String PROVIDER_INTERFACE

Added in API level 19

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

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

Public Methods

public static Uri buildChildDocumentsUri (String authority, String parentDocumentId)

Added in API level 19

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
parentDocumentId the document to return children for, which must be a directory with MIME type of MIME_TYPE_DIR.
See Also

public static 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 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 MIME_TYPE_DIR.
See Also

public static Uri buildDocumentUri (String authority, String documentId)

Added in API level 19

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.

See Also

public static 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 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.
See Also

public static Uri buildRecentDocumentsUri (String authority, String rootId)

Added in API level 19

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.

See Also

public static Uri buildRootUri (String authority, String rootId)

Added in API level 19

Build URI representing the given COLUMN_ROOT_ID in a document provider.

See Also

public static Uri buildRootsUri (String authority)

Added in API level 19

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.

See Also

public static Uri buildSearchDocumentsUri (String authority, String rootId, String query)

Added in API level 19

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.

See Also

public static Uri buildTreeDocumentUri (String authority, String documentId)

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

See Also

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

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

Parameters
parentDocumentUri directory with FLAG_DIR_SUPPORTS_CREATE
mimeType MIME type of new document
displayName name of new document
Returns
  • newly created document, or null if failed

public static boolean deleteDocument (ContentResolver resolver, Uri documentUri)

Added in API level 19

Delete the given document.

Parameters
documentUri document with FLAG_SUPPORTS_DELETE
Returns
  • if the document was deleted successfully.

public static String getDocumentId (Uri documentUri)

Added in API level 19

Extract the COLUMN_DOCUMENT_ID from the given URI.

See Also

public static Bitmap getDocumentThumbnail (ContentResolver resolver, Uri documentUri, Point size, CancellationSignal signal)

Added in API level 19

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

Parameters
documentUri document to return thumbnail for, which must have 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.
Returns
  • decoded thumbnail, or null if problem was encountered.
See Also

public static String getRootId (Uri rootUri)

Added in API level 19

Extract the COLUMN_ROOT_ID from the given URI.

public static String getSearchDocumentsQuery (Uri searchDocumentsUri)

Added in API level 19

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

public static String getTreeDocumentId (Uri documentUri)

Extract the via COLUMN_DOCUMENT_ID from the given URI.

public static boolean isDocumentUri (Context context, Uri uri)

Added in API level 19

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

See Also

public static 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
documentUri document with FLAG_SUPPORTS_RENAME
displayName updated name for document
Returns
  • the existing or new document after the rename, or null if failed.