From e4773279d77855d42520e34f5cdbdf769ae62ebb Mon Sep 17 00:00:00 2001
From: David Zhao <qingxun@google.com>
Date: Thu, 18 May 2023 16:36:32 -0700
Subject: [PATCH] Update documentation for TV messages

Test: mmm
Bug: 278628657
Change-Id: I90a728b02f8208541bb10d419961b25f78fd840f
---
 tv/input/aidl/android/hardware/tv/input/ITvInput.aidl        | 5 +++++
 .../aidl/android/hardware/tv/input/ITvInputCallback.aidl     | 5 +++++
 2 files changed, 10 insertions(+)

diff --git a/tv/input/aidl/android/hardware/tv/input/ITvInput.aidl b/tv/input/aidl/android/hardware/tv/input/ITvInput.aidl
index cbaf0663b6..c63e0aca0f 100644
--- a/tv/input/aidl/android/hardware/tv/input/ITvInput.aidl
+++ b/tv/input/aidl/android/hardware/tv/input/ITvInput.aidl
@@ -98,6 +98,11 @@ interface ITvInput {
      * detected from the stream based on whether or not they are enabled by
      * {@link #setTvMessageEnabled(int, int, TvMessageEventType, boolean)}.
      *
+     * This queue is expected to already contain the message data before calling
+     * {@link android.hardware.tv.input.ITvInputCallback#notifyTvMessageEvent}.
+     * The HAL implementation is expected to have already created the queue
+     * before the notification callback is called for the first time.
+     *
      * @param deviceId The ID of the device that contains the stream to get the queue for.
      * @param streamId THe ID of the stream to get the queue for.
      * @return The descriptor of the TV message queue.
diff --git a/tv/input/aidl/android/hardware/tv/input/ITvInputCallback.aidl b/tv/input/aidl/android/hardware/tv/input/ITvInputCallback.aidl
index 2c7e32f29d..a3afd41fd5 100644
--- a/tv/input/aidl/android/hardware/tv/input/ITvInputCallback.aidl
+++ b/tv/input/aidl/android/hardware/tv/input/ITvInputCallback.aidl
@@ -39,6 +39,11 @@ interface ITvInputCallback {
      * the device that sent the message should be contained in
      * {@link android.hardware.tv.input.TvMessage#groupId}
      *
+     * Invoking this callback for the first time immediately triggers
+     * {@link android.hardware.tv.input.ITvInput#getTvMessageQueueDesc}. It is
+     * expected for the queue to be ready with
+     * the relevant messages for the event before this callback is called.
+     *
      * @param event Event passed to the client.
      */
     void notifyTvMessageEvent(in TvMessageEvent event);