Skip to content

Most visited

Recently visited

navigation

DocumentsContract

public final class DocumentsContract
extends Object

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, ACTION_OPEN_DOCUMENT_TREE, or StorageVolume.createAccessIntent.

See also:

Summary

Nested classes

class DocumentsContract.Document

Constants related to a document, including Cursor column names and flags. 

class DocumentsContract.Path

Holds a path from a document to a particular document under it. 

class DocumentsContract.Root

Constants related to a root of documents, including Cursor column names and flags. 

Constants

String ACTION_DOCUMENT_SETTINGS

Action of intent issued by DocumentsUI when user wishes to open/configure/manage a particular document in the provider application.

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_INITIAL_URI

Sets the desired initial location visible to user when file chooser is shown.

String EXTRA_LOADING

Optional boolean flag included in a directory getExtras() indicating that a document provider is still loading data.

String EXTRA_ORIENTATION

Included in getExtras() when returned thumbnail should be rotated.

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

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 copyDocument(ContentResolver resolver, Uri sourceDocumentUri, Uri targetParentDocumentUri)

Copies the given document.

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

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

static IntentSender createWebLinkIntent(ContentResolver resolver, Uri uri, Bundle options)

Creates an intent for obtaining a web link for the specified document.

static boolean deleteDocument(ContentResolver resolver, Uri documentUri)

Delete the given document.

static void ejectRoot(ContentResolver resolver, Uri rootUri)

Ejects the given root.

static DocumentsContract.Path findDocumentPath(ContentResolver resolver, Uri treeUri)

Finds the canonical path from the top of the document tree.

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 boolean isTreeUri(Uri uri)

Test if the given URI represents a DocumentsContract.Document tree.

static Uri moveDocument(ContentResolver resolver, Uri sourceDocumentUri, Uri sourceParentDocumentUri, Uri targetParentDocumentUri)

Moves the given document under a new parent.

static boolean removeDocument(ContentResolver resolver, Uri documentUri, Uri parentDocumentUri)

Removes the given document from a parent directory.

static Uri renameDocument(ContentResolver resolver, Uri documentUri, String displayName)

Change the display name of an existing document.

Inherited methods

From class java.lang.Object

Constants

ACTION_DOCUMENT_SETTINGS

added in API level 26
String ACTION_DOCUMENT_SETTINGS

Action of intent issued by DocumentsUI when user wishes to open/configure/manage a particular document in the provider application.

When issued, the intent will include the URI of the document as the intent data.

A provider wishing to provide support for this action should do two things.

  • Add an <intent-filter> matching this action.
  • When supplying information in queryChildDocuments(String, String[], Bundle), include FLAG_SUPPORTS_SETTINGS in the flags for each document that supports settings.

    Constant Value: "android.provider.action.DOCUMENT_SETTINGS"

  • EXTRA_ERROR

    added in API level 19
    String EXTRA_ERROR

    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"

    EXTRA_EXCLUDE_SELF

    added in API level 23
    String EXTRA_EXCLUDE_SELF

    Set this in a DocumentsUI intent to cause a package's own roots to be excluded from the roots list.

    Constant Value: "android.provider.extra.EXCLUDE_SELF"

    EXTRA_INFO

    added in API level 19
    String EXTRA_INFO

    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"

    EXTRA_INITIAL_URI

    added in API level 26
    String EXTRA_INITIAL_URI

    Sets the desired initial location visible to user when file chooser is shown.

    Applicable to Intent with actions:

    Location should specify a document URI or a tree URI with document ID. If this URI identifies a non-directory, document navigator will attempt to use the parent of the document as the initial location.

    The initial location is system specific if this extra is missing or document navigator failed to locate the desired initial location.

    Constant Value: "android.provider.extra.INITIAL_URI"

    EXTRA_LOADING

    added in API level 19
    String EXTRA_LOADING

    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.

    Constant Value: "loading"

    EXTRA_ORIENTATION

    added in API level 24
    String EXTRA_ORIENTATION

    Included in getExtras() when returned thumbnail should be rotated.

    See also:

    Constant Value: "android.provider.extra.ORIENTATION"

    EXTRA_PROMPT

    added in API level 23
    String EXTRA_PROMPT

    Overrides the default prompt text in DocumentsUI when set in an intent.

    Constant Value: "android.provider.extra.PROMPT"

    PROVIDER_INTERFACE

    added in API level 19
    String PROVIDER_INTERFACE

    Intent action used to identify DocumentsProvider instances. This is used in the <intent-filter> of a <provider>.

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

    Public methods

    buildChildDocumentsUri

    added in API level 19
    Uri buildChildDocumentsUri (String authority, 
                    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.

    Parameters
    authority String

    parentDocumentId String: the document to return children for, which must be a directory with MIME type of MIME_TYPE_DIR.

    Returns
    Uri

    buildChildDocumentsUriUsingTree

    added in API level 21
    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 Uri: the subtree to leverage to gain access to the target document. The target directory must be a descendant of this subtree.

    parentDocumentId String: 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.

    Returns
    Uri

    buildDocumentUri

    added in API level 19
    Uri buildDocumentUri (String authority, 
                    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.

    Parameters
    authority String

    documentId String

    Returns
    Uri

    buildDocumentUriUsingTree

    added in API level 21
    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 Uri: the subtree to leverage to gain access to the target document. The target directory must be a descendant of this subtree.

    documentId String: the target document, which the caller may not have direct access to.

    Returns
    Uri

    buildRecentDocumentsUri

    added in API level 19
    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.

    Parameters
    authority String

    rootId String

    Returns
    Uri

    buildRootUri

    added in API level 19
    Uri buildRootUri (String authority, 
                    String rootId)

    Build URI representing the given COLUMN_ROOT_ID in a document provider.

    Parameters
    authority String

    rootId String

    Returns
    Uri

    See also:

    buildRootsUri

    added in API level 19
    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.

    Parameters
    authority String

    Returns
    Uri

    buildSearchDocumentsUri

    added in API level 19
    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.

    Parameters
    authority String

    rootId String

    query String

    Returns
    Uri

    buildTreeDocumentUri

    added in API level 21
    Uri buildTreeDocumentUri (String authority, 
                    String documentId)

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

    Parameters
    authority String

    documentId String

    Returns
    Uri

    copyDocument

    added in API level 24
    Uri copyDocument (ContentResolver resolver, 
                    Uri sourceDocumentUri, 
                    Uri targetParentDocumentUri)

    Copies the given document.

    Parameters
    resolver ContentResolver

    sourceDocumentUri Uri: document with FLAG_SUPPORTS_COPY

    targetParentDocumentUri Uri: document which will become a parent of the source document's copy.

    Returns
    Uri the copied document, or null if failed.

    Throws
    FileNotFoundException

    createDocument

    added in API level 21
    Uri createDocument (ContentResolver resolver, 
                    Uri parentDocumentUri, 
                    String mimeType, 
                    String displayName)

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

    Parameters
    resolver ContentResolver

    parentDocumentUri Uri: directory with FLAG_DIR_SUPPORTS_CREATE

    mimeType String: MIME type of new document

    displayName String: name of new document

    Returns
    Uri newly created document, or null if failed

    Throws
    FileNotFoundException

    createWebLinkIntent

    added in API level 26
    IntentSender createWebLinkIntent (ContentResolver resolver, 
                    Uri uri, 
                    Bundle options)

    Creates an intent for obtaining a web link for the specified document.

    Note, that due to internal limitations, if there is already a web link intent created for the specified document but with different options, then it may be overriden.

    Providers are required to show confirmation UI for all new permissions granted for the linked document.

    If list of recipients is known, then it should be passed in options as EXTRA_EMAIL as a list of email addresses. Note, that this is just a hint for the provider, which can ignore the list. In either case the provider is required to show a UI for letting the user confirm any new permission grants.

    Note, that the entire options bundle will be sent to the provider backing the passed uri. Make sure that you trust the provider before passing any sensitive information.

    Since this API may show a UI, it cannot be called from background.

    In order to obtain the Web Link use code like this:

    
     void onSomethingHappened() {
       IntentSender sender = DocumentsContract.createWebLinkIntent(...);
       if (sender != null) {
         startIntentSenderForResult(
             sender,
             WEB_LINK_REQUEST_CODE,
             null, 0, 0, 0, null);
       }
     }
    
     (...)
    
     void onActivityResult(int requestCode, int resultCode, Intent data) {
       if (requestCode == WEB_LINK_REQUEST_CODE && resultCode == RESULT_OK) {
         Uri weblinkUri = data.getData();
         ...
       }
     }
     

    Parameters
    resolver ContentResolver

    uri Uri: uri for the document to create a link to.

    options Bundle: Extra information for generating the link.

    Returns
    IntentSender an intent sender to obtain the web link, or null if the document is not linkable, or creating the intent sender failed.

    Throws
    FileNotFoundException

    deleteDocument

    added in API level 19
    boolean deleteDocument (ContentResolver resolver, 
                    Uri documentUri)

    Delete the given document.

    Parameters
    resolver ContentResolver

    documentUri Uri: document with FLAG_SUPPORTS_DELETE

    Returns
    boolean if the document was deleted successfully.

    Throws
    FileNotFoundException

    ejectRoot

    added in API level 26
    void ejectRoot (ContentResolver resolver, 
                    Uri rootUri)

    Ejects the given root. It throws IllegalStateException when ejection failed.

    Parameters
    resolver ContentResolver

    rootUri Uri: root with FLAG_SUPPORTS_EJECT to be ejected

    findDocumentPath

    added in API level 26
    DocumentsContract.Path findDocumentPath (ContentResolver resolver, 
                    Uri treeUri)

    Finds the canonical path from the top of the document tree. The getPath() of the return value contains the document ID of all documents along the path from the top the document tree to the requested document, both inclusive. The getRootId() of the return value returns null.

    Parameters
    resolver ContentResolver

    treeUri Uri: treeUri of the document which path is requested.

    Returns
    DocumentsContract.Path the path of the document, or null if failed.

    Throws
    FileNotFoundException

    getDocumentId

    added in API level 19
    String getDocumentId (Uri documentUri)

    Extract the COLUMN_DOCUMENT_ID from the given URI.

    Parameters
    documentUri Uri

    Returns
    String

    getDocumentThumbnail

    added in API level 19
    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
    resolver ContentResolver

    documentUri Uri: document to return thumbnail for, which must have FLAG_SUPPORTS_THUMBNAIL set.

    size Point: optimal thumbnail size desired. A provider may return a thumbnail of a different size, but never more than double the requested size.

    signal CancellationSignal: signal used to indicate if caller is no longer interested in the thumbnail.

    Returns
    Bitmap decoded thumbnail, or null if problem was encountered.

    Throws
    FileNotFoundException

    getRootId

    added in API level 19
    String getRootId (Uri rootUri)

    Extract the COLUMN_ROOT_ID from the given URI.

    Parameters
    rootUri Uri

    Returns
    String

    getSearchDocumentsQuery

    added in API level 19
    String getSearchDocumentsQuery (Uri searchDocumentsUri)

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

    Parameters
    searchDocumentsUri Uri

    Returns
    String

    getTreeDocumentId

    added in API level 21
    String getTreeDocumentId (Uri documentUri)

    Extract the via COLUMN_DOCUMENT_ID from the given URI.

    Parameters
    documentUri Uri

    Returns
    String

    isDocumentUri

    added in API level 19
    boolean isDocumentUri (Context context, 
                    Uri uri)

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

    Parameters
    context Context

    uri Uri

    This value may be null.

    Returns
    boolean

    isTreeUri

    added in API level 24
    boolean isTreeUri (Uri uri)

    Test if the given URI represents a DocumentsContract.Document tree.

    Parameters
    uri Uri

    Returns
    boolean

    moveDocument

    added in API level 24
    Uri moveDocument (ContentResolver resolver, 
                    Uri sourceDocumentUri, 
                    Uri sourceParentDocumentUri, 
                    Uri targetParentDocumentUri)

    Moves the given document under a new parent.

    Parameters
    resolver ContentResolver

    sourceDocumentUri Uri: document with FLAG_SUPPORTS_MOVE

    sourceParentDocumentUri Uri: parent document of the document to move.

    targetParentDocumentUri Uri: document which will become a new parent of the source document.

    Returns
    Uri the moved document, or null if failed.

    Throws
    FileNotFoundException

    removeDocument

    added in API level 24
    boolean removeDocument (ContentResolver resolver, 
                    Uri documentUri, 
                    Uri parentDocumentUri)

    Removes the given document from a parent directory.

    In contrast to deleteDocument(ContentResolver, Uri) it requires specifying the parent. This method is especially useful if the document can be in multiple parents.

    Parameters
    resolver ContentResolver

    documentUri Uri: document with FLAG_SUPPORTS_REMOVE

    parentDocumentUri Uri: parent document of the document to remove.

    Returns
    boolean true if the document was removed successfully.

    Throws
    FileNotFoundException

    renameDocument

    added in API level 21
    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
    resolver ContentResolver

    documentUri Uri: document with FLAG_SUPPORTS_RENAME

    displayName String: updated name for document

    Returns
    Uri the existing or new document after the rename, or null if failed.

    Throws
    FileNotFoundException
    This site uses cookies to store your preferences for site-specific language and display options.

    Get the latest Android developer news and tips that will help you find success on Google Play.

    * Required Fields

    Hooray!

    Follow Google Developers on WeChat

    Browse this site in ?

    You requested a page in , but your language preference for this site is .

    Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

    This class requires API level or higher

    This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

    For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

    Take a short survey?
    Help us improve the Android developer experience. (Dec 2017 Android Platform & Tools Survey)