Merge "Fix DATA column docs" into sc-dev
diff --git a/apex/framework/java/android/provider/MediaStore.java b/apex/framework/java/android/provider/MediaStore.java
index 84c8813..c39d334 100644
--- a/apex/framework/java/android/provider/MediaStore.java
+++ b/apex/framework/java/android/provider/MediaStore.java
@@ -1175,26 +1175,23 @@
/**
* Absolute filesystem path to the media item on disk.
* <p>
- * On Android 11, you can use this value when you access an existing
- * file using direct file paths. That's because this value has a valid
- * file path. However, don't assume that the file is always available.
- * Be prepared to handle any file-based I/O errors that could occur.
+ * Apps may use this path to do file operations. However, they should not assume that the
+ * file is always available. Apps must be prepared to handle any file-based I/O errors that
+ * could occur.
* <p>
- * Don't use this value when you create or update a media file, even
- * if you're on Android 11 and are using direct file paths. Instead,
- * use the values of the {@link #DISPLAY_NAME} and
+ * From Android 11 onwards, this column is read-only for apps that target
+ * {@link android.os.Build.VERSION_CODES#R R} and higher. On those devices, when creating or
+ * updating a uri, this column's value is not accepted. Instead, to update the
+ * filesystem location of a file, use the values of the {@link #DISPLAY_NAME} and
* {@link #RELATIVE_PATH} columns.
* <p>
- * Note that apps may not have filesystem permissions to directly access
- * this path. Instead of trying to open this path directly, apps should
- * use {@link ContentResolver#openFileDescriptor(Uri, String)} to gain
- * access.
+ * Though direct file operations are supported,
+ * {@link ContentResolver#openFileDescriptor(Uri, String)} API is recommended for better
+ * performance.
*
- * @deprecated Apps may not have filesystem permissions to directly
- * access this path. Instead of trying to open this path
- * directly, apps should use
- * {@link ContentResolver#openFileDescriptor(Uri, String)}
- * to gain access.
+ * @deprecated Apps that target {@link android.os.Build.VERSION_CODES#R R} and higher
+ * may not update the value of this column. However they may read the file path
+ * value from this column and use in file operations.
*/
@Deprecated
@Column(Cursor.FIELD_TYPE_STRING)
@@ -1857,7 +1854,7 @@
* is a playlist file.
*
* @deprecated Android playlists are now deprecated. We will keep the current
- * functionality for compatibility resons, but we will no longer take
+ * functionality for compatibility reasons, but we will no longer take
* feature request. We do not advise adding new usages of Android Playlists.
* M3U files can be used as an alternative.
*/
@@ -2629,21 +2626,13 @@
/**
* Path to the thumbnail file on disk.
- * <p>
- * Note that apps may not have filesystem permissions to directly
- * access this path. Instead of trying to open this path directly,
- * apps should use
- * {@link ContentResolver#openFileDescriptor(Uri, String)} to gain
- * access.
*
* As of {@link android.os.Build.VERSION_CODES#Q}, this thumbnail
* has correct rotation, don't need to rotate it again.
*
- * @deprecated Apps may not have filesystem permissions to directly
- * access this path. Instead of trying to open this path
- * directly, apps should use
- * {@link ContentResolver#loadThumbnail}
- * to gain access.
+ * @deprecated Apps that target {@link android.os.Build.VERSION_CODES#R R} and higher
+ * may not update the value of this column. However they may read the file
+ * path value from this column and use in file operations.
*/
@Deprecated
@Column(Cursor.FIELD_TYPE_STRING)
@@ -3183,7 +3172,7 @@
* Audio playlist metadata columns.
*
* @deprecated Android playlists are now deprecated. We will keep the current
- * functionality for compatibility resons, but we will no longer take
+ * functionality for compatibility reasons, but we will no longer take
* feature request. We do not advise adding new usages of Android Playlists.
* M3U files can be used as an alternative.
*/
@@ -3197,18 +3186,10 @@
/**
* Path to the playlist file on disk.
- * <p>
- * Note that apps may not have filesystem permissions to directly
- * access this path. Instead of trying to open this path directly,
- * apps should use
- * {@link ContentResolver#openFileDescriptor(Uri, String)} to gain
- * access.
*
- * @deprecated Apps may not have filesystem permissions to directly
- * access this path. Instead of trying to open this path
- * directly, apps should use
- * {@link ContentResolver#openFileDescriptor(Uri, String)}
- * to gain access.
+ * @deprecated Apps that target {@link android.os.Build.VERSION_CODES#R R} and higher
+ * may not update the value of this column. However they may read the file
+ * path value from this column and use in file operations.
*/
@Deprecated
@Column(Cursor.FIELD_TYPE_STRING)
@@ -3623,18 +3604,10 @@
public static class Thumbnails implements BaseColumns {
/**
* Path to the thumbnail file on disk.
- * <p>
- * Note that apps may not have filesystem permissions to directly
- * access this path. Instead of trying to open this path directly,
- * apps should use
- * {@link ContentResolver#openFileDescriptor(Uri, String)} to gain
- * access.
*
- * @deprecated Apps may not have filesystem permissions to directly
- * access this path. Instead of trying to open this path
- * directly, apps should use
- * {@link ContentResolver#loadThumbnail}
- * to gain access.
+ * @deprecated Apps that target {@link android.os.Build.VERSION_CODES#R R} and higher
+ * may not update the value of this column. However they may read the file
+ * path value from this column and use in file operations.
*/
@Deprecated
@Column(Cursor.FIELD_TYPE_STRING)
@@ -3969,11 +3942,9 @@
/**
* Path to the thumbnail file on disk.
*
- * @deprecated Apps may not have filesystem permissions to directly
- * access this path. Instead of trying to open this path
- * directly, apps should use
- * {@link ContentResolver#openFileDescriptor(Uri, String)}
- * to gain access.
+ * @deprecated Apps that target {@link android.os.Build.VERSION_CODES#R R} and higher
+ * may not update the value of this column. However they may read the file
+ * path value from this column and use in file operations.
*/
@Deprecated
@Column(Cursor.FIELD_TYPE_STRING)