Android APIs
public abstract class

DocumentsProvider

extends ContentProvider
java.lang.Object
   ↳ android.content.ContentProvider
     ↳ android.provider.DocumentsProvider

Class Overview

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.

Documents

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.

Roots

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.

See Also

Summary

[Expand]
Inherited Constants
From interface android.content.ComponentCallbacks2
Public Constructors
DocumentsProvider()
Public Methods
void attachInfo(Context context, ProviderInfo info)
Implementation is provided by the parent class.
Bundle call(String method, String arg, Bundle extras)
Implementation is provided by the parent class.
Uri canonicalize(Uri uri)
Implementation is provided by the parent class.
String createDocument(String parentDocumentId, String mimeType, String displayName)
Create a new document and return its newly generated COLUMN_DOCUMENT_ID.
final int delete(Uri uri, String selection, String[] selectionArgs)
Implementation is provided by the parent class.
void deleteDocument(String documentId)
Delete the requested document.
String getDocumentType(String documentId)
Return concrete MIME type of the requested document.
final String getType(Uri uri)
Implementation is provided by the parent class.
final Uri insert(Uri uri, ContentValues values)
Implementation is provided by the parent class.
boolean isChildDocument(String parentDocumentId, String documentId)
Test if a document is descendant (child, grandchild, etc) from the given parent.
final AssetFileDescriptor openAssetFile(Uri uri, String mode, CancellationSignal signal)
Implementation is provided by the parent class.
final AssetFileDescriptor openAssetFile(Uri uri, String mode)
Implementation is provided by the parent class.
abstract ParcelFileDescriptor openDocument(String documentId, String mode, CancellationSignal signal)
Open and return the requested document.
AssetFileDescriptor openDocumentThumbnail(String documentId, Point sizeHint, CancellationSignal signal)
Open and return a thumbnail of the requested document.
final ParcelFileDescriptor openFile(Uri uri, String mode)
Implementation is provided by the parent class.
final ParcelFileDescriptor openFile(Uri uri, String mode, CancellationSignal signal)
Implementation is provided by the parent class.
final AssetFileDescriptor openTypedAssetFile(Uri uri, String mimeTypeFilter, Bundle opts, CancellationSignal signal)
Implementation is provided by the parent class.
final AssetFileDescriptor openTypedAssetFile(Uri uri, String mimeTypeFilter, Bundle opts)
Implementation is provided by the parent class.
final Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder)
Implementation is provided by the parent class.
abstract Cursor queryChildDocuments(String parentDocumentId, String[] projection, String sortOrder)
Return the children documents contained in the requested directory.
abstract Cursor queryDocument(String documentId, String[] projection)
Return metadata for the single requested document.
Cursor queryRecentDocuments(String rootId, String[] projection)
Return recently modified documents under the requested root.
abstract Cursor queryRoots(String[] projection)
Return all roots currently provided.
Cursor querySearchDocuments(String rootId, String query, String[] projection)
Return documents that that match the given query under the requested root.
String renameDocument(String documentId, String displayName)
Rename an existing document.
final void revokeDocumentPermission(String documentId)
Revoke any active permission grants for the given COLUMN_DOCUMENT_ID, usually called when a document becomes invalid.
final int update(Uri uri, ContentValues values, String selection, String[] selectionArgs)
Implementation is provided by the parent class.
[Expand]
Inherited Methods
From class android.content.ContentProvider
From class java.lang.Object
From interface android.content.ComponentCallbacks2
From interface android.content.ComponentCallbacks

Public Constructors

public DocumentsProvider ()

Added in API level 19

Public Methods

public void attachInfo (Context context, ProviderInfo info)

Added in API level 19

Implementation is provided by the parent class.

Parameters
context The context this provider is running in
info Registered information about this content provider

public Bundle call (String method, String arg, Bundle extras)

Added in API level 19

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.

Parameters
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.
Returns
  • provider-defined return value. May be null, which is also the default for providers which don't implement any call methods.

public Uri canonicalize (Uri uri)

Added in API level 19

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.

Parameters
uri The Uri to canonicalize.
Returns
  • Return the canonical representation of url, or null if canonicalization of that Uri is not supported.
See Also

public String createDocument (String parentDocumentId, String mimeType, String displayName)

Added in API level 19

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.

Parameters
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.
Throws
FileNotFoundException

public final int delete (Uri uri, String selection, String[] selectionArgs)

Added in API level 19

Implementation is provided by the parent class. Throws by default, and cannot be overriden.

Parameters
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.
Returns
  • The number of rows affected.
See Also

public void deleteDocument (String documentId)

Added in API level 19

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).

Parameters
documentId the document to delete.
Throws
FileNotFoundException

public String getDocumentType (String documentId)

Added in API level 19

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.

Throws
FileNotFoundException

public final String getType (Uri uri)

Added in API level 19

Implementation is provided by the parent class. Cannot be overriden.

Parameters
uri the URI to query.
Returns
  • a MIME type string, or null if there is no type.
See Also

public final Uri insert (Uri uri, ContentValues values)

Added in API level 19

Implementation is provided by the parent class. Throws by default, and cannot be overriden.

Parameters
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.
Returns
  • The URI for the newly inserted item.
See Also

public boolean isChildDocument (String parentDocumentId, String documentId)

Added in API level 21

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.

Parameters
parentDocumentId parent to verify against.
documentId child to verify.
Returns
  • if given document is a descendant of the given parent.
See Also

public final AssetFileDescriptor openAssetFile (Uri uri, String mode, CancellationSignal signal)

Added in API level 19

Implementation is provided by the parent class. Cannot be overriden.

Parameters
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.
Returns
  • Returns a new AssetFileDescriptor which you can use to access the file.
Throws
FileNotFoundException
See Also

public final AssetFileDescriptor openAssetFile (Uri uri, String mode)

Added in API level 19

Implementation is provided by the parent class. Cannot be overriden.

Parameters
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.
Returns
  • Returns a new AssetFileDescriptor which you can use to access the file.
Throws
FileNotFoundException
See Also

public abstract ParcelFileDescriptor openDocument (String documentId, String mode, CancellationSignal signal)

Added in API level 19

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.

Parameters
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.
Throws
FileNotFoundException
See Also

public AssetFileDescriptor openDocumentThumbnail (String documentId, Point sizeHint, CancellationSignal signal)

Added in API level 19

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.

Parameters
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.
Throws
FileNotFoundException
See Also

public final ParcelFileDescriptor openFile (Uri uri, String mode)

Added in API level 19

Implementation is provided by the parent class. Cannot be overriden.

Parameters
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.
Returns
  • Returns a new ParcelFileDescriptor which you can use to access the file.
Throws
FileNotFoundException
See Also

public final ParcelFileDescriptor openFile (Uri uri, String mode, CancellationSignal signal)

Added in API level 19

Implementation is provided by the parent class. Cannot be overriden.

Parameters
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.
Returns
  • Returns a new ParcelFileDescriptor which you can use to access the file.
Throws
FileNotFoundException
See Also

public final AssetFileDescriptor openTypedAssetFile (Uri uri, String mimeTypeFilter, Bundle opts, CancellationSignal signal)

Added in API level 19

Implementation is provided by the parent class. Cannot be overriden.

Parameters
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.
Returns
  • Returns a new AssetFileDescriptor from which the client can read data of the desired type.
Throws
FileNotFoundException
See Also

public final AssetFileDescriptor openTypedAssetFile (Uri uri, String mimeTypeFilter, Bundle opts)

Added in API level 19

Implementation is provided by the parent class. Cannot be overriden.

Parameters
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.
Returns
  • Returns a new AssetFileDescriptor from which the client can read data of the desired type.
Throws
FileNotFoundException
See Also

public final Cursor query (Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder)

Added in API level 19

Implementation is provided by the parent class. Cannot be overriden.

Parameters
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.
Returns
  • a Cursor or null.
See Also

public abstract Cursor queryChildDocuments (String parentDocumentId, String[] projection, String sortOrder)

Added in API level 19

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.

Parameters
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.
Throws
FileNotFoundException
See Also

public abstract Cursor queryDocument (String documentId, String[] projection)

Added in API level 19

Return metadata for the single requested document. You should avoid making network requests to keep this request fast.

Parameters
documentId the document to return.
projection list of DocumentsContract.Document columns to put into the cursor. If null all supported columns should be included.
Throws
FileNotFoundException

public Cursor queryRecentDocuments (String rootId, String[] projection)

Added in API level 19

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.

Parameters
projection list of DocumentsContract.Document columns to put into the cursor. If null all supported columns should be included.
Throws
FileNotFoundException
See Also

public abstract Cursor queryRoots (String[] projection)

Added in API level 19

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.

Parameters
projection list of DocumentsContract.Root columns to put into the cursor. If null all supported columns should be included.
Throws
FileNotFoundException

public Cursor querySearchDocuments (String rootId, String query, String[] projection)

Added in API level 19

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.

Parameters
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.
Throws
FileNotFoundException
See Also

public String renameDocument (String documentId, String displayName)

Added in API level 21

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.

Parameters
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.
Throws
FileNotFoundException

public final void revokeDocumentPermission (String documentId)

Added in API level 21

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).

public final int update (Uri uri, ContentValues values, String selection, String[] selectionArgs)

Added in API level 19

Implementation is provided by the parent class. Throws by default, and cannot be overriden.

Parameters
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.
Returns
  • the number of rows affected.