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

Commit 49877764 authored by David Zhao's avatar David Zhao
Browse files

API Review: Add TVMessage bundle keys 

This CL adds bundle key documentation to APIs that receive TV messages. It also adds Javadoc to the new bundle keys. The list of bundle keys are not exhaustive, and would depend on the subtype of the message, of which there are too many to define due to the amount of CC formats. It does, however, provide a bundle key to allow the reader to determine the subtype to parse it appropriately.

These keys are added in response to API Council reviews.

Bug: 272375356
Test: mmm
Change-Id: If6c1b0b757802a4531b8cb59bb574c44386d592e
parent c36b24ba

core/api/current.txt

+2 −0
Original line number Diff line number Diff line
@@ -27342,7 +27342,9 @@ package android.media.tv { 
    field public static final int TIME_SHIFT_STATUS_UNAVAILABLE = 2; // 0x2

    field public static final int TIME_SHIFT_STATUS_UNKNOWN = 0; // 0x0

    field public static final int TIME_SHIFT_STATUS_UNSUPPORTED = 1; // 0x1

    field public static final String TV_MESSAGE_KEY_RAW_DATA = "android.media.tv.TvInputManager.raw_data";

    field public static final String TV_MESSAGE_KEY_STREAM_ID = "android.media.tv.TvInputManager.stream_id";

    field public static final String TV_MESSAGE_KEY_SUBTYPE = "android.media.tv.TvInputManager.subtype";

    field public static final int TV_MESSAGE_TYPE_CLOSED_CAPTION = 2; // 0x2

    field public static final int TV_MESSAGE_TYPE_OTHER = 1000; // 0x3e8

    field public static final int TV_MESSAGE_TYPE_WATERMARK = 1; // 0x1

media/java/android/media/tv/TvInputManager.java

+42 −1
Original line number Diff line number Diff line
@@ -149,10 +149,45 @@ public final class TvInputManager { 
    /**

     * This constant is used as a {@link Bundle} key for TV messages. The value of the key

     * identifies the stream on the TV input source for which the watermark event is relevant to.

     *

     * <p> Type: String

     */

    public static final String TV_MESSAGE_KEY_STREAM_ID =

            "android.media.tv.TvInputManager.stream_id";



    /**

     * This constant is used as a {@link Bundle} key for TV messages. The value of the key

     * identifies the subtype of the data, such as the format of the CC data. The format

     * found at this key can then be used to identify how to parse the data at

     * {@link #TV_MESSAGE_KEY_RAW_DATA}.

     *

     * To parse the raw data bsed on the subtype, please refer to the official documentation of the

     * concerning subtype. For example, for the subtype "ATSC A/335" for watermarking, the

     * document for A/335 from the ATSC standard details how this data is formatted.

     *

     * Some other examples of common formats include:

     * <ul>

     *     <li>Watermarking - ATSC A/336</li>

     *     <li>Closed Captioning - CTA 608-E</li>

     * </ul>

     *

     * <p> Type: String

     */

    public static final String TV_MESSAGE_KEY_SUBTYPE =

            "android.media.tv.TvInputManager.subtype";



    /**

     * This constant is used as a {@link Bundle} key for TV messages. The value of the key

     * stores the raw data contained in this TV Message. The format of this data is determined

     * by the format defined by the subtype, found using the key at

     * {@link #TV_MESSAGE_KEY_SUBTYPE}. See {@link #TV_MESSAGE_KEY_SUBTYPE} for more

     * information on how to parse this data.

     *

     * <p> Type: byte[]

     */

    public static final String TV_MESSAGE_KEY_RAW_DATA =

            "android.media.tv.TvInputManager.raw_data";



    static final int VIDEO_UNAVAILABLE_REASON_START = 0;

    static final int VIDEO_UNAVAILABLE_REASON_END = 18;
@@ -802,7 +837,13 @@ public final class TvInputManager { 
         *

         * @param session A {@link TvInputManager.Session} associated with this callback.

         * @param type The type of message received, such as {@link #TV_MESSAGE_TYPE_WATERMARK}

         * @param data The raw data of the message

         * @param data The raw data of the message. The bundle keys are:

         *             {@link TvInputManager#TV_MESSAGE_KEY_STREAM_ID},

         *             {@link TvInputManager#TV_MESSAGE_KEY_SUBTYPE},

         *             {@link TvInputManager#TV_MESSAGE_KEY_RAW_DATA}.

         *             See {@link TvInputManager#TV_MESSAGE_KEY_SUBTYPE} for more information on

         *             how to parse this data.

         *

         */

        public void onTvMessage(Session session, @TvInputManager.TvMessageType int type,

                Bundle data) {

media/java/android/media/tv/TvInputService.java

+12 −2
Original line number Diff line number Diff line
@@ -1030,7 +1030,12 @@ public abstract class TvInputService extends Service { 
         *

         * @param type The of message that was sent, such as

         * {@link TvInputManager#TV_MESSAGE_TYPE_WATERMARK}

         * @param data The data sent with the message.

         * @param data The raw data of the message. The bundle keys are:

         *             {@link TvInputManager#TV_MESSAGE_KEY_STREAM_ID},

         *             {@link TvInputManager#TV_MESSAGE_KEY_SUBTYPE},

         *             {@link TvInputManager#TV_MESSAGE_KEY_RAW_DATA}.

         *             See {@link TvInputManager#TV_MESSAGE_KEY_SUBTYPE} for more information on

         *             how to parse this data.

         */

        public void notifyTvMessage(@TvInputManager.TvMessageType int type,

                @NonNull Bundle data) {
@@ -1500,7 +1505,12 @@ public abstract class TvInputService extends Service { 
         *

         * @param type The type of message received, such as

         * {@link TvInputManager#TV_MESSAGE_TYPE_WATERMARK}

         * @param data The raw data of the message

         * @param data The raw data of the message. The bundle keys are:

         *             {@link TvInputManager#TV_MESSAGE_KEY_STREAM_ID},

         *             {@link TvInputManager#TV_MESSAGE_KEY_SUBTYPE},

         *             {@link TvInputManager#TV_MESSAGE_KEY_RAW_DATA}.

         *             See {@link TvInputManager#TV_MESSAGE_KEY_SUBTYPE} for more information on

         *             how to parse this data.

         */

        public void onTvMessage(@NonNull @TvInputManager.TvMessageType String type,

                @NonNull Bundle data) {

media/java/android/media/tv/TvView.java

+6 −1
Original line number Diff line number Diff line
@@ -1254,7 +1254,12 @@ public class TvView extends ViewGroup { 
         * @param inputId The ID of the TV input bound to this view.

         * @param type The type of message received, such as

         *             {@link TvInputManager#TV_MESSAGE_TYPE_WATERMARK}

         * @param data The raw data of the message

         * @param data The raw data of the message. The bundle keys are:

         *             {@link TvInputManager#TV_MESSAGE_KEY_STREAM_ID},

         *             {@link TvInputManager#TV_MESSAGE_KEY_SUBTYPE},

         *             {@link TvInputManager#TV_MESSAGE_KEY_RAW_DATA}.

         *             See {@link TvInputManager#TV_MESSAGE_KEY_SUBTYPE} for more information on

         *             how to parse this data.

         */

        public void onTvMessage(@NonNull String inputId,

                @TvInputManager.TvMessageType int type, @NonNull Bundle data) {

media/java/android/media/tv/interactive/TvInteractiveAppService.java

+6 −1
Original line number Diff line number Diff line
@@ -918,7 +918,12 @@ public abstract class TvInteractiveAppService extends Service { 
         *

         * @param type The type of message received, such as

         * {@link TvInputManager#TV_MESSAGE_TYPE_WATERMARK}

         * @param data The raw data of the message

         * @param data The raw data of the message. The bundle keys are:

         *             {@link TvInputManager#TV_MESSAGE_KEY_STREAM_ID},

         *             {@link TvInputManager#TV_MESSAGE_KEY_SUBTYPE},

         *             {@link TvInputManager#TV_MESSAGE_KEY_RAW_DATA}.

         *             See {@link TvInputManager#TV_MESSAGE_KEY_SUBTYPE} for more information on

         *             how to parse this data.

         */

        public void onTvMessage(@TvInputManager.TvMessageType int type,

                @NonNull Bundle data) {