Define storage roots, external GUIDs, creation.

Allow storage backends to publish multiple roots into the UI, which
are defined by a directory GUID, type, and label details.  Update
external provider to surface a primary external storage root, and
switch to burning file path into the returned GUIDs so they remain
durable.

Added insert, update, and delete support to external provider. Adds
file extensions to display names when needed to match MIME type.

Add flags for searching and deletion, and extras for Cursor
pagination. Add directory creation dialog to UI. Opening a document
always gives write access.

Change-Id: I9bea1aa0dcde909a5ab86aefeece7451ab920cf1

1 files changed, 127 insertions, 11 deletions

diff --git a/core/java/android/provider/DocumentsContract.java b/core/java/android/provider/DocumentsContract.java
index c26f6d4..979a5a3 100644
--- a/core/java/android/provider/DocumentsContract.java
+++ b/core/java/android/provider/DocumentsContract.java
@@ -16,10 +16,13 @@
 
 package android.provider;
 
+import android.content.ContentProvider;
 import android.content.ContentResolver;
 import android.content.ContentValues;
 import android.content.Intent;
+import android.content.pm.ProviderInfo;
 import android.content.res.AssetFileDescriptor;
+import android.database.Cursor;
 import android.graphics.Bitmap;
 import android.graphics.BitmapFactory;
 import android.graphics.Point;
@@ -39,9 +42,10 @@ import java.io.InputStream;
 public final class DocumentsContract {
     private static final String TAG = "Documents";
 
+    // content://com.example/roots/
     // content://com.example/docs/0/
     // content://com.example/docs/0/contents/
-    // content://com.example/search/?query=pony
+    // content://com.example/docs/0/search/?query=pony
 
     /**
      * MIME type of a document which is a directory that may contain additional
@@ -78,25 +82,69 @@ public final class DocumentsContract {
     public static final int FLAG_SUPPORTS_RENAME = 1 << 1;
 
     /**
+     * Flag indicating that a document is deletable.
+     *
+     * @see DocumentColumns#FLAGS
+     */
+    public static final int FLAG_SUPPORTS_DELETE = 1 << 2;
+
+    /**
      * Flag indicating that a document can be represented as a thumbnail.
      *
      * @see DocumentColumns#FLAGS
      * @see #getThumbnail(ContentResolver, Uri, Point)
      */
-    public static final int FLAG_SUPPORTS_THUMBNAIL = 1 << 2;
+    public static final int FLAG_SUPPORTS_THUMBNAIL = 1 << 3;
+
+    /**
+     * Flag indicating that a document is a directory that supports search.
+     *
+     * @see DocumentColumns#FLAGS
+     */
+    public static final int FLAG_SUPPORTS_SEARCH = 1 << 4;
 
     /**
      * Optimal dimensions for a document thumbnail request, stored as a
      * {@link Point} object. This is only a hint, and the returned thumbnail may
      * have different dimensions.
+     *
+     * @see ContentProvider#openTypedAssetFile(Uri, String, Bundle)
      */
     public static final String EXTRA_THUMBNAIL_SIZE = "thumbnail_size";
 
+    /**
+     * Extra boolean flag included in a directory {@link Cursor#getExtras()}
+     * indicating that the backend can provide additional data if requested,
+     * such as additional search results.
+     */
+    public static final String EXTRA_HAS_MORE = "has_more";
+
+    /**
+     * Extra boolean flag included in a {@link Cursor#respond(Bundle)} call to a
+     * directory to request that additional data should be fetched. When
+     * requested data is ready, the provider should send a change notification
+     * to cause a requery.
+     *
+     * @see Cursor#respond(Bundle)
+     * @see ContentResolver#notifyChange(Uri, android.database.ContentObserver,
+     *      boolean)
+     */
+    public static final String EXTRA_REQUEST_MORE = "request_more";
+
+    private static final String PATH_ROOTS = "roots";
     private static final String PATH_DOCS = "docs";
     private static final String PATH_CONTENTS = "contents";
     private static final String PATH_SEARCH = "search";
 
-    private static final String PARAM_QUERY = "query";
+    public static final String PARAM_QUERY = "query";
+
+    /**
+     * Build URI representing the custom roots in a storage backend.
+     */
+    public static Uri buildRootsUri(String authority) {
+        return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT)
+                .authority(authority).appendPath(PATH_ROOTS).build();
+    }
 
     /**
      * Build URI representing the given {@link DocumentColumns#GUID} in a
@@ -108,11 +156,14 @@ public final class DocumentsContract {
     }
 
     /**
-     * Build URI representing a search for matching documents in a storage
-     * backend.
+     * Build URI representing a search for matching documents under a directory
+     * in a storage backend.
+     *
+     * @param documentUri directory to search under, which must have
+     *            {@link #FLAG_SUPPORTS_SEARCH}.
      */
-    public static Uri buildSearchUri(String authority, String query) {
-        return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT).authority(authority)
+    public static Uri buildSearchUri(Uri documentUri, String query) {
+        return documentUri.buildUpon()
                 .appendPath(PATH_SEARCH).appendQueryParameter(PARAM_QUERY, query).build();
     }
 
@@ -134,7 +185,8 @@ public final class DocumentsContract {
     public interface DocumentColumns extends OpenableColumns {
         /**
          * The globally unique ID for a document within a storage backend.
-         * Values <em>must</em> never change once returned.
+         * Values <em>must</em> never change once returned. This field is
+         * read-only to document clients.
          * <p>
          * Type: STRING
          *
@@ -144,7 +196,9 @@ public final class DocumentsContract {
 
         /**
          * MIME type of a document, matching the value returned by
-         * {@link ContentResolver#getType(android.net.Uri)}.
+         * {@link ContentResolver#getType(android.net.Uri)}. This field must be
+         * provided when a new document is created, but after that the field is
+         * read-only.
          * <p>
          * Type: STRING
          *
@@ -154,7 +208,8 @@ public final class DocumentsContract {
 
         /**
          * Timestamp when a document was last modified, in milliseconds since
-         * January 1, 1970 00:00:00.0 UTC.
+         * January 1, 1970 00:00:00.0 UTC. This field is read-only to document
+         * clients.
          * <p>
          * Type: INTEGER (long)
          *
@@ -163,13 +218,74 @@ public final class DocumentsContract {
         public static final String LAST_MODIFIED = "last_modified";
 
         /**
-         * Flags that apply to a specific document.
+         * Flags that apply to a specific document. This field is read-only to
+         * document clients.
          * <p>
          * Type: INTEGER (int)
          */
         public static final String FLAGS = "flags";
     }
 
+    public static final int ROOT_TYPE_SERVICE = 1;
+    public static final int ROOT_TYPE_SHORTCUT = 2;
+    public static final int ROOT_TYPE_DEVICE = 3;
+    public static final int ROOT_TYPE_DEVICE_ADVANCED = 4;
+
+    /**
+     * These are standard columns for the roots URI.
+     *
+     * @see DocumentsContract#buildRootsUri(String)
+     */
+    public interface RootColumns {
+        /**
+         * Storage root type, use for clustering.
+         * <p>
+         * Type: INTEGER (int)
+         *
+         * @see DocumentsContract#ROOT_TYPE_SERVICE
+         * @see DocumentsContract#ROOT_TYPE_DEVICE
+         */
+        public static final String ROOT_TYPE = "root_type";
+
+        /**
+         * GUID of directory entry for this storage root.
+         * <p>
+         * Type: STRING
+         */
+        public static final String GUID = "guid";
+
+        /**
+         * Icon resource ID for this storage root, or {@code 0} to use the
+         * default {@link ProviderInfo#icon}.
+         * <p>
+         * Type: INTEGER (int)
+         */
+        public static final String ICON = "icon";
+
+        /**
+         * Title for this storage root, or {@code null} to use the default
+         * {@link ProviderInfo#labelRes}.
+         * <p>
+         * Type: STRING
+         */
+        public static final String TITLE = "title";
+
+        /**
+         * Summary for this storage root, or {@code null} to omit.
+         * <p>
+         * Type: STRING
+         */
+        public static final String SUMMARY = "summary";
+
+        /**
+         * Number of free bytes of available in this storage root, or -1 if
+         * unknown or unbounded.
+         * <p>
+         * Type: INTEGER (long)
+         */
+        public static final String AVAILABLE_BYTES = "available_bytes";
+    }
+
     /**
      * Return thumbnail representing the document at the given URI. Callers are
      * responsible for their own caching. Given document must have