Merge "Update MediaProjection documentation for onStop callback" into main (533049d8) · Commits · e / os / android_frameworks_base

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

+22 −22

Original line number	Diff line number	Diff line
		@@ -91,15 +91,15 @@ public final class MediaProjection {
		}

		/**
		* Register a listener to receive notifications about when the {@link MediaProjection} or captured
		* content changes state.
		* Register a listener to receive notifications about when the {@link MediaProjection} or
		* captured content changes state.
		*
		* <p>The callback must be registered before invoking {@link #createVirtualDisplay(String, int,
		* int, int, int, Surface, VirtualDisplay.Callback, Handler)} to ensure that any notifications on
		* the callback are not missed. The client must implement {@link Callback#onStop()} and clean up
		* any resources it is holding, e.g. the {@link VirtualDisplay} and {@link Surface}. This should
		* also update any application UI indicating the MediaProjection status as MediaProjection has
		* stopped.
		* int, int, int, Surface, VirtualDisplay.Callback, Handler)} to ensure that any notifications
		* on the callback are not missed. The client must implement {@link Callback#onStop()} to
		* properly handle MediaProjection clean up any resources it is holding, e.g. the {@link
		* VirtualDisplay} and {@link Surface}. This should also update any application UI indicating
		* the MediaProjection status as MediaProjection has stopped.
		*
		* @param callback The callback to call.
		* @param handler The handler on which the callback should be invoked, or null if the callback
		@@ -313,7 +313,7 @@ public final class MediaProjection {
		*/
		public abstract static class Callback {
		/**
		* Called when the MediaProjection session is no longer valid.
		* Called when the MediaProjection session has been stopped and is no longer valid.
		*
		* <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
		@@ -321,9 +321,9 @@ public final class MediaProjection {
		* it should be updated to indicate that MediaProjection is no longer active.
		*
		* <p>MediaProjection stopping can be a result of the system stopping the ongoing
		* MediaProjection due to various reasons, such as another MediaProjection session starting.
		* MediaProjection may also stop due to the user explicitly stopping ongoing MediaProjection
		* via any available system-level UI.
		* MediaProjection due to various reasons, such as another MediaProjection session starting,
		* a user stopping the session via UI affordances in system-level UI, or the screen being
		* locked.
		*
		* <p>After this callback any call to {@link MediaProjection#createVirtualDisplay} will
		* fail, even if no such {@link VirtualDisplay} was ever created for this MediaProjection

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

+8 −7

Original line number	Diff line number	Diff line
		@@ -60,13 +60,14 @@ import java.util.Map;
		* <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)}. Note that the `onStop()` callback can be a result of
		* the system stopping MediaProjection due to various reasons or the user stopping the
		* MediaProjection via UI affordances in system-level UI.
		* state. When receiving an `onStop()` callback the {@link MediaProjection} session has been
		* finished and 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)}. Note that the `onStop()`
		* callback can be a result of the system stopping MediaProjection due to various reasons.
		* This includes the user stopping the MediaProjection via UI affordances in system-level UI,
		* the screen being locked, or another {@link MediaProjection} session starting.
		* <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)}.