Start paving the way for XMP metadata.

The Extensible Metadata Platform (XMP) standard is widely used to
annotate useful information about audio, video, and image files, so
this change starts indexing certain widely-useful fields.

For example, the "document ID" concept is designed to uniquely
identify media items regardless of renaming or trivial metadata
edits over time.  And "original document ID" gives a clean way of
identifying a chain of derivative works.

Finally, the "format" attribute can be used to specify a richer MIME
type that may not be recognizable from a file extension alone.

While we're making changes here, remove several APIs that we've
realized aren't needed for Q, such as "trashing."

Bug: 120791890
Test: atest MediaProviderTests
Test: atest cts/tests/tests/provider/src/android/provider/cts/MediaStore*
Change-Id: I0361dd857aed4c2e2f533685478db1c558a97564

3 files changed, 94 insertions, 9 deletions

diff --git a/api/current.txt b/api/current.txt
index d6f0955dbca9..209f2f50477d 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -38340,11 +38340,7 @@ package android.provider {
     method @NonNull public static String getVolumeName(@NonNull android.net.Uri);
     method @NonNull public static android.provider.MediaStore.PendingSession openPending(@NonNull android.content.Context, @NonNull android.net.Uri);
     method @NonNull public static android.net.Uri setIncludePending(@NonNull android.net.Uri);
-    method @NonNull public static android.net.Uri setIncludeTrashed(@NonNull android.net.Uri);
     method @NonNull public static android.net.Uri setRequireOriginal(@NonNull android.net.Uri);
-    method public static void trash(@NonNull android.content.Context, @NonNull android.net.Uri);
-    method public static void trash(@NonNull android.content.Context, @NonNull android.net.Uri, long);
-    method public static void untrash(@NonNull android.content.Context, @NonNull android.net.Uri);
     field public static final String ACTION_IMAGE_CAPTURE = "android.media.action.IMAGE_CAPTURE";
     field public static final String ACTION_IMAGE_CAPTURE_SECURE = "android.media.action.IMAGE_CAPTURE_SECURE";
     field public static final String ACTION_REVIEW = "android.provider.action.REVIEW";
@@ -38615,14 +38611,14 @@ package android.provider {
   public static interface MediaStore.MediaColumns extends android.provider.BaseColumns {
     field @Deprecated public static final String DATA = "_data";
     field public static final String DATE_ADDED = "date_added";
-    field public static final String DATE_EXPIRES = "date_expires";
     field public static final String DATE_MODIFIED = "date_modified";
     field public static final String DISPLAY_NAME = "_display_name";
-    field public static final String HASH = "_hash";
+    field public static final String DOCUMENT_ID = "document_id";
     field public static final String HEIGHT = "height";
+    field public static final String INSTANCE_ID = "instance_id";
     field public static final String IS_PENDING = "is_pending";
-    field public static final String IS_TRASHED = "is_trashed";
     field public static final String MIME_TYPE = "mime_type";
+    field public static final String ORIGINAL_DOCUMENT_ID = "original_document_id";
     field public static final String OWNER_PACKAGE_NAME = "owner_package_name";
     field public static final String PRIMARY_DIRECTORY = "primary_directory";
     field public static final String SECONDARY_DIRECTORY = "secondary_directory";
diff --git a/api/removed.txt b/api/removed.txt
index 262ffec46de1..f5bd434c3cc0 100644
--- a/api/removed.txt
+++ b/api/removed.txt
@@ -507,6 +507,19 @@ package android.provider {
     field @Deprecated public static final String TIMESTAMP = "timestamp";
   }
 
+  public final class MediaStore {
+    method @Deprecated @NonNull public static android.net.Uri setIncludeTrashed(@NonNull android.net.Uri);
+    method @Deprecated public static void trash(@NonNull android.content.Context, @NonNull android.net.Uri);
+    method @Deprecated public static void trash(@NonNull android.content.Context, @NonNull android.net.Uri, long);
+    method @Deprecated public static void untrash(@NonNull android.content.Context, @NonNull android.net.Uri);
+  }
+
+  public static interface MediaStore.MediaColumns extends android.provider.BaseColumns {
+    field @Deprecated public static final String DATE_EXPIRES = "date_expires";
+    field @Deprecated public static final String HASH = "_hash";
+    field @Deprecated public static final String IS_TRASHED = "is_trashed";
+  }
+
   public static final class Settings.Global extends android.provider.Settings.NameValueTable {
     field @Deprecated public static final String CONTACT_METADATA_SYNC = "contact_metadata_sync";
   }
diff --git a/core/java/android/provider/MediaStore.java b/core/java/android/provider/MediaStore.java
index 67c840006948..edaf7bb055cf 100644
--- a/core/java/android/provider/MediaStore.java
+++ b/core/java/android/provider/MediaStore.java
@@ -543,7 +543,9 @@ public final class MediaStore {
      * @see MediaStore#setIncludeTrashed(Uri)
      * @see MediaStore#trash(Context, Uri)
      * @see MediaStore#untrash(Context, Uri)
+     * @removed
      */
+    @Deprecated
     public static @NonNull Uri setIncludeTrashed(@NonNull Uri uri) {
         return uri.buildUpon().appendQueryParameter(PARAM_INCLUDE_TRASHED, "1").build();
     }
@@ -797,7 +799,9 @@ public final class MediaStore {
      * @see MediaStore#setIncludeTrashed(Uri)
      * @see MediaStore#trash(Context, Uri)
      * @see MediaStore#untrash(Context, Uri)
+     * @removed
      */
+    @Deprecated
     public static void trash(@NonNull Context context, @NonNull Uri uri) {
         trash(context, uri, 48 * DateUtils.HOUR_IN_MILLIS);
     }
@@ -815,7 +819,9 @@ public final class MediaStore {
      * @see MediaStore#setIncludeTrashed(Uri)
      * @see MediaStore#trash(Context, Uri)
      * @see MediaStore#untrash(Context, Uri)
+     * @removed
      */
+    @Deprecated
     public static void trash(@NonNull Context context, @NonNull Uri uri,
             @DurationMillisLong long timeoutMillis) {
         if (timeoutMillis < 0) {
@@ -837,7 +843,9 @@ public final class MediaStore {
      * @see MediaStore#setIncludeTrashed(Uri)
      * @see MediaStore#trash(Context, Uri)
      * @see MediaStore#untrash(Context, Uri)
+     * @removed
      */
+    @Deprecated
     public static void untrash(@NonNull Context context, @NonNull Uri uri) {
         final ContentValues values = new ContentValues();
         values.put(MediaColumns.IS_TRASHED, 0);
@@ -884,7 +892,9 @@ public final class MediaStore {
          * hash is calculated.
          * <p>
          * Type: BLOB
+         * @removed
          */
+        @Deprecated
         public static final String HASH = "_hash";
 
         /**
@@ -921,8 +931,22 @@ public final class MediaStore {
         public static final String DATE_MODIFIED = "date_modified";
 
         /**
-         * The MIME type of the file
-         * <P>Type: TEXT</P>
+         * The MIME type of the media item.
+         * <p>
+         * This is typically defined based on the file extension of the media
+         * item. However, it may be the value of the {@code format} attribute
+         * defined by the <em>Dublin Core Media Initiative</em> standard,
+         * extracted from any XMP metadata contained within this media item.
+         * <p class="note">
+         * Note: the {@code format} attribute may be ignored if the top-level
+         * MIME type disagrees with the file extension. For example, it's
+         * reasonable for an {@code image/jpeg} file to declare a {@code format}
+         * of {@code image/vnd.google.panorama360+jpg}, but declaring a
+         * {@code format} of {@code audio/ogg} would be ignored.
+         * <p>
+         * This is a read-only column that is automatically computed.
+         * <p>
+         * Type: TEXT
          */
         public static final String MIME_TYPE = "mime_type";
 
@@ -965,7 +989,9 @@ public final class MediaStore {
          * @see MediaStore#setIncludeTrashed(Uri)
          * @see MediaStore#trash(Context, Uri)
          * @see MediaStore#untrash(Context, Uri)
+         * @removed
          */
+        @Deprecated
         public static final String IS_TRASHED = "is_trashed";
 
         /**
@@ -974,7 +1000,9 @@ public final class MediaStore {
          * {@link #IS_PENDING} or {@link #IS_TRASHED}.
          * <p>
          * Type: INTEGER
+         * @removed
          */
+        @Deprecated
         public static final String DATE_EXPIRES = "date_expires";
 
         /**
@@ -991,6 +1019,8 @@ public final class MediaStore {
          * Package name that contributed this media. The value may be
          * {@code NULL} if ownership cannot be reliably determined.
          * <p>
+         * This is a read-only column that is automatically computed.
+         * <p>
          * Type: TEXT
          */
         public static final String OWNER_PACKAGE_NAME = "owner_package_name";
@@ -1014,6 +1044,52 @@ public final class MediaStore {
          * @see PendingParams#setSecondaryDirectory(String)
          */
         public static final String SECONDARY_DIRECTORY = "secondary_directory";
+
+        /**
+         * The "document ID" GUID as defined by the <em>XMP Media
+         * Management</em> standard, extracted from any XMP metadata contained
+         * within this media item. The value is {@code null} when no metadata
+         * was found.
+         * <p>
+         * Each "document ID" is created once for each new resource. Different
+         * renditions of that resource are expected to have different IDs.
+         * <p>
+         * This is a read-only column that is automatically computed.
+         * <p>
+         * Type: TEXT
+         */
+        public static final String DOCUMENT_ID = "document_id";
+
+        /**
+         * The "instance ID" GUID as defined by the <em>XMP Media
+         * Management</em> standard, extracted from any XMP metadata contained
+         * within this media item. The value is {@code null} when no metadata
+         * was found.
+         * <p>
+         * This "instance ID" changes with each save operation of a specific
+         * "document ID".
+         * <p>
+         * This is a read-only column that is automatically computed.
+         * <p>
+         * Type: TEXT
+         */
+        public static final String INSTANCE_ID = "instance_id";
+
+        /**
+         * The "original document ID" GUID as defined by the <em>XMP Media
+         * Management</em> standard, extracted from any XMP metadata contained
+         * within this media item.
+         * <p>
+         * This "original document ID" links a resource to its original source.
+         * For example, when you save a PSD document as a JPEG, then convert the
+         * JPEG to GIF format, the "original document ID" of both the JPEG and
+         * GIF files is the "document ID" of the original PSD file.
+         * <p>
+         * This is a read-only column that is automatically computed.
+         * <p>
+         * Type: TEXT
+         */
+        public static final String ORIGINAL_DOCUMENT_ID = "original_document_id";
     }
 
     /**