DocumentsContract

ACTION_DOCUMENT_SETTINGS

static val ACTION_DOCUMENT_SETTINGS: String

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.

Value: "android.provider.action.DOCUMENT_SETTINGS"

EXTRA_ERROR

static val EXTRA_ERROR: String

Optional string included in a directory Cursor.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.

Value: "error"

EXTRA_EXCLUDE_SELF

static val EXTRA_EXCLUDE_SELF: String

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

Value: "android.provider.extra.EXCLUDE_SELF"

EXTRA_INFO

static val EXTRA_INFO: String

Optional string included in a directory Cursor.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.

Value: "info"

EXTRA_INITIAL_URI

static val EXTRA_INITIAL_URI: String

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

Applicable to Intent with actions:

• Intent.ACTION_OPEN_DOCUMENT
• Intent.ACTION_CREATE_DOCUMENT
• Intent.ACTION_OPEN_DOCUMENT_TREE

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.

Value: "android.provider.extra.INITIAL_URI"

EXTRA_LOADING

static val EXTRA_LOADING: String

Optional boolean flag included in a directory Cursor.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.

Value: "loading"

EXTRA_ORIENTATION

static val EXTRA_ORIENTATION: String

An extra number of degrees that an image should be rotated during the decode process to be presented correctly.

Value: "android.provider.extra.ORIENTATION"

EXTRA_PROMPT

static val EXTRA_PROMPT: String

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

Value: "android.provider.extra.PROMPT"

METADATA_EXIF

static val METADATA_EXIF: String

Get Exif information using DocumentsContract#getDocumentMetadata.

Value: "android:documentExif"

METADATA_TREE_COUNT

static val METADATA_TREE_COUNT: String

Get total count of all documents currently stored under the given directory tree. Only valid for Document.MIME_TYPE_DIR documents.

Value: "android:metadataTreeCount"

METADATA_TREE_SIZE

static val METADATA_TREE_SIZE: String

Get total size of all documents currently stored under the given directory tree. Only valid for Document.MIME_TYPE_DIR documents.

Value: "android:metadataTreeSize"

METADATA_TYPES

static val METADATA_TYPES: String

Get string array identifies the type or types of metadata returned using DocumentsContract#getDocumentMetadata.

Value: "android:documentMetadataTypes"

PROVIDER_INTERFACE

static val PROVIDER_INTERFACE: String

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

Value: "android.content.action.DOCUMENTS_PROVIDER"

QUERY_ARG_DISPLAY_NAME

static val QUERY_ARG_DISPLAY_NAME: String

Key for DocumentsProvider to query display name is matched. The match of display name is partial matching and case-insensitive. Ex: The value is "o", the display name of the results will contain both "foo" and "Open".

Value: "android:query-arg-display-name"

QUERY_ARG_EXCLUDE_MEDIA

static val QUERY_ARG_EXCLUDE_MEDIA: String

Key for DocumentsProvider to decide whether the files that have been added to MediaStore should be excluded. If the value is true, exclude them. Otherwise, include them.

Value: "android:query-arg-exclude-media"

QUERY_ARG_FILE_SIZE_OVER

static val QUERY_ARG_FILE_SIZE_OVER: String

Key for DocumentsProvider to query the file size in bytes is larger than the value.

Value: "android:query-arg-file-size-over"

QUERY_ARG_LAST_MODIFIED_AFTER

static val QUERY_ARG_LAST_MODIFIED_AFTER: String

Key for DocumentsProvider to query the last modified time is newer than the value. The unit is in milliseconds since January 1, 1970 00:00:00.0 UTC.

Value: "android:query-arg-last-modified-after"

QUERY_ARG_MIME_TYPES

static val QUERY_ARG_MIME_TYPES: String

Key for DocumentsProvider to query mime types is matched. The value is a string array, it can support different mime types. Each items will be treated as "OR" condition. Ex: {"image/*" , "video/*"}. The mime types of the results will contain both image type and video type.

Value: "android:query-arg-mime-types"

buildChildDocumentsUri

static fun buildChildDocumentsUri(
    authority: String!, 
    parentDocumentId: String!
): Uri!

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

buildChildDocumentsUriUsingTree

static fun buildChildDocumentsUriUsingTree(
    treeUri: Uri!, 
    parentDocumentId: String!
): Uri!

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

However, instead of directly accessing the target directory, the returned URI will leverage access granted through a subtree URI, typically returned by Intent.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.

buildDocumentUri

static fun buildDocumentUri(
    authority: String!, 
    documentId: String!
): Uri!

Build URI representing the target Document.COLUMN_DOCUMENT_ID in a document provider. When queried, a provider will return a single row with columns defined by Document.

buildDocumentUriUsingTree

static fun buildDocumentUriUsingTree(
    treeUri: Uri!, 
    documentId: String!
): Uri!

Build URI representing the target Document.COLUMN_DOCUMENT_ID in a document provider. When queried, a provider will return a single row with columns defined by Document.

However, instead of directly accessing the target document, the returned URI will leverage access granted through a subtree URI, typically returned by Intent.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.

buildRecentDocumentsUri

static fun buildRecentDocumentsUri(
    authority: String!, 
    rootId: String!
): Uri!

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

buildRootUri

static fun buildRootUri(
    authority: String!, 
    rootId: String!
): Uri!

Build URI representing the given Root.COLUMN_ROOT_ID in a document provider.

buildRootsUri

static fun buildRootsUri(authority: String!): Uri!

Build URI representing the roots of a document provider. When queried, a provider will return one or more rows with columns defined by Root.

buildSearchDocumentsUri

static fun buildSearchDocumentsUri(
    authority: String!, 
    rootId: String!, 
    query: String!
): Uri!

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

buildTreeDocumentUri

static fun buildTreeDocumentUri(
    authority: String!, 
    documentId: String!
): Uri!

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

copyDocument

static fun copyDocument(
    content: ContentResolver, 
    sourceDocumentUri: Uri, 
    targetParentDocumentUri: Uri
): Uri?

Copies the given document.

createDocument

static fun createDocument(
    content: ContentResolver, 
    parentDocumentUri: Uri, 
    mimeType: String, 
    displayName: String
): Uri?

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

createWebLinkIntent

static fun createWebLinkIntent(
    content: ContentResolver, 
    uri: Uri, 
    options: Bundle?
): IntentSender?

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

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 Intent.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:

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

deleteDocument

static fun deleteDocument(
    content: ContentResolver, 
    documentUri: Uri
): Boolean

Delete the given document.

ejectRoot

static fun ejectRoot(
    content: ContentResolver, 
    rootUri: Uri
): Unit

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

findDocumentPath

static fun findDocumentPath(
    content: ContentResolver, 
    treeUri: Uri
): DocumentsContract.Path?

Finds the canonical path from the top of the document tree. The Path.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 Path.getRootId() of the return value returns null.

getDocumentId

static fun getDocumentId(documentUri: Uri!): String!

Extract the Document.COLUMN_DOCUMENT_ID from the given URI.

getDocumentMetadata

static fun getDocumentMetadata(
    content: ContentResolver, 
    documentUri: Uri
): Bundle?

Returns metadata associated with the document. The type of metadata returned is specific to the document type. For example the data returned for an image file will likely consist primarily or solely of EXIF metadata.

The returned Bundle will contain zero or more entries depending on the type of data supported by the document provider.

1. A DocumentsContract.METADATA_TYPES containing a String[] value. The string array identifies the type or types of metadata returned. Each value in the can be used to access a Bundle of data containing that type of data.
2. An entry each for each type of returned metadata. Each set of metadata is itself represented as a bundle and accessible via a string key naming the type of data.

Example:

<code>
      Bundle metadata = DocumentsContract.getDocumentMetadata(client, imageDocUri, tags);
      if (metadata.containsKey(DocumentsContract.METADATA_EXIF)) {
          Bundle exif = metadata.getBundle(DocumentsContract.METADATA_EXIF);
          int imageLength = exif.getInt(ExifInterface.TAG_IMAGE_LENGTH);
      }
  </code>

getDocumentThumbnail

static fun getDocumentThumbnail(
    content: ContentResolver, 
    documentUri: Uri, 
    size: Point, 
    signal: CancellationSignal?
): Bitmap?

Return thumbnail representing the document at the given URI. Callers are responsible for their own in-memory caching.

getRootId

static fun getRootId(rootUri: Uri!): String!

Extract the Root.COLUMN_ROOT_ID from the given URI.

getSearchDocumentsQuery

static fun getSearchDocumentsQuery(searchDocumentsUri: Uri!): String!

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

getTreeDocumentId

static fun getTreeDocumentId(documentUri: Uri!): String!

Extract the via Document.COLUMN_DOCUMENT_ID from the given URI.

isChildDocument

static fun isChildDocument(
    content: ContentResolver, 
    parentDocumentUri: Uri, 
    childDocumentUri: Uri
): Boolean

Test if a document is descendant (child, grandchild, etc) from the given parent.

isDocumentUri

static fun isDocumentUri(
    context: Context!, 
    uri: Uri?
): Boolean

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

isRootUri

static fun isRootUri(
    context: Context, 
    uri: Uri?
): Boolean

Test if the given URI represents specific root backed by DocumentsProvider.

isRootsUri

static fun isRootsUri(
    context: Context, 
    uri: Uri?
): Boolean

Test if the given URI represents all roots of the authority backed by DocumentsProvider.

isTreeUri

static fun isTreeUri(uri: Uri!): Boolean

Test if the given URI represents a Document tree.

moveDocument

static fun moveDocument(
    content: ContentResolver, 
    sourceDocumentUri: Uri, 
    sourceParentDocumentUri: Uri, 
    targetParentDocumentUri: Uri
): Uri?

Moves the given document under a new parent.

removeDocument

static fun removeDocument(
    content: ContentResolver, 
    documentUri: Uri, 
    parentDocumentUri: Uri
): Boolean

Removes the given document from a parent directory.

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

renameDocument

static fun renameDocument(
    content: ContentResolver, 
    documentUri: Uri, 
    displayName: String
): Uri?

Change the display name of an existing document.

If the underlying provider needs to create a new Document.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.