* To create a document provider, extend {@link 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
* {@link Intent#ACTION_OPEN_DOCUMENT}, {@link Intent#ACTION_CREATE_DOCUMENT},
* or {@link Intent#ACTION_OPEN_DOCUMENT_TREE}.
*
* @see DocumentsProvider
*/
public final class DocumentsContract {
private static final String TAG = "Documents";
// content://com.example/root/
// content://com.example/root/sdcard/
// content://com.example/root/sdcard/recent/
// content://com.example/root/sdcard/search/?query=pony
// content://com.example/document/12/
// content://com.example/document/12/children/
// content://com.example/tree/12/document/24/
// content://com.example/tree/12/document/24/children/
private DocumentsContract() {
}
/**
* Intent action used to identify {@link DocumentsProvider} instances. This
* is used in the {@code
* A document can be either an openable stream (with a specific MIME type),
* or a directory containing additional documents (with the
* {@link #MIME_TYPE_DIR} MIME type). A directory represents the top of a
* subtree containing zero or more documents, which can recursively contain
* even more documents and directories.
*
* All columns are read-only to client applications.
*/
public final static class Document {
private Document() {
}
/**
* Unique ID of a document. This ID is both provided by and interpreted
* by a {@link DocumentsProvider}, and should be treated as an opaque
* value by client applications. This column is required.
*
* Each document must have a unique ID within a provider, but that
* single document may be included as a child of multiple directories.
*
* A provider must always return durable IDs, since they will be used to
* issue long-term URI permission grants when an application interacts
* with {@link Intent#ACTION_OPEN_DOCUMENT} and
* {@link Intent#ACTION_CREATE_DOCUMENT}.
*
* Type: STRING
*/
public static final String COLUMN_DOCUMENT_ID = "document_id";
/**
* Concrete MIME type of a document. For example, "image/png" or
* "application/pdf" for openable files. A document can also be a
* directory containing additional documents, which is represented with
* the {@link #MIME_TYPE_DIR} MIME type. This column is required.
*
* Type: STRING
*
* @see #MIME_TYPE_DIR
*/
public static final String COLUMN_MIME_TYPE = "mime_type";
/**
* Display name of a document, used as the primary title displayed to a
* user. This column is required.
*
* Type: STRING
*/
public static final String COLUMN_DISPLAY_NAME = OpenableColumns.DISPLAY_NAME;
/**
* Summary of a document, which may be shown to a user. This column is
* optional, and may be {@code null}.
*
* Type: STRING
*/
public static final String COLUMN_SUMMARY = "summary";
/**
* Timestamp when a document was last modified, in milliseconds since
* January 1, 1970 00:00:00.0 UTC. This column is required, and may be
* {@code null} if unknown. A {@link DocumentsProvider} can update this
* field using events from {@link OnCloseListener} or other reliable
* {@link ParcelFileDescriptor} transports.
*
* Type: INTEGER (long)
*
* @see System#currentTimeMillis()
*/
public static final String COLUMN_LAST_MODIFIED = "last_modified";
/**
* Specific icon resource ID for a document. This column is optional,
* and may be {@code null} to use a platform-provided default icon based
* on {@link #COLUMN_MIME_TYPE}.
*
* Type: INTEGER (int)
*/
public static final String COLUMN_ICON = "icon";
/**
* Flags that apply to a document. This column is required.
*
* Type: INTEGER (int)
*
* @see #FLAG_SUPPORTS_WRITE
* @see #FLAG_SUPPORTS_DELETE
* @see #FLAG_SUPPORTS_THUMBNAIL
* @see #FLAG_DIR_PREFERS_GRID
* @see #FLAG_DIR_PREFERS_LAST_MODIFIED
*/
public static final String COLUMN_FLAGS = "flags";
/**
* Size of a document, in bytes, or {@code null} if unknown. This column
* is required.
*
* Type: INTEGER (long)
*/
public static final String COLUMN_SIZE = OpenableColumns.SIZE;
/**
* MIME type of a document which is a directory that may contain
* additional documents.
*
* @see #COLUMN_MIME_TYPE
*/
public static final String MIME_TYPE_DIR = "vnd.android.document/directory";
/**
* Flag indicating that a document can be represented as a thumbnail.
*
* @see #COLUMN_FLAGS
* @see DocumentsContract#getDocumentThumbnail(ContentResolver, Uri,
* Point, CancellationSignal)
* @see DocumentsProvider#openDocumentThumbnail(String, Point,
* android.os.CancellationSignal)
*/
public static final int FLAG_SUPPORTS_THUMBNAIL = 1;
/**
* Flag indicating that a document supports writing.
*
* When a document is opened with {@link Intent#ACTION_OPEN_DOCUMENT},
* the calling application is granted both
* {@link Intent#FLAG_GRANT_READ_URI_PERMISSION} and
* {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION}. However, the actual
* writability of a document may change over time, for example due to
* remote access changes. This flag indicates that a document client can
* expect {@link ContentResolver#openOutputStream(Uri)} to succeed.
*
* @see #COLUMN_FLAGS
*/
public static final int FLAG_SUPPORTS_WRITE = 1 << 1;
/**
* Flag indicating that a document is deletable.
*
* @see #COLUMN_FLAGS
* @see DocumentsContract#deleteDocument(ContentResolver, Uri)
* @see DocumentsProvider#deleteDocument(String)
*/
public static final int FLAG_SUPPORTS_DELETE = 1 << 2;
/**
* Flag indicating that a document is a directory that supports creation
* of new files within it. Only valid when {@link #COLUMN_MIME_TYPE} is
* {@link #MIME_TYPE_DIR}.
*
* @see #COLUMN_FLAGS
* @see DocumentsProvider#createDocument(String, String, String)
*/
public static final int FLAG_DIR_SUPPORTS_CREATE = 1 << 3;
/**
* Flag indicating that a directory prefers its contents be shown in a
* larger format grid. Usually suitable when a directory contains mostly
* pictures. Only valid when {@link #COLUMN_MIME_TYPE} is
* {@link #MIME_TYPE_DIR}.
*
* @see #COLUMN_FLAGS
*/
public static final int FLAG_DIR_PREFERS_GRID = 1 << 4;
/**
* Flag indicating that a directory prefers its contents be sorted by
* {@link #COLUMN_LAST_MODIFIED}. Only valid when
* {@link #COLUMN_MIME_TYPE} is {@link #MIME_TYPE_DIR}.
*
* @see #COLUMN_FLAGS
*/
public static final int FLAG_DIR_PREFERS_LAST_MODIFIED = 1 << 5;
/**
* Flag indicating that a document can be renamed.
*
* @see #COLUMN_FLAGS
* @see DocumentsContract#renameDocument(ContentProviderClient, Uri,
* String)
* @see DocumentsProvider#renameDocument(String, String)
*/
public static final int FLAG_SUPPORTS_RENAME = 1 << 6;
/**
* Flag indicating that document titles should be hidden when viewing
* this directory in a larger format grid. For example, a directory
* containing only images may want the image thumbnails to speak for
* themselves. Only valid when {@link #COLUMN_MIME_TYPE} is
* {@link #MIME_TYPE_DIR}.
*
* @see #COLUMN_FLAGS
* @see #FLAG_DIR_PREFERS_GRID
* @hide
*/
public static final int FLAG_DIR_HIDE_GRID_TITLES = 1 << 16;
}
/**
* Constants related to a root of documents, including {@link Cursor} column
* names and flags. A root is the start of a tree of documents, such as a
* physical storage device, or an account. Each root starts at the directory
* referenced by {@link Root#COLUMN_DOCUMENT_ID}, which can recursively
* contain both documents and directories.
*
* All columns are read-only to client applications.
*/
public final static class Root {
private Root() {
}
/**
* Unique ID of a root. This ID is both provided by and interpreted by a
* {@link DocumentsProvider}, and should be treated as an opaque value
* by client applications. This column is required.
*
* Type: STRING
*/
public static final String COLUMN_ROOT_ID = "root_id";
/**
* Flags that apply to a root. This column is required.
*
* Type: INTEGER (int)
*
* @see #FLAG_LOCAL_ONLY
* @see #FLAG_SUPPORTS_CREATE
* @see #FLAG_SUPPORTS_RECENTS
* @see #FLAG_SUPPORTS_SEARCH
*/
public static final String COLUMN_FLAGS = "flags";
/**
* Icon resource ID for a root. This column is required.
*
* Type: INTEGER (int)
*/
public static final String COLUMN_ICON = "icon";
/**
* Title for a root, which will be shown to a user. This column is
* required. For a single storage service surfacing multiple accounts as
* different roots, this title should be the name of the service.
*
* Type: STRING
*/
public static final String COLUMN_TITLE = "title";
/**
* Summary for this root, which may be shown to a user. This column is
* optional, and may be {@code null}. For a single storage service
* surfacing multiple accounts as different roots, this summary should
* be the name of the account.
*
* Type: STRING
*/
public static final String COLUMN_SUMMARY = "summary";
/**
* Document which is a directory that represents the top directory of
* this root. This column is required.
*
* Type: STRING
*
* @see Document#COLUMN_DOCUMENT_ID
*/
public static final String COLUMN_DOCUMENT_ID = "document_id";
/**
* Number of bytes available in this root. This column is optional, and
* may be {@code null} if unknown or unbounded.
*
* Type: INTEGER (long)
*/
public static final String COLUMN_AVAILABLE_BYTES = "available_bytes";
/**
* MIME types supported by this root. This column is optional, and if
* {@code null} the root is assumed to support all MIME types. Multiple
* MIME types can be separated by a newline. For example, a root
* supporting audio might return "audio/*\napplication/x-flac".
*
* Type: STRING
*/
public static final String COLUMN_MIME_TYPES = "mime_types";
/** {@hide} */
public static final String MIME_TYPE_ITEM = "vnd.android.document/root";
/**
* Flag indicating that at least one directory under this root supports
* creating content. Roots with this flag will be shown when an
* application interacts with {@link Intent#ACTION_CREATE_DOCUMENT}.
*
* @see #COLUMN_FLAGS
*/
public static final int FLAG_SUPPORTS_CREATE = 1;
/**
* Flag indicating that this root offers content that is strictly local
* on the device. That is, no network requests are made for the content.
*
* @see #COLUMN_FLAGS
* @see Intent#EXTRA_LOCAL_ONLY
*/
public static final int FLAG_LOCAL_ONLY = 1 << 1;
/**
* Flag indicating that this root can be queried to provide recently
* modified documents.
*
* @see #COLUMN_FLAGS
* @see DocumentsContract#buildRecentDocumentsUri(String, String)
* @see DocumentsProvider#queryRecentDocuments(String, String[])
*/
public static final int FLAG_SUPPORTS_RECENTS = 1 << 2;
/**
* Flag indicating that this root supports search.
*
* @see #COLUMN_FLAGS
* @see DocumentsContract#buildSearchDocumentsUri(String, String,
* String)
* @see DocumentsProvider#querySearchDocuments(String, String,
* String[])
*/
public static final int FLAG_SUPPORTS_SEARCH = 1 << 3;
/**
* Flag indicating that this root supports testing parent child
* relationships.
*
* @see #COLUMN_FLAGS
* @see DocumentsProvider#isChildDocument(String, String)
*/
public static final int FLAG_SUPPORTS_IS_CHILD = 1 << 4;
/**
* Flag indicating that this root is currently empty. This may be used
* to hide the root when opening documents, but the root will still be
* shown when creating documents and {@link #FLAG_SUPPORTS_CREATE} is
* also set. If the value of this flag changes, such as when a root
* becomes non-empty, you must send a content changed notification for
* {@link DocumentsContract#buildRootsUri(String)}.
*
* @see #COLUMN_FLAGS
* @see ContentResolver#notifyChange(Uri,
* android.database.ContentObserver, boolean)
* @hide
*/
public static final int FLAG_EMPTY = 1 << 16;
/**
* Flag indicating that this root should only be visible to advanced
* users.
*
* @see #COLUMN_FLAGS
* @hide
*/
public static final int FLAG_ADVANCED = 1 << 17;
}
/**
* Optional boolean flag included in a directory {@link 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.
*
* @see ContentResolver#notifyChange(Uri, android.database.ContentObserver,
* boolean)
*/
public static final String EXTRA_LOADING = "loading";
/**
* Optional string included in a directory {@link 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.
*/
public static final String EXTRA_INFO = "info";
/**
* Optional string included in a directory {@link 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.
*/
public static final String EXTRA_ERROR = "error";
/** {@hide} */
public static final String METHOD_CREATE_DOCUMENT = "android:createDocument";
/** {@hide} */
public static final String METHOD_RENAME_DOCUMENT = "android:renameDocument";
/** {@hide} */
public static final String METHOD_DELETE_DOCUMENT = "android:deleteDocument";
/** {@hide} */
public static final String EXTRA_URI = "uri";
private static final String PATH_ROOT = "root";
private static final String PATH_RECENT = "recent";
private static final String PATH_DOCUMENT = "document";
private static final String PATH_CHILDREN = "children";
private static final String PATH_SEARCH = "search";
private static final String PATH_TREE = "tree";
private static final String PARAM_QUERY = "query";
private static final String PARAM_MANAGE = "manage";
/**
* Build URI representing the roots of a document provider. When queried, a
* provider will return one or more rows with columns defined by
* {@link Root}.
*
* @see DocumentsProvider#queryRoots(String[])
*/
public static Uri buildRootsUri(String authority) {
return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT)
.authority(authority).appendPath(PATH_ROOT).build();
}
/**
* Build URI representing the given {@link Root#COLUMN_ROOT_ID} in a
* document provider.
*
* @see #getRootId(Uri)
*/
public static Uri buildRootUri(String authority, String rootId) {
return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT)
.authority(authority).appendPath(PATH_ROOT).appendPath(rootId).build();
}
/**
* 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 {@link Document}.
*
* @see DocumentsProvider#queryRecentDocuments(String, String[])
* @see #getRootId(Uri)
*/
public static Uri buildRecentDocumentsUri(String authority, String rootId) {
return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT)
.authority(authority).appendPath(PATH_ROOT).appendPath(rootId)
.appendPath(PATH_RECENT).build();
}
/**
* Build URI representing access to descendant documents of the given
* {@link Document#COLUMN_DOCUMENT_ID}.
*
* @see #getTreeDocumentId(Uri)
*/
public static Uri buildTreeDocumentUri(String authority, String documentId) {
return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT).authority(authority)
.appendPath(PATH_TREE).appendPath(documentId).build();
}
/**
* Build URI representing the target {@link Document#COLUMN_DOCUMENT_ID} in
* a document provider. When queried, a provider will return a single row
* with columns defined by {@link Document}.
*
* @see DocumentsProvider#queryDocument(String, String[])
* @see #getDocumentId(Uri)
*/
public static Uri buildDocumentUri(String authority, String documentId) {
return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT)
.authority(authority).appendPath(PATH_DOCUMENT).appendPath(documentId).build();
}
/**
* Build URI representing the target {@link Document#COLUMN_DOCUMENT_ID} in
* a document provider. When queried, a provider will return a single row
* with columns defined by {@link Document}.
*
* However, instead of directly accessing the target document, the returned
* URI will leverage access granted through a subtree URI, typically
* returned by {@link 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.
*
* @param treeUri the subtree to leverage to gain access to the target
* document. The target directory must be a descendant of this
* subtree.
* @param documentId the target document, which the caller may not have
* direct access to.
* @see Intent#ACTION_OPEN_DOCUMENT_TREE
* @see DocumentsProvider#isChildDocument(String, String)
* @see #buildDocumentUri(String, String)
*/
public static Uri buildDocumentUriUsingTree(Uri treeUri, String documentId) {
return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT)
.authority(treeUri.getAuthority()).appendPath(PATH_TREE)
.appendPath(getTreeDocumentId(treeUri)).appendPath(PATH_DOCUMENT)
.appendPath(documentId).build();
}
/** {@hide} */
public static Uri buildDocumentUriMaybeUsingTree(Uri baseUri, String documentId) {
if (isTreeUri(baseUri)) {
return buildDocumentUriUsingTree(baseUri, documentId);
} else {
return buildDocumentUri(baseUri.getAuthority(), documentId);
}
}
/**
* 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 {@link Document}.
*
* @param parentDocumentId the document to return children for, which must
* be a directory with MIME type of
* {@link Document#MIME_TYPE_DIR}.
* @see DocumentsProvider#queryChildDocuments(String, String[], String)
* @see #getDocumentId(Uri)
*/
public static Uri buildChildDocumentsUri(String authority, String parentDocumentId) {
return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT).authority(authority)
.appendPath(PATH_DOCUMENT).appendPath(parentDocumentId).appendPath(PATH_CHILDREN)
.build();
}
/**
* 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 {@link Document}.
*
* However, instead of directly accessing the target directory, the returned
* URI will leverage access granted through a subtree URI, typically
* returned by {@link 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.
*
* @param treeUri the subtree to leverage to gain access to the target
* document. The target directory must be a descendant of this
* subtree.
* @param 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 {@link Document#MIME_TYPE_DIR}.
* @see Intent#ACTION_OPEN_DOCUMENT_TREE
* @see DocumentsProvider#isChildDocument(String, String)
* @see #buildChildDocumentsUri(String, String)
*/
public static Uri buildChildDocumentsUriUsingTree(Uri treeUri, String parentDocumentId) {
return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT)
.authority(treeUri.getAuthority()).appendPath(PATH_TREE)
.appendPath(getTreeDocumentId(treeUri)).appendPath(PATH_DOCUMENT)
.appendPath(parentDocumentId).appendPath(PATH_CHILDREN).build();
}
/**
* 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 {@link Document}.
*
* @see DocumentsProvider#querySearchDocuments(String, String, String[])
* @see #getRootId(Uri)
* @see #getSearchDocumentsQuery(Uri)
*/
public static Uri buildSearchDocumentsUri(
String authority, String rootId, String query) {
return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT).authority(authority)
.appendPath(PATH_ROOT).appendPath(rootId).appendPath(PATH_SEARCH)
.appendQueryParameter(PARAM_QUERY, query).build();
}
/**
* Test if the given URI represents a {@link Document} backed by a
* {@link DocumentsProvider}.
*
* @see #buildDocumentUri(String, String)
* @see #buildDocumentUriUsingTree(Uri, String)
*/
public static boolean isDocumentUri(Context context, Uri uri) {
final List
* If the underlying provider needs to create a new
* {@link 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.
*
* @param documentUri document with {@link Document#FLAG_SUPPORTS_RENAME}
* @param displayName updated name for document
* @return the existing or new document after the rename, or {@code null} if
* failed.
*/
public static Uri renameDocument(ContentResolver resolver, Uri documentUri,
String displayName) {
final ContentProviderClient client = resolver.acquireUnstableContentProviderClient(
documentUri.getAuthority());
try {
return renameDocument(client, documentUri, displayName);
} catch (Exception e) {
Log.w(TAG, "Failed to rename document", e);
return null;
} finally {
ContentProviderClient.releaseQuietly(client);
}
}
/** {@hide} */
public static Uri renameDocument(ContentProviderClient client, Uri documentUri,
String displayName) throws RemoteException {
final Bundle in = new Bundle();
in.putParcelable(DocumentsContract.EXTRA_URI, documentUri);
in.putString(Document.COLUMN_DISPLAY_NAME, displayName);
final Bundle out = client.call(METHOD_RENAME_DOCUMENT, null, in);
final Uri outUri = out.getParcelable(DocumentsContract.EXTRA_URI);
return (outUri != null) ? outUri : documentUri;
}
/**
* Delete the given document.
*
* @param documentUri document with {@link Document#FLAG_SUPPORTS_DELETE}
* @return if the document was deleted successfully.
*/
public static boolean deleteDocument(ContentResolver resolver, Uri documentUri) {
final ContentProviderClient client = resolver.acquireUnstableContentProviderClient(
documentUri.getAuthority());
try {
deleteDocument(client, documentUri);
return true;
} catch (Exception e) {
Log.w(TAG, "Failed to delete document", e);
return false;
} finally {
ContentProviderClient.releaseQuietly(client);
}
}
/** {@hide} */
public static void deleteDocument(ContentProviderClient client, Uri documentUri)
throws RemoteException {
final Bundle in = new Bundle();
in.putParcelable(DocumentsContract.EXTRA_URI, documentUri);
client.call(METHOD_DELETE_DOCUMENT, null, in);
}
/**
* Open the given image for thumbnail purposes, using any embedded EXIF
* thumbnail if available, and providing orientation hints from the parent
* image.
*
* @hide
*/
public static AssetFileDescriptor openImageThumbnail(File file) throws FileNotFoundException {
final ParcelFileDescriptor pfd = ParcelFileDescriptor.open(
file, ParcelFileDescriptor.MODE_READ_ONLY);
Bundle extras = null;
try {
final ExifInterface exif = new ExifInterface(file.getAbsolutePath());
switch (exif.getAttributeInt(ExifInterface.TAG_ORIENTATION, -1)) {
case ExifInterface.ORIENTATION_ROTATE_90:
extras = new Bundle(1);
extras.putInt(EXTRA_ORIENTATION, 90);
break;
case ExifInterface.ORIENTATION_ROTATE_180:
extras = new Bundle(1);
extras.putInt(EXTRA_ORIENTATION, 180);
break;
case ExifInterface.ORIENTATION_ROTATE_270:
extras = new Bundle(1);
extras.putInt(EXTRA_ORIENTATION, 270);
break;
}
final long[] thumb = exif.getThumbnailRange();
if (thumb != null) {
return new AssetFileDescriptor(pfd, thumb[0], thumb[1], extras);
}
} catch (IOException e) {
}
return new AssetFileDescriptor(pfd, 0, AssetFileDescriptor.UNKNOWN_LENGTH, extras);
}
}