java.lang.Object | ||
↳ | android.content.ContentProvider | |
↳ | android.provider.DocumentsProvider |
Base class for a document provider. A document provider offers read and write access to durable files, such as files stored on a local disk, or files in a cloud storage service. To create a document provider, extend this class, implement the abstract methods, and add it to your manifest like this:
<manifest> ... <application> ... <provider android:name="com.example.MyCloudProvider" android:authorities="com.example.mycloudprovider" android:exported="true" android:grantUriPermissions="true" android:permission="android.permission.MANAGE_DOCUMENTS" android:enabled="@bool/isAtLeastKitKat"> <intent-filter> <action android:name="android.content.action.DOCUMENTS_PROVIDER" /> </intent-filter> </provider> ... </application> </manifest>
When defining your provider, you must protect it with
MANAGE_DOCUMENTS
, which is a permission
only the system can obtain. Applications cannot use a documents provider
directly; they must go through ACTION_OPEN_DOCUMENT
or
ACTION_CREATE_DOCUMENT
which requires a user to actively
navigate and select documents. When a user selects documents through that UI,
the system issues narrow URI permission grants to the requesting application.
A document can be either an openable stream (with a specific MIME type), or a
directory containing additional documents (with the
MIME_TYPE_DIR
MIME type). Each directory represents the top
of a subtree containing zero or more documents, which can recursively contain
even more documents and directories.
Each document can have different capabilities, as described by
COLUMN_FLAGS
. For example, if a document can be represented
as a thumbnail, your provider can set
FLAG_SUPPORTS_THUMBNAIL
and implement
openDocumentThumbnail(String, Point, CancellationSignal)
to return
that thumbnail.
Each document under a provider is uniquely referenced by its
COLUMN_DOCUMENT_ID
, which must not change once returned. A
single document can be included in multiple directories when responding to
queryChildDocuments(String, String[], String)
. For example, a
provider might surface a single photo in multiple locations: once in a
directory of geographic locations, and again in a directory of dates.
All documents are surfaced through one or more "roots." Each root represents
the top of a document tree that a user can navigate. For example, a root
could represent an account or a physical storage device. Similar to
documents, each root can have capabilities expressed through
COLUMN_FLAGS
.
[Expand]
Inherited Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From interface
android.content.ComponentCallbacks2
|
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Implementation is provided by the parent class.
| |||||||||||
Implementation is provided by the parent class.
| |||||||||||
Implementation is provided by the parent class.
| |||||||||||
Create a new document and return its newly generated
COLUMN_DOCUMENT_ID . | |||||||||||
Implementation is provided by the parent class.
| |||||||||||
Delete the requested document.
| |||||||||||
Return concrete MIME type of the requested document.
| |||||||||||
Implementation is provided by the parent class.
| |||||||||||
Implementation is provided by the parent class.
| |||||||||||
Test if a document is descendant (child, grandchild, etc) from the given
parent.
| |||||||||||
Implementation is provided by the parent class.
| |||||||||||
Implementation is provided by the parent class.
| |||||||||||
Open and return the requested document.
| |||||||||||
Open and return a thumbnail of the requested document.
| |||||||||||
Implementation is provided by the parent class.
| |||||||||||
Implementation is provided by the parent class.
| |||||||||||
Implementation is provided by the parent class.
| |||||||||||
Implementation is provided by the parent class.
| |||||||||||
Implementation is provided by the parent class.
| |||||||||||
Return the children documents contained in the requested directory.
| |||||||||||
Return metadata for the single requested document.
| |||||||||||
Return recently modified documents under the requested root.
| |||||||||||
Return all roots currently provided.
| |||||||||||
Return documents that that match the given query under the requested
root.
| |||||||||||
Rename an existing document.
| |||||||||||
Revoke any active permission grants for the given
COLUMN_DOCUMENT_ID , usually called when a document
becomes invalid. | |||||||||||
Implementation is provided by the parent class.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
android.content.ContentProvider
| |||||||||||
From class
java.lang.Object
| |||||||||||
From interface
android.content.ComponentCallbacks
| |||||||||||
From interface
android.content.ComponentCallbacks2
|
Implementation is provided by the parent class.
context | The context this provider is running in |
---|---|
info | Registered information about this content provider |
Implementation is provided by the parent class. Can be overridden to
provide additional functionality, but subclasses must always
call the superclass. If the superclass returns null
, the subclass
may implement custom behavior.
method | method name to call. Opaque to framework, but should not be null . |
---|---|
arg | provider-defined String argument. May be null . |
extras | provider-defined Bundle argument. May be null . |
null
, which is also
the default for providers which don't implement any call methods.
Implementation is provided by the parent class. Can be overridden to
provide additional functionality, but subclasses must always
call the superclass. If the superclass returns null
, the subclass
may implement custom behavior.
This is typically used to resolve a subtree URI into a concrete document reference, issuing a narrower single-document URI permission grant along the way.
uri | The Uri to canonicalize. |
---|
Create a new document and return its newly generated
COLUMN_DOCUMENT_ID
. You must allocate a new
COLUMN_DOCUMENT_ID
to represent the document, which must
not change once returned.
parentDocumentId | the parent directory to create the new document under. |
---|---|
mimeType | the concrete MIME type associated with the new document. If the MIME type is not supported, the provider must throw. |
displayName | the display name of the new document. The provider may alter this name to meet any internal constraints, such as avoiding conflicting names. |
FileNotFoundException |
---|
Implementation is provided by the parent class. Throws by default, and cannot be overriden.
uri | The full URI to query, including a row ID (if a specific record is requested). |
---|---|
selection | An optional restriction to apply to rows when deleting. |
Delete the requested document.
Upon returning, any URI permission grants for the given document will be
revoked. If additional documents were deleted as a side effect of this
call (such as documents inside a directory) the implementor is
responsible for revoking those permissions using
revokeDocumentPermission(String)
.
documentId | the document to delete. |
---|
FileNotFoundException |
---|
Return concrete MIME type of the requested document. Must match the value
of COLUMN_MIME_TYPE
for this document. The default
implementation queries queryDocument(String, String[])
, so
providers may choose to override this as an optimization.
FileNotFoundException |
---|
Implementation is provided by the parent class. Cannot be overriden.
uri | the URI to query. |
---|
null
if there is no type.
Implementation is provided by the parent class. Throws by default, and cannot be overriden.
uri | The content:// URI of the insertion request. This must not be null . |
---|---|
values | A set of column_name/value pairs to add to the database.
This must not be null . |
Test if a document is descendant (child, grandchild, etc) from the given
parent. For example, providers must implement this to support
ACTION_OPEN_DOCUMENT_TREE
. You should avoid making network
requests to keep this request fast.
parentDocumentId | parent to verify against. |
---|---|
documentId | child to verify. |
Implementation is provided by the parent class. Cannot be overriden.
uri | The URI whose file is to be opened. |
---|---|
mode | Access mode for the file. May be "r" for read-only access, "w" for write-only access (erasing whatever data is currently in the file), "wa" for write-only access to append to any existing data, "rw" for read and write access on any existing data, and "rwt" for read and write access that truncates any existing file. |
signal | A signal to cancel the operation in progress, or
null if none. For example, if you are downloading a
file from the network to service a "rw" mode request, you
should periodically call
throwIfCanceled() to check whether
the client has canceled the request and abort the download. |
FileNotFoundException |
---|
Implementation is provided by the parent class. Cannot be overriden.
uri | The URI whose file is to be opened. |
---|---|
mode | Access mode for the file. May be "r" for read-only access, "w" for write-only access (erasing whatever data is currently in the file), "wa" for write-only access to append to any existing data, "rw" for read and write access on any existing data, and "rwt" for read and write access that truncates any existing file. |
FileNotFoundException |
---|
Open and return the requested document.
Your provider should return a reliable ParcelFileDescriptor
to
detect when the remote caller has finished reading or writing the
document. You may return a pipe or socket pair if the mode is exclusively
"r" or "w", but complex modes like "rw" imply a normal file on disk that
supports seeking.
If you block while downloading content, you should periodically check
isCanceled()
to abort abandoned open requests.
documentId | the document to return. |
---|---|
mode | the mode to open with, such as 'r', 'w', or 'rw'. |
signal | used by the caller to signal if the request should be cancelled. May be null. |
FileNotFoundException |
---|
Open and return a thumbnail of the requested document.
A provider should return a thumbnail closely matching the hinted size, attempting to serve from a local cache if possible. A provider should never return images more than double the hinted size.
If you perform expensive operations to download or generate a thumbnail,
you should periodically check isCanceled()
to
abort abandoned thumbnail requests.
documentId | the document to return. |
---|---|
sizeHint | hint of the optimal thumbnail dimensions. |
signal | used by the caller to signal if the request should be cancelled. May be null. |
FileNotFoundException |
---|
Implementation is provided by the parent class. Cannot be overriden.
uri | The URI whose file is to be opened. |
---|---|
mode | Access mode for the file. May be "r" for read-only access, "rw" for read and write access, or "rwt" for read and write access that truncates any existing file. |
FileNotFoundException |
---|
Implementation is provided by the parent class. Cannot be overriden.
uri | The URI whose file is to be opened. |
---|---|
mode | Access mode for the file. May be "r" for read-only access, "w" for write-only access, "rw" for read and write access, or "rwt" for read and write access that truncates any existing file. |
signal | A signal to cancel the operation in progress, or
null if none. For example, if you are downloading a
file from the network to service a "rw" mode request, you
should periodically call
throwIfCanceled() to check whether
the client has canceled the request and abort the download. |
FileNotFoundException |
---|
Implementation is provided by the parent class. Cannot be overriden.
uri | The data in the content provider being queried. |
---|---|
mimeTypeFilter | The type of data the client desires. May be a pattern, such as */*, if the caller does not have specific type requirements; in this case the content provider will pick its best type matching the pattern. |
opts | Additional options from the client. The definitions of these are specific to the content provider being called. |
signal | A signal to cancel the operation in progress, or
null if none. For example, if you are downloading a
file from the network to service a "rw" mode request, you
should periodically call
throwIfCanceled() to check whether
the client has canceled the request and abort the download. |
FileNotFoundException |
---|
Implementation is provided by the parent class. Cannot be overriden.
uri | The data in the content provider being queried. |
---|---|
mimeTypeFilter | The type of data the client desires. May be a pattern, such as */*, if the caller does not have specific type requirements; in this case the content provider will pick its best type matching the pattern. |
opts | Additional options from the client. The definitions of these are specific to the content provider being called. |
FileNotFoundException |
---|
Implementation is provided by the parent class. Cannot be overriden.
uri | The URI to query. This will be the full URI sent by the client; if the client is requesting a specific record, the URI will end in a record number that the implementation should parse and add to a WHERE or HAVING clause, specifying that _id value. |
---|---|
projection | The list of columns to put into the cursor. If
null all columns are included. |
selection | A selection criteria to apply when filtering rows.
If null then all rows are included. |
selectionArgs | You may include ?s in selection, which will be replaced by the values from selectionArgs, in order that they appear in the selection. The values will be bound as Strings. |
sortOrder | How the rows in the cursor should be sorted.
If null then the provider is free to define the sort order. |
null
.
Return the children documents contained in the requested directory. This must only return immediate descendants, as additional queries will be issued to recursively explore the tree.
If your provider is cloud-based, and you have some data cached or pinned
locally, you may return the local data immediately, setting
EXTRA_LOADING
on the Cursor to indicate that
you are still fetching additional data. Then, when the network data is
available, you can send a change notification to trigger a requery and
return the complete contents. To return a Cursor with extras, you need to
extend and override getExtras()
.
To support change notifications, you must
setNotificationUri(ContentResolver, Uri)
with a relevant
Uri, such as
buildChildDocumentsUri(String, String)
. Then
you can call notifyChange(Uri, android.database.ContentObserver, boolean)
with that Uri to send change
notifications.
parentDocumentId | the directory to return children for. |
---|---|
projection | list of DocumentsContract.Document columns to put into the
cursor. If null all supported columns should be
included. |
sortOrder | how to order the rows, formatted as an SQL
ORDER BY clause (excluding the ORDER BY itself).
Passing null will use the default sort order, which
may be unordered. This ordering is a hint that can be used to
prioritize how data is fetched from the network, but UI may
always enforce a specific ordering. |
FileNotFoundException |
---|
Return metadata for the single requested document. You should avoid making network requests to keep this request fast.
documentId | the document to return. |
---|---|
projection | list of DocumentsContract.Document columns to put into the
cursor. If null all supported columns should be
included.
|
FileNotFoundException |
---|
Return recently modified documents under the requested root. This will
only be called for roots that advertise
FLAG_SUPPORTS_RECENTS
. The returned documents should be
sorted by COLUMN_LAST_MODIFIED
in descending order, and
limited to only return the 64 most recently modified documents.
Recent documents do not support change notifications.
projection | list of DocumentsContract.Document columns to put into the
cursor. If null all supported columns should be
included. |
---|
FileNotFoundException |
---|
Return all roots currently provided. To display to users, you must define at least one root. You should avoid making network requests to keep this request fast.
Each root is defined by the metadata columns described in DocumentsContract.Root
,
including COLUMN_DOCUMENT_ID
which points to a directory
representing a tree of documents to display under that root.
If this set of roots changes, you must call notifyChange(Uri, android.database.ContentObserver, boolean)
with
buildRootsUri(String)
to notify the system.
projection | list of DocumentsContract.Root columns to put into the cursor. If
null all supported columns should be included.
|
---|
FileNotFoundException |
---|
Return documents that that match the given query under the requested
root. The returned documents should be sorted by relevance in descending
order. How documents are matched against the query string is an
implementation detail left to each provider, but it's suggested that at
least COLUMN_DISPLAY_NAME
be matched in a
case-insensitive fashion.
Only documents may be returned; directories are not supported in search results.
If your provider is cloud-based, and you have some data cached or pinned
locally, you may return the local data immediately, setting
EXTRA_LOADING
on the Cursor to indicate that
you are still fetching additional data. Then, when the network data is
available, you can send a change notification to trigger a requery and
return the complete contents.
To support change notifications, you must
setNotificationUri(ContentResolver, Uri)
with a relevant
Uri, such as buildSearchDocumentsUri(String, String, String)
. Then you can call notifyChange(Uri, android.database.ContentObserver, boolean)
with that Uri to send change
notifications.
rootId | the root to search under. |
---|---|
query | string to match documents against. |
projection | list of DocumentsContract.Document columns to put into the
cursor. If null all supported columns should be
included. |
FileNotFoundException |
---|
Rename an existing document.
If a different COLUMN_DOCUMENT_ID
must be used to
represent the renamed document, generate and return it. Any outstanding
URI permission grants will be updated to point at the new document. If
the original COLUMN_DOCUMENT_ID
is still valid after the
rename, return null
.
documentId | the document to rename. |
---|---|
displayName | the updated display name of the document. The provider may alter this name to meet any internal constraints, such as avoiding conflicting names. |
FileNotFoundException |
---|
Revoke any active permission grants for the given
COLUMN_DOCUMENT_ID
, usually called when a document
becomes invalid. Follows the same semantics as
revokeUriPermission(Uri, int)
.
Implementation is provided by the parent class. Throws by default, and cannot be overriden.
uri | The URI to query. This can potentially have a record ID if this is an update request for a specific record. |
---|---|
values | A set of column_name/value pairs to update in the database.
This must not be null . |
selection | An optional filter to match rows to update. |