From 3f49082523633f30b5aa761c5e20e19b39ec180b Mon Sep 17 00:00:00 2001 From: shubang Date: Tue, 8 Mar 2022 15:16:24 -0800 Subject: [PATCH] TIAF API review: multiple components Address feedback from API council Bug: 219501014 Test: atest android.media.tv.interactive.cts.TvInteractiveAppServiceTest Change-Id: I655483db22b9a5ad3c3e30200f887fe49e73f240 --- core/api/current.txt | 6 +++-- .../java/android/media/tv/TvInputManager.java | 4 ++-- media/java/android/media/tv/TvView.java | 10 ++++---- .../interactive/TvInteractiveAppManager.java | 18 ++++++++++---- .../interactive/TvInteractiveAppService.java | 18 +++++++++++--- .../tv/interactive/TvInteractiveAppView.java | 24 +++++++++++++++++-- 6 files changed, 61 insertions(+), 19 deletions(-) diff --git a/core/api/current.txt b/core/api/current.txt index 064d998219c2f..68e5ba8590cf0 100644 --- a/core/api/current.txt +++ b/core/api/current.txt @@ -26077,7 +26077,7 @@ package android.media.tv { method public void onContentAllowed(String); method public void onContentBlocked(String, android.media.tv.TvContentRating); method public void onDisconnected(String); - method public void onSignalStrength(@NonNull String, int); + method public void onSignalStrengthUpdated(@NonNull String, int); method public void onTimeShiftStatusChanged(String, int); method public void onTrackSelected(String, int, String); method public void onTracksChanged(String, java.util.List); @@ -26185,6 +26185,7 @@ package android.media.tv.interactive { public abstract static class TvInteractiveAppService.Session implements android.view.KeyEvent.Callback { ctor public TvInteractiveAppService.Session(@NonNull android.content.Context); + method public boolean isMediaViewEnabled(); method @CallSuper public void layoutSurface(int, int, int, int); method @CallSuper public final void notifyBiInteractiveAppCreated(@NonNull android.net.Uri, @Nullable String); method @CallSuper public void notifySessionStateChanged(int, int); @@ -26204,7 +26205,7 @@ package android.media.tv.interactive { method public boolean onKeyLongPress(int, @NonNull android.view.KeyEvent); method public boolean onKeyMultiple(int, int, @NonNull android.view.KeyEvent); method public boolean onKeyUp(int, @NonNull android.view.KeyEvent); - method public void onMediaViewSizeChanged(int, int); + method public void onMediaViewSizeChanged(@Px int, @Px int); method public abstract void onRelease(); method public void onResetInteractiveApp(); method public abstract boolean onSetSurface(@Nullable android.view.Surface); @@ -26259,6 +26260,7 @@ package android.media.tv.interactive { method public void createBiInteractiveApp(@NonNull android.net.Uri, @Nullable android.os.Bundle); method public void destroyBiInteractiveApp(@NonNull String); method public boolean dispatchUnhandledInputEvent(@NonNull android.view.InputEvent); + method @Nullable public android.media.tv.interactive.TvInteractiveAppView.OnUnhandledInputEventListener getOnUnhandledInputEventListener(); method public void onAttachedToWindow(); method public void onDetachedFromWindow(); method public void onLayout(boolean, int, int, int, int); diff --git a/media/java/android/media/tv/TvInputManager.java b/media/java/android/media/tv/TvInputManager.java index 69fe5ee498722..149c2f471a4c8 100644 --- a/media/java/android/media/tv/TvInputManager.java +++ b/media/java/android/media/tv/TvInputManager.java @@ -680,7 +680,7 @@ public final class TvInputManager { * @param session A {@link TvInputManager.Session} associated with this callback. * @param strength The current signal strength. */ - public void onSignalStrength(Session session, @SignalStrength int strength) { + public void onSignalStrengthUpdated(Session session, @SignalStrength int strength) { } /** @@ -898,7 +898,7 @@ public final class TvInputManager { mHandler.post(new Runnable() { @Override public void run() { - mSessionCallback.onSignalStrength(mSession, strength); + mSessionCallback.onSignalStrengthUpdated(mSession, strength); if (mSession.mIAppNotificationEnabled && mSession.getInteractiveAppSession() != null) { mSession.getInteractiveAppSession().notifySignalStrength(strength); diff --git a/media/java/android/media/tv/TvView.java b/media/java/android/media/tv/TvView.java index 4d63af7be4740..ff3d06c5bd693 100644 --- a/media/java/android/media/tv/TvView.java +++ b/media/java/android/media/tv/TvView.java @@ -1083,7 +1083,7 @@ public class TvView extends ViewGroup { * @param inputId The ID of the TV input bound to this view. * @param strength The current signal strength. */ - public void onSignalStrength( + public void onSignalStrengthUpdated( @NonNull String inputId, @TvInputManager.SignalStrength int strength) { } @@ -1406,16 +1406,16 @@ public class TvView extends ViewGroup { } @Override - public void onSignalStrength(Session session, int strength) { + public void onSignalStrengthUpdated(Session session, int strength) { if (DEBUG) { - Log.d(TAG, "onSignalStrength(strength=" + strength + ")"); + Log.d(TAG, "onSignalStrengthUpdated(strength=" + strength + ")"); } if (this != mSessionCallback) { - Log.w(TAG, "onSignalStrength - session not created"); + Log.w(TAG, "onSignalStrengthUpdated - session not created"); return; } if (mCallback != null) { - mCallback.onSignalStrength(mInputId, strength); + mCallback.onSignalStrengthUpdated(mInputId, strength); } } diff --git a/media/java/android/media/tv/interactive/TvInteractiveAppManager.java b/media/java/android/media/tv/interactive/TvInteractiveAppManager.java index 90f32593ed78c..702832ccb3ca0 100755 --- a/media/java/android/media/tv/interactive/TvInteractiveAppManager.java +++ b/media/java/android/media/tv/interactive/TvInteractiveAppManager.java @@ -28,9 +28,9 @@ import android.media.tv.AdResponse; import android.media.tv.BroadcastInfoRequest; import android.media.tv.BroadcastInfoResponse; import android.media.tv.TvContentRating; -import android.media.tv.TvInputInfo; import android.media.tv.TvInputManager; import android.media.tv.TvTrackInfo; +import android.media.tv.interactive.TvInteractiveAppServiceInfo.InteractiveAppType; import android.net.Uri; import android.os.Bundle; import android.os.Handler; @@ -776,8 +776,16 @@ public final class TvInteractiveAppManager { /** * Prepares TV Interactive App service environment for the given type. + * + *

This method brings up the corresponding {@link TvInteractiveAppService} and prepare needed + * resources. It's used to set up the resources in advance, or handle non-session operations. + * + * @param tvIAppServiceId The ID of TV interactive service to prepare the resources. The + * ID can be found in {@link TvInteractiveAppServiceInfo#getId()}. + * + * @see TvInteractiveAppService.Session */ - public void prepare(@NonNull String tvIAppServiceId, int type) { + public void prepare(@NonNull String tvIAppServiceId, @InteractiveAppType int type) { try { mService.prepare(tvIAppServiceId, type, mUserId); } catch (RemoteException e) { @@ -790,7 +798,7 @@ public final class TvInteractiveAppManager { * Android application by TV interactive App RTE. * * @param tvIAppServiceId The ID of TV interactive service which the command to be sent to. The - * ID can be found in {@link TvInputInfo#getId()}. + * ID can be found in {@link TvInteractiveAppServiceInfo#getId()}. * @param appLinkInfo The Android application link info record to be registered. */ public void registerAppLinkInfo( @@ -807,7 +815,7 @@ public final class TvInteractiveAppManager { * Android application by TV interactive App RTE. * * @param tvIAppServiceId The ID of TV interactive service which the command to be sent to. The - * ID can be found in {@link TvInputInfo#getId()}. + * ID can be found in {@link TvInteractiveAppServiceInfo#getId()}. * @param appLinkInfo The Android application link info record to be unregistered. */ public void unregisterAppLinkInfo( @@ -823,7 +831,7 @@ public final class TvInteractiveAppManager { * Sends app link command. * * @param tvIAppServiceId The ID of TV interactive service which the command to be sent to. The - * ID can be found in {@link TvInputInfo#getId()}. + * ID can be found in {@link TvInteractiveAppServiceInfo#getId()}. * @param command The command to be sent. */ public void sendAppLinkCommand(@NonNull String tvIAppServiceId, @NonNull Bundle command) { diff --git a/media/java/android/media/tv/interactive/TvInteractiveAppService.java b/media/java/android/media/tv/interactive/TvInteractiveAppService.java index 100c6d3947bbe..15144f82e52c6 100755 --- a/media/java/android/media/tv/interactive/TvInteractiveAppService.java +++ b/media/java/android/media/tv/interactive/TvInteractiveAppService.java @@ -20,6 +20,7 @@ import android.annotation.CallSuper; import android.annotation.MainThread; import android.annotation.NonNull; import android.annotation.Nullable; +import android.annotation.Px; import android.annotation.SdkConstant; import android.annotation.StringDef; import android.annotation.SuppressLint; @@ -372,6 +373,15 @@ public abstract class TvInteractiveAppService extends Service { }); } + /** + * Returns {@code true} if media view is enabled, {@code false} otherwise. + * + * @see #setMediaViewEnabled(boolean) + */ + public boolean isMediaViewEnabled() { + return mMediaViewEnabled; + } + /** * Starts TvInteractiveAppService session. */ @@ -435,6 +445,8 @@ public abstract class TvInteractiveAppService extends Service { /** * Receives current stream volume. + * + * @param volume a volume value between {@code 0.0f} and {@code 1.0f}, inclusive. */ public void onStreamVolume(float volume) { } @@ -495,10 +507,10 @@ public abstract class TvInteractiveAppService extends Service { * containing {@link TvInteractiveAppView}. Note that the size of the underlying surface can * be different if the surface was changed by calling {@link #layoutSurface}. * - * @param width The width of the media view. - * @param height The height of the media view. + * @param width The width of the media view, in pixels. + * @param height The height of the media view, in pixels. */ - public void onMediaViewSizeChanged(int width, int height) { + public void onMediaViewSizeChanged(@Px int width, @Px int height) { } /** diff --git a/media/java/android/media/tv/interactive/TvInteractiveAppView.java b/media/java/android/media/tv/interactive/TvInteractiveAppView.java index 8fc5d807c7df5..9154de008d7a1 100755 --- a/media/java/android/media/tv/interactive/TvInteractiveAppView.java +++ b/media/java/android/media/tv/interactive/TvInteractiveAppView.java @@ -265,7 +265,9 @@ public class TvInteractiveAppView extends ViewGroup { } /** - * Resets this TvInteractiveAppView. + * Resets this TvInteractiveAppView to release its resources. + * + *

It can be reused by call {@link #prepareInteractiveApp(String, int)}. */ public void reset() { if (DEBUG) Log.d(TAG, "reset()"); @@ -391,6 +393,19 @@ public class TvInteractiveAppView extends ViewGroup { mOnUnhandledInputEventListener = listener; // TODO: handle CallbackExecutor } + + /** + * Gets the {@link OnUnhandledInputEventListener}. + *

Returns {@code null} if the listener is not set or is cleared. + * + * @see #setOnUnhandledInputEventListener(Executor, OnUnhandledInputEventListener) + * @see #clearOnUnhandledInputEventListener() + */ + @Nullable + public OnUnhandledInputEventListener getOnUnhandledInputEventListener() { + return mOnUnhandledInputEventListener; + } + /** * Clears the {@link OnUnhandledInputEventListener}. */ @@ -413,7 +428,8 @@ public class TvInteractiveAppView extends ViewGroup { } /** - * Prepares the interactive application. + * Prepares the interactive application runtime environment of corresponding + * {@link TvInteractiveAppService}. * * @param iAppServiceId the interactive app service ID, which can be found in * {@link TvInteractiveAppServiceInfo#getId()}. @@ -459,6 +475,8 @@ public class TvInteractiveAppView extends ViewGroup { /** * Resets the interactive application. + * + *

This releases the resources of the corresponding {@link TvInteractiveAppService.Session}. */ public void resetInteractiveApp() { if (DEBUG) { @@ -498,6 +516,8 @@ public class TvInteractiveAppView extends ViewGroup { /** * Sends stream volume to related TV interactive app. + * + * @param volume a volume value between {@code 0.0f} and {@code 1.0f}, inclusive. */ public void sendStreamVolume(float volume) { if (DEBUG) {