Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)
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.

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 given directory in a document provider.
static Uri buildDocumentUri ( String authority, String documentId)
Build URI representing the given 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 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 boolean isDocumentUri ( Context context, Uri uri)
Test if the given URI represents a DocumentsContract.Document backed by a DocumentsProvider .
[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)

Build URI representing the children of the given 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 buildDocumentUri ( String authority, String documentId)

Build URI representing the given 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 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 .

See Also

public static Uri buildRootUri ( String authority, String rootId)

Build URI representing the given COLUMN_ROOT_ID in a document provider.

See Also

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

See Also

public 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. When queried, a provider will return zero or more rows with columns defined by DocumentsContract.Document .

See Also

public static boolean deleteDocument ( ContentResolver resolver, Uri documentUri)

Delete the given document.

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

public static String getDocumentId ( Uri documentUri)

Extract the COLUMN_DOCUMENT_ID from the given URI.

public static 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
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)

Extract the COLUMN_ROOT_ID from the given URI.

public static String getSearchDocumentsQuery ( Uri searchDocumentsUri)

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

public static boolean isDocumentUri ( Context context, Uri uri)

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