diff options
| -rw-r--r-- | core/java/android/provider/DocumentsProvider.java | 77 |
1 files changed, 47 insertions, 30 deletions
diff --git a/core/java/android/provider/DocumentsProvider.java b/core/java/android/provider/DocumentsProvider.java index c9efb53a959d..e35b8eb42528 100644 --- a/core/java/android/provider/DocumentsProvider.java +++ b/core/java/android/provider/DocumentsProvider.java @@ -76,9 +76,8 @@ import java.io.FileNotFoundException; * only the system can obtain. Applications cannot use a documents provider * directly; they must go through {@link Intent#ACTION_OPEN_DOCUMENT} or * {@link Intent#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. + * navigate and select documents. When a user selects documents through that UI, + * the system issues narrow URI permission grants to the requesting application. * </p> * <h3>Documents</h3> * <p> @@ -91,8 +90,8 @@ import java.io.FileNotFoundException; * <p> * Each document can have different capabilities, as described by * {@link Document#COLUMN_FLAGS}. For example, if a document can be represented - * as a thumbnail, a provider can set {@link Document#FLAG_SUPPORTS_THUMBNAIL} - * and implement + * as a thumbnail, your provider can set + * {@link Document#FLAG_SUPPORTS_THUMBNAIL} and implement * {@link #openDocumentThumbnail(String, Point, CancellationSignal)} to return * that thumbnail. * </p> @@ -102,7 +101,7 @@ import java.io.FileNotFoundException; * single document can be included in multiple directories when responding to * {@link #queryChildDocuments(String, String[], String)}. For example, a * provider might surface a single photo in multiple locations: once in a - * directory of locations, and again in a directory of dates. + * directory of geographic locations, and again in a directory of dates. * </p> * <h3>Roots</h3> * <p> @@ -162,7 +161,7 @@ public abstract class DocumentsProvider extends ContentProvider { /** * Create a new document and return its newly generated - * {@link Document#COLUMN_DOCUMENT_ID}. A provider must allocate a new + * {@link Document#COLUMN_DOCUMENT_ID}. You must allocate a new * {@link Document#COLUMN_DOCUMENT_ID} to represent the document, which must * not change once returned. * @@ -194,16 +193,17 @@ public abstract class DocumentsProvider extends ContentProvider { } /** - * Return all roots currently provided. A provider must define at least one - * root to display to users, and it should avoid making network requests to - * keep this request fast. + * 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. * <p> * Each root is defined by the metadata columns described in {@link Root}, * including {@link Root#COLUMN_DOCUMENT_ID} which points to a directory * representing a tree of documents to display under that root. * <p> * If this set of roots changes, you must call {@link ContentResolver#notifyChange(Uri, - * android.database.ContentObserver)} to notify the system. + * android.database.ContentObserver, boolean)} with + * {@link DocumentsContract#buildRootsUri(String)} to notify the system. * * @param projection list of {@link Root} columns to put into the cursor. If * {@code null} all supported columns should be included. @@ -229,8 +229,8 @@ public abstract class DocumentsProvider extends ContentProvider { } /** - * Return metadata for the single requested document. A provider should - * avoid making network requests to keep this request fast. + * Return metadata for the single requested document. You should avoid + * making network requests to keep this request fast. * * @param documentId the document to return. * @param projection list of {@link Document} columns to put into the @@ -248,10 +248,17 @@ public abstract class DocumentsProvider extends ContentProvider { * If your provider is cloud-based, and you have some data cached or pinned * locally, you may return the local data immediately, setting * {@link DocumentsContract#EXTRA_LOADING} on the Cursor to indicate that - * your provider is still fetching additional data. Then, when the network - * data is available, you can call {@link ContentResolver#notifyChange(Uri, - * android.database.ContentObserver)} to trigger a requery and return the - * complete contents. + * 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. + * <p> + * To support change notifications, you must + * {@link Cursor#setNotificationUri(ContentResolver, Uri)} with a relevant + * Uri, such as + * {@link DocumentsContract#buildChildDocumentsUri(String, String)}. Then + * you can call {@link ContentResolver#notifyChange(Uri, + * android.database.ContentObserver, boolean)} with that Uri to send change + * notifications. * * @param parentDocumentId the directory to return children for. * @param projection list of {@link Document} columns to put into the @@ -289,6 +296,20 @@ public abstract class DocumentsProvider extends ContentProvider { * <p> * Only documents may be returned; directories are not supported in search * results. + * <p> + * If your provider is cloud-based, and you have some data cached or pinned + * locally, you may return the local data immediately, setting + * {@link DocumentsContract#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. + * <p> + * To support change notifications, you must + * {@link Cursor#setNotificationUri(ContentResolver, Uri)} with a relevant + * Uri, such as {@link DocumentsContract#buildSearchDocumentsUri(String, + * String, String)}. Then you can call {@link ContentResolver#notifyChange(Uri, + * android.database.ContentObserver, boolean)} with that Uri to send change + * notifications. * * @param rootId the root to search under. * @param query string to match documents against. @@ -327,17 +348,14 @@ public abstract class DocumentsProvider extends ContentProvider { /** * Open and return the requested document. * <p> - * A provider should return a reliable {@link ParcelFileDescriptor} to + * Your provider should return a reliable {@link ParcelFileDescriptor} to * detect when the remote caller has finished reading or writing the - * document. A provider may return a pipe or socket pair if the mode is - * exclusively {@link ParcelFileDescriptor#MODE_READ_ONLY} or - * {@link ParcelFileDescriptor#MODE_WRITE_ONLY}, but complex modes like - * {@link ParcelFileDescriptor#MODE_READ_WRITE} require a normal file on - * disk. + * 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. * <p> - * If a provider blocks while downloading content, it should periodically - * check {@link CancellationSignal#isCanceled()} to abort abandoned open - * requests. + * If you block while downloading content, you should periodically check + * {@link CancellationSignal#isCanceled()} to abort abandoned open requests. * * @param documentId the document to return. * @param mode the mode to open with, such as 'r', 'w', or 'rw'. @@ -359,10 +377,9 @@ public abstract class DocumentsProvider extends ContentProvider { * attempting to serve from a local cache if possible. A provider should * never return images more than double the hinted size. * <p> - * If a provider performs expensive operations to download or generate a - * thumbnail, it should periodically check - * {@link CancellationSignal#isCanceled()} to abort abandoned thumbnail - * requests. + * If you perform expensive operations to download or generate a thumbnail, + * you should periodically check {@link CancellationSignal#isCanceled()} to + * abort abandoned thumbnail requests. * * @param documentId the document to return. * @param sizeHint hint of the optimal thumbnail dimensions. |