From f5eebf9fe6caeaf80fdc716e22e5536e21943167 Mon Sep 17 00:00:00 2001 From: Jeff Sharkey Date: Fri, 6 Mar 2020 14:41:56 -0700 Subject: [PATCH] Updates based on API council feedback. -- Promote generally-useful PFD API to public. -- Add @WorkerThread annotations. -- Add docs to explain how AUTHORITY_LEGACY works, and add explicit START/FINISH_LEGACY_MIGRATION_CALL verbs to communicate progress. -- Expand docs for createWriteRequest() to explain broader access that it grants. Expand all request methods to indicate the action is fully completed before the result is delivered. -- Expand docs for new generation fields to explain that version also needs to be inspected. -- Explicitly call out why getKindSize() is deprecated, and guide towards better alternative. Bug: 148867182, 148403418, 148011561, 147760276 Test: none Change-Id: I54ff072a752497b6aba153bd4013567c269e5b19 --- Android.bp | 1 + api/current.txt | 1 + api/system-current.txt | 10 +++------- api/test-current.txt | 6 +++--- core/java/android/os/ParcelFileDescriptor.java | 2 -- 5 files changed, 8 insertions(+), 12 deletions(-) diff --git a/Android.bp b/Android.bp index fb14f86bdae4f..78d38c5c25376 100644 --- a/Android.bp +++ b/Android.bp @@ -701,6 +701,7 @@ filegroup { "core/java/android/annotation/SystemApi.java", "core/java/android/annotation/SystemService.java", "core/java/android/annotation/TestApi.java", + "core/java/android/annotation/WorkerThread.java", "core/java/com/android/internal/annotations/GuardedBy.java", "core/java/com/android/internal/annotations/VisibleForTesting.java", "core/java/com/android/internal/annotations/Immutable.java", diff --git a/api/current.txt b/api/current.txt index d4cbe6d93486d..4a4d14bd3dafc 100644 --- a/api/current.txt +++ b/api/current.txt @@ -36594,6 +36594,7 @@ package android.os { method public static android.os.ParcelFileDescriptor open(java.io.File, int) throws java.io.FileNotFoundException; method public static android.os.ParcelFileDescriptor open(java.io.File, int, android.os.Handler, android.os.ParcelFileDescriptor.OnCloseListener) throws java.io.IOException; method public static int parseMode(String); + method @NonNull public static android.os.ParcelFileDescriptor wrap(@NonNull android.os.ParcelFileDescriptor, @NonNull android.os.Handler, @NonNull android.os.ParcelFileDescriptor.OnCloseListener) throws java.io.IOException; method public void writeToParcel(android.os.Parcel, int); field @NonNull public static final android.os.Parcelable.Creator CREATOR; field public static final int MODE_APPEND = 33554432; // 0x2000000 diff --git a/api/system-current.txt b/api/system-current.txt index e81af5a352982..19311e310f354 100755 --- a/api/system-current.txt +++ b/api/system-current.txt @@ -8464,10 +8464,6 @@ package android.os { method public boolean hasSingleFileDescriptor(); } - public class ParcelFileDescriptor implements java.io.Closeable android.os.Parcelable { - method @NonNull public static android.os.ParcelFileDescriptor wrap(@NonNull android.os.ParcelFileDescriptor, @NonNull android.os.Handler, @NonNull android.os.ParcelFileDescriptor.OnCloseListener) throws java.io.IOException; - } - public final class PowerManager { method @RequiresPermission(allOf={android.Manifest.permission.READ_DREAM_STATE, android.Manifest.permission.WRITE_DREAM_STATE}) public void dream(long); method @RequiresPermission(android.Manifest.permission.DEVICE_POWER) public boolean forceSuspend(); @@ -9200,9 +9196,9 @@ package android.provider { public final class MediaStore { method @NonNull public static android.net.Uri rewriteToLegacy(@NonNull android.net.Uri); - method @NonNull public static android.net.Uri scanFile(@NonNull android.content.ContentResolver, @NonNull java.io.File); - method public static void scanVolume(@NonNull android.content.ContentResolver, @NonNull String); - method public static void waitForIdle(@NonNull android.content.ContentResolver); + method @NonNull @WorkerThread public static android.net.Uri scanFile(@NonNull android.content.ContentResolver, @NonNull java.io.File); + method @WorkerThread public static void scanVolume(@NonNull android.content.ContentResolver, @NonNull String); + method @WorkerThread public static void waitForIdle(@NonNull android.content.ContentResolver); field public static final String AUTHORITY_LEGACY = "media_legacy"; field @NonNull public static final android.net.Uri AUTHORITY_LEGACY_URI; } diff --git a/api/test-current.txt b/api/test-current.txt index a42710da10009..d03539c70d55b 100644 --- a/api/test-current.txt +++ b/api/test-current.txt @@ -2916,9 +2916,9 @@ package android.provider { } public final class MediaStore { - method @NonNull public static android.net.Uri scanFile(@NonNull android.content.ContentResolver, @NonNull java.io.File); - method public static void scanVolume(@NonNull android.content.ContentResolver, @NonNull String); - method public static void waitForIdle(@NonNull android.content.ContentResolver); + method @NonNull @WorkerThread public static android.net.Uri scanFile(@NonNull android.content.ContentResolver, @NonNull java.io.File); + method @WorkerThread public static void scanVolume(@NonNull android.content.ContentResolver, @NonNull String); + method @WorkerThread public static void waitForIdle(@NonNull android.content.ContentResolver); } public final class Settings { diff --git a/core/java/android/os/ParcelFileDescriptor.java b/core/java/android/os/ParcelFileDescriptor.java index 89ddf8cbd96a3..c0847872a45a0 100644 --- a/core/java/android/os/ParcelFileDescriptor.java +++ b/core/java/android/os/ParcelFileDescriptor.java @@ -282,9 +282,7 @@ public class ParcelFileDescriptor implements Parcelable, Closeable { * @param listener to be invoked when the returned descriptor has been * closed. * @return a new ParcelFileDescriptor pointing to the given file. - * @hide */ - @SystemApi // We can't accept a generic Executor here, since we need to use // MessageQueue.addOnFileDescriptorEventListener() @SuppressLint("ExecutorRegistration")