From f6f3136e8b7e68b12824ac4c41dd4e8d1bca4927 Mon Sep 17 00:00:00 2001
From: Jing Ji <jji@google.com>
Date: Tue, 14 Mar 2023 18:33:35 -0700
Subject: [PATCH] Update the doc for the
 MediaProjectionManager#getMediaProjection

So it reflects the latest requirement from Android U regarding
the mediaProjection FGS permission, which was introduced in
the I1e5b58ddea232fecaaa5ed513276a62c72429a0b.

Bug: 269758761
Test: m offline-sdk-docs
Change-Id: I9b52f2227e7745886a238a3ef96f704d32788dd9
---
 .../projection/MediaProjectionManager.java    | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/media/java/android/media/projection/MediaProjectionManager.java b/media/java/android/media/projection/MediaProjectionManager.java
index f327e4e76f16b..30fccf485b24a 100644
--- a/media/java/android/media/projection/MediaProjectionManager.java
+++ b/media/java/android/media/projection/MediaProjectionManager.java
@@ -35,6 +35,27 @@ import java.util.Map;
 
 /**
  * Manages the retrieval of certain types of {@link MediaProjection} tokens.
+ *
+ * <p><ol>An example flow of starting a media projection will be:
+ *     <li>Declare a foreground service with the type {@code mediaProjection} in
+ *     the {@code AndroidManifest.xml}.
+ *     </li>
+ *     <li>Create an intent by calling {@link MediaProjectionManager#createScreenCaptureIntent()}
+ *         and pass this intent to {@link Activity#startActivityForResult(Intent, int)}.
+ *     </li>
+ *     <li>On getting {@link Activity#onActivityResult(int, int, Intent)},
+ *         start the foreground service with the type
+ *         {@link android.content.pm.ServiceInfo#FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION}.
+ *     </li>
+ *     <li>Retrieve the media projection token by calling
+ *         {@link MediaProjectionManager#getMediaProjection(int, Intent)} with the result code and
+ *         intent from the {@link Activity#onActivityResult(int, int, Intent)} above.
+ *     </li>
+ *     <li>Start the screen capture session for media projection by calling
+ *         {@link MediaProjection#createVirtualDisplay(String, int, int, int, int, Surface,
+ *         android.hardware.display.VirtualDisplay.Callback, Handler)}.
+ *     </li>
+ * </ol>
  */
 @SystemService(Context.MEDIA_PROJECTION_SERVICE)
 public final class MediaProjectionManager {
@@ -170,6 +191,17 @@ public final class MediaProjectionManager {
      * <a href="/guide/topics/manifest/service-element"><code>&lt;service&gt;</code></a> element of
      * the app's manifest file.
      * </p>
+     * <p>
+     * For an app targeting SDK version {@link android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE U} or
+     * later, the user must have granted the app with the permission to start a projection,
+     * before the app starts a foreground service with the type
+     * {@link android.content.pm.ServiceInfo#FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION}.
+     * Additionally, the app must have started the foreground service with that type before calling
+     * this API here, or else it'll receive a {@link SecurityException} from this API call, unless
+     * it's a privileged app. Apps can request the permission via the
+     * {@link #createScreenCaptureIntent()} and {@link Activity#startActivityForResult(Intent, int)}
+     * (or similar APIs).
+     * </p>
      *
      * @param resultCode The result code from {@link Activity#onActivityResult(int, int, Intent)
      *                   onActivityResult(int, int, Intent)}.