BugreportManager API review updates.

- Expand BugreportManager class javadoc
    - Explain what "privileged" means
    - Highlight only one-BR-at-a-time behavior
- Add more detail to BugreportCallback javadocs
    - Explain standard callback invocation flow
    - More detail on when BUGREPORT_ERROR_INVALID_INPUT is used
- Add @WorkerThread to {start{,Connectivity},cancel}Bugreport

Bug: 180015324
Test: make
Change-Id: Id3400b1cdd271f47bdeaf8cdc1a0dea61aafc933

3 files changed, 28 insertions, 8 deletions

diff --git a/core/api/current.txt b/core/api/current.txt
index 7d30edee3a13..a3174247e7e8 100644
--- a/core/api/current.txt
+++ b/core/api/current.txt
@@ -29604,8 +29604,8 @@ package android.os {
   }
 
   public final class BugreportManager {
-    method public void cancelBugreport();
-    method public void startConnectivityBugreport(@NonNull android.os.ParcelFileDescriptor, @NonNull java.util.concurrent.Executor, @NonNull android.os.BugreportManager.BugreportCallback);
+    method @WorkerThread public void cancelBugreport();
+    method @WorkerThread public void startConnectivityBugreport(@NonNull android.os.ParcelFileDescriptor, @NonNull java.util.concurrent.Executor, @NonNull android.os.BugreportManager.BugreportCallback);
   }
 
   public abstract static class BugreportManager.BugreportCallback {
diff --git a/core/api/system-current.txt b/core/api/system-current.txt
index f3ed528ad10e..64ab0ff9d238 100644
--- a/core/api/system-current.txt
+++ b/core/api/system-current.txt
@@ -7149,7 +7149,7 @@ package android.os {
 
   public final class BugreportManager {
     method @RequiresPermission(android.Manifest.permission.DUMP) public void requestBugreport(@NonNull android.os.BugreportParams, @Nullable CharSequence, @Nullable CharSequence);
-    method @RequiresPermission(android.Manifest.permission.DUMP) public void startBugreport(@NonNull android.os.ParcelFileDescriptor, @Nullable android.os.ParcelFileDescriptor, @NonNull android.os.BugreportParams, @NonNull java.util.concurrent.Executor, @NonNull android.os.BugreportManager.BugreportCallback);
+    method @RequiresPermission(android.Manifest.permission.DUMP) @WorkerThread public void startBugreport(@NonNull android.os.ParcelFileDescriptor, @Nullable android.os.ParcelFileDescriptor, @NonNull android.os.BugreportParams, @NonNull java.util.concurrent.Executor, @NonNull android.os.BugreportManager.BugreportCallback);
   }
 
   public final class BugreportParams {
diff --git a/core/java/android/os/BugreportManager.java b/core/java/android/os/BugreportManager.java
index 305c686f8657..a435ac12d33c 100644
--- a/core/java/android/os/BugreportManager.java
+++ b/core/java/android/os/BugreportManager.java
@@ -25,6 +25,7 @@ import android.annotation.RequiresPermission;
 import android.annotation.SuppressAutoDoc;
 import android.annotation.SystemApi;
 import android.annotation.SystemService;
+import android.annotation.WorkerThread;
 import android.app.ActivityManager;
 import android.content.Context;
 import android.util.Log;
@@ -41,7 +42,15 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.util.concurrent.Executor;
 
-/** Class that provides a privileged API to capture and consume bugreports. */
+/**
+ * Class that provides a privileged API to capture and consume bugreports.
+ *
+ * <p>This class may only be used by apps that currently have carrier privileges (see {@link
+ * android.telephony.TelephonyManager#hasCarrierPrivileges}) on an active SIM or priv-apps
+ * explicitly allowed by the device manufacturer.
+ *
+ * <p>Only one bugreport can be generated by the system at a time.
+ */
 @SystemService(Context.BUGREPORT_SERVICE)
 public final class BugreportManager {
 
@@ -56,7 +65,12 @@ public final class BugreportManager {
         mBinder = binder;
     }
 
-    /** An interface describing the callback for bugreport progress and status. */
+    /**
+     * An interface describing the callback for bugreport progress and status.
+     *
+     * <p>In general, callers can expect to receive {@link #onProgress} calls as the bugreport
+     * progresses, followed by a terminal call to either {@link #onFinished} or {@link #onError}.
+     */
     public abstract static class BugreportCallback {
         /**
          * Possible error codes taking a bugreport can encounter.
@@ -75,15 +89,18 @@ public final class BugreportManager {
                 })
         public @interface BugreportErrorCode {}
 
-        /** The input options were invalid */
+        /**
+         * The input options were invalid. For example, the destination file the app provided could
+         * not be written by the system.
+         */
         public static final int BUGREPORT_ERROR_INVALID_INPUT =
                 IDumpstateListener.BUGREPORT_ERROR_INVALID_INPUT;
 
-        /** A runtime error occurred */
+        /** A runtime error occurred. */
         public static final int BUGREPORT_ERROR_RUNTIME =
                 IDumpstateListener.BUGREPORT_ERROR_RUNTIME_ERROR;
 
-        /** User denied consent to share the bugreport */
+        /** User denied consent to share the bugreport. */
         public static final int BUGREPORT_ERROR_USER_DENIED_CONSENT =
                 IDumpstateListener.BUGREPORT_ERROR_USER_DENIED_CONSENT;
 
@@ -149,6 +166,7 @@ public final class BugreportManager {
      */
     @SystemApi
     @RequiresPermission(android.Manifest.permission.DUMP)
+    @WorkerThread
     public void startBugreport(
             @NonNull ParcelFileDescriptor bugreportFd,
             @Nullable ParcelFileDescriptor screenshotFd,
@@ -222,6 +240,7 @@ public final class BugreportManager {
      * @param callback callback for progress and status updates.
      */
     @SuppressAutoDoc // Blocked by b/72967236 - no support for carrier privileges
+    @WorkerThread
     public void startConnectivityBugreport(
             @NonNull ParcelFileDescriptor bugreportFd,
             @NonNull @CallbackExecutor Executor executor,
@@ -247,6 +266,7 @@ public final class BugreportManager {
      * @throws SecurityException if trying to cancel another app's bugreport in progress
      */
     @SuppressAutoDoc // Blocked by b/72967236 - no support for carrier privileges
+    @WorkerThread
     public void cancelBugreport() {
         try {
             mBinder.cancelBugreport(-1 /* callingUid */, mContext.getOpPackageName());