| 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.
| Nested Classes | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| DocumentsContract.Document |
Constants related to a document, including Cursor column names
and flags.
|
||||||||||
| 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 | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Build URI representing the children of the target directory in a document
provider.
| |||||||||||
Build URI representing the children of the target directory in a document
provider.
| |||||||||||
Build URI representing the target
COLUMN_DOCUMENT_ID in
a document provider.
| |||||||||||
Build URI representing the target
COLUMN_DOCUMENT_ID in
a document provider.
| |||||||||||
Build URI representing the recently modified documents of a specific root
in a document provider.
| |||||||||||
Build URI representing the given
COLUMN_ROOT_ID in a
document provider.
| |||||||||||
Build URI representing the roots of a document provider.
| |||||||||||
Build URI representing a search for matching documents under a specific
root in a document provider.
| |||||||||||
Build URI representing access to descendant documents of the given
COLUMN_DOCUMENT_ID.
| |||||||||||
Create a new document with given MIME type and display name.
| |||||||||||
Delete the given document.
| |||||||||||
Extract the
COLUMN_DOCUMENT_ID from the given URI.
| |||||||||||
Return thumbnail representing the document at the given URI.
| |||||||||||
Extract the
COLUMN_ROOT_ID from the given URI.
| |||||||||||
Extract the search query from a URI built by
buildSearchDocumentsUri(String, String, String).
| |||||||||||
Extract the via
COLUMN_DOCUMENT_ID from the given URI.
| |||||||||||
Test if the given URI represents a
DocumentsContract.Document backed by a
DocumentsProvider.
| |||||||||||
Change the display name of an existing document.
| |||||||||||
|
[Expand]
Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
| |||||||||||
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.
Set this in a DocumentsUI intent to cause a package's own roots to be excluded from the roots list.
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.
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.
Overrides the default prompt text in DocumentsUI when set in an intent.
Intent action used to identify DocumentsProvider instances. This
is used in the
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.
| parentDocumentId | the document to return children for, which must
be a directory with MIME type of
MIME_TYPE_DIR. |
|---|
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.
| 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. |
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.
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.
| 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. |
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.
Build URI representing the given COLUMN_ROOT_ID in a
document provider.
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.
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.
Build URI representing access to descendant documents of the given
COLUMN_DOCUMENT_ID.
Create a new document with given MIME type and display name.
| parentDocumentUri | directory with
FLAG_DIR_SUPPORTS_CREATE |
|---|---|
| mimeType | MIME type of new document |
| displayName | name of new document |
Developers
null if failed
Delete the given document.
| documentUri | document with FLAG_SUPPORTS_DELETE |
|---|
Extract the COLUMN_DOCUMENT_ID from the given URI.
Return thumbnail representing the document at the given URI. Callers are responsible for their own in-memory caching.
| 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. |
null if problem was encountered.Extract the COLUMN_ROOT_ID from the given URI.
Extract the search query from a URI built by
buildSearchDocumentsUri(String, String, String).
Extract the via COLUMN_DOCUMENT_ID from the given URI.
Test if the given URI represents a DocumentsContract.Document backed by a
DocumentsProvider.
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.
| documentUri | document with FLAG_SUPPORTS_RENAME |
|---|---|
| displayName | updated name for document |
null if
failed.