Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 46eeb3b6 authored by Marvin Ramin's avatar Marvin Ramin
Browse files

Update documentation of MediaProjection Callback 

Clearly call out the requirement to register a callback before creating a VirtualDisplay for a MediaProjection session.

Also point out the behavior

Bug: 352133031
Change-Id: I54492f9e719caf8b51e146c2c893215296801fd7
Test: n/a
Flag: DOCS_ONLY
parent 77b2e9ab

media/java/android/media/projection/MediaProjection.java

+4 −0
Original line number Diff line number Diff line
@@ -312,6 +312,10 @@ public final class MediaProjection { 
         * <p>Once a MediaProjection has been stopped, it's up to the application to release any

         * resources it may be holding (e.g. releasing the {@link VirtualDisplay} and

         * {@link Surface}).

         *

         * <p>After this callback any call to

         * {@link MediaProjection#createVirtualDisplay} will fail, even if no such

         * {@link VirtualDisplay} was ever created for this MediaProjection session.

         */

        public void onStop() { }

media/java/android/media/projection/MediaProjectionManager.java

+25 −19
Original line number Diff line number Diff line
@@ -43,25 +43,31 @@ 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,

 * <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>Create an intent by calling {@link MediaProjectionManager#createScreenCaptureIntent()} and

 *       pass this intent to {@link Activity#startActivityForResult(Intent, int)}.

 *   <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>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>Register a {@link MediaProjection.Callback} by calling {@link

 *       MediaProjection#registerCallback(MediaProjection.Callback, Handler)}. This is required to

 *       receive notifications about when the {@link MediaProjection} or captured content changes

 *       state. When receiving an `onStop()` callback, the client must clean up any resources it is

 *       holding, e.g. the {@link VirtualDisplay} and {@link Surface}. The MediaProjection may

 *       further no longer create any new {@link VirtualDisplay}s via {@link

 *       MediaProjection#createVirtualDisplay(String, int, int, int, int, Surface,

 *       VirtualDisplay.Callback, Handler)}.

 *   <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)