Merge "API Review: Update javadoc for recording requestId" into udc-dev

2 files changed, 41 insertions, 12 deletions

diff --git a/media/java/android/media/tv/interactive/TvInteractiveAppService.java b/media/java/android/media/tv/interactive/TvInteractiveAppService.java
index d78d277edd8a..012d5c1bc58b 100755
--- a/media/java/android/media/tv/interactive/TvInteractiveAppService.java
+++ b/media/java/android/media/tv/interactive/TvInteractiveAppService.java
@@ -285,7 +285,10 @@ public abstract class TvInteractiveAppService extends Service {
     public static final String COMMAND_PARAMETER_KEY_PLAYBACK_PARAMS = "command_playback_params";
     /**
      * Time shift command parameter: playback params.
-     * <p>Type: Integer. One of {@link TvInputManager#TIME_SHIFT_MODE_OFF},
+     * <p>Type: Integer. One of {@link TvInputManager#         *                  same as the ID sent here. This should be defined by the
+         *                  {@link TvInteractiveAppService} and can be any string.
+         *                  Should this API be called with the same requestId twice, both requests
+         *                  should be handled regardless by the TV application.TIME_SHIFT_MODE_OFF},
      * {@link TvInputManager#TIME_SHIFT_MODE_LOCAL},
      * {@link TvInputManager#TIME_SHIFT_MODE_NETWORK},
      * {@link TvInputManager#TIME_SHIFT_MODE_AUTO}.
@@ -630,6 +633,8 @@ public abstract class TvInteractiveAppService extends Service {
          *                  {@link #requestStartRecording(String, Uri)} is called.
          *                  {@code null} if the recording is not triggered by a
          *                  {@link #requestStartRecording(String, Uri)} request.
+         *                  This ID should be created by the {@link TvInteractiveAppService} and
+         *                  can be any string.
          * @see #onRecordingStopped(String)
          */
         public void onRecordingStarted(@NonNull String recordingId, @Nullable String requestId) {
@@ -708,6 +713,8 @@ public abstract class TvInteractiveAppService extends Service {
          * @param requestId The ID of the request when
          *                  {@link #requestScheduleRecording}  is called.
          *                  {@code null} if the recording is not triggered by a request.
+         *                  This ID should be created by the {@link TvInteractiveAppService} and
+         *                  can be any string.
          */
         public void onRecordingScheduled(@NonNull String recordingId, @Nullable String requestId) {
         }
@@ -1338,7 +1345,10 @@ public abstract class TvInteractiveAppService extends Service {
          * @param requestId The ID of this request which is used to match the corresponding
          *                  response. The request ID in
          *                  {@link #onRecordingStarted(String, String)} for this request is the
-         *                  same as the ID sent here.
+         *                  same as the ID sent here. This should be defined by the
+         *                  {@link TvInteractiveAppService} and can be any string.
+         *                  Should this API be called with the same requestId twice, both 
+         *                  requests should be handled regardless by the TV application.
          * @param programUri The URI for the TV program to record.
          * @see android.media.tv.TvRecordingClient#startRecording(Uri)
          */
@@ -1390,7 +1400,10 @@ public abstract class TvInteractiveAppService extends Service {
          * @param requestId The ID of this request which is used to match the corresponding
          *                  response. The request ID in
          *                  {@link #onRecordingScheduled(String, String)} for this request is the
-         *                  same as the ID sent here.
+         *                  same as the ID sent here. This should be defined by the
+         *                  {@link TvInteractiveAppService} and can be any string.
+         *                  Should this API be called with the same requestId twice, both requests
+         *                  should be handled regardless by the TV application.
          * @param inputId The ID of the TV input for the given channel.
          * @param channelUri The URI of a channel to be recorded.
          * @param programUri The URI of the TV program to be recorded.
@@ -1424,7 +1437,10 @@ public abstract class TvInteractiveAppService extends Service {
          * @param requestId The ID of this request which is used to match the corresponding
          *                  response. The request ID in
          *                  {@link #onRecordingScheduled(String, String)} for this request is the
-         *                  same as the ID sent here.
+         *                  same as the ID sent here. This should be defined by the
+         *                  {@link TvInteractiveAppService} and can be any string. Should this API
+         *                  be called with the same requestId twice, both requests should be handled
+         *                  regardless by the TV application.
          * @param inputId The ID of the TV input for the given channel.
          * @param channelUri The URI of a channel to be recorded.
          * @param startTime The start time of the recording in milliseconds since epoch.
diff --git a/media/java/android/media/tv/interactive/TvInteractiveAppView.java b/media/java/android/media/tv/interactive/TvInteractiveAppView.java
index a894cd800e81..f51e8a33bc3a 100755
--- a/media/java/android/media/tv/interactive/TvInteractiveAppView.java
+++ b/media/java/android/media/tv/interactive/TvInteractiveAppView.java
@@ -675,6 +675,8 @@ public class TvInteractiveAppView extends ViewGroup {
      * @param requestId The ID of the request when
      *                  {@link TvInteractiveAppService.Session#requestStartRecording(String, Uri)}
      *                  is called. {@code null} if the recording is not triggered by a request.
+     *                  This ID should be created by the {@link TvInteractiveAppService} and
+     *                  can be any string.
      * @see TvInteractiveAppView#notifyRecordingStopped(String)
      */
     public void notifyRecordingStarted(@NonNull String recordingId, @Nullable String requestId) {
@@ -922,6 +924,8 @@ public class TvInteractiveAppView extends ViewGroup {
      * @param requestId The ID of the request when
      *                  {@link TvInteractiveAppService.Session#requestScheduleRecording} is called.
      *                  {@code null} if the recording is not triggered by a request.
+     *                  This ID should be created by the {@link TvInteractiveAppService} and
+     *                  can be any string.
      */
     public void notifyRecordingScheduled(
             @NonNull String recordingId, @Nullable String requestId) {
@@ -1214,14 +1218,17 @@ public class TvInteractiveAppView extends ViewGroup {
         }
 
         /**
-         * This is called when {@link TvInteractiveAppService.Session#requestStartRecording(Uri)}
-         * is called.
+         * This is called when
+         * {@link TvInteractiveAppService.Session#requestStartRecording(String, Uri)} is called.
          *
          * @param iAppServiceId The ID of the TV interactive app service bound to this view.
          * @param requestId The ID of this request which is used to match the corresponding
          *                  response. The request ID in
-         *                  {@link #notifyRecordingStarted(String, String)}
-         *                  for this request should be the same as the ID received here.
+         *                  {@link #notifyRecordingStarted(String, String)}  for this request is the
+         *                  same as the ID sent here. This should be defined by the
+         *                  TIAS and can be any string. Should this API be called with the
+         *                  same requestId twice, both requests should be handled regardless
+         *                  by the TV application.
          * @param programUri The URI of the program to record
          *
          */
@@ -1252,8 +1259,11 @@ public class TvInteractiveAppView extends ViewGroup {
          * @param iAppServiceId The ID of the TV interactive app service bound to this view.
          * @param requestId The ID of this request which is used to match the corresponding
          *                  response. The request ID in
-         *                  {@link #notifyRecordingScheduled(String, String)} for this request
-         *                  should be the same as the ID received here.
+         *                  {@link #notifyRecordingScheduled(String, String)} for this request is
+         *                  the same as the ID sent here. This should be defined by the
+         *                  TIAS and can be any string. Should this API be called with the
+         *                  same requestId twice, both requests should be handled regardless
+         *                  by the TV application.
          * @param inputId The ID of the TV input for the given channel.
          * @param channelUri The URI of a channel to be recorded.
          * @param programUri The URI of the TV program to be recorded.
@@ -1276,8 +1286,11 @@ public class TvInteractiveAppView extends ViewGroup {
          * @param iAppServiceId The ID of the TV interactive app service bound to this view.
          * @param requestId The ID of this request which is used to match the corresponding
          *                  response. The request ID in
-         *                  {@link #notifyRecordingScheduled(String, String)} for this request
-         *                  should be the same as the ID received here.
+         *                  {@link #notifyRecordingScheduled(String, String)} for this request is
+         *                  the same as the ID sent here. This should be defined by the
+         *                  TIAS and can be any string. Should this API be called with the
+         *                  same requestId twice, both requests should be handled regardless
+         *                  by the TV application.
          * @param inputId The ID of the TV input for the given channel.
          * @param channelUri The URI of a channel to be recorded.
          * @param startTime The start time of the recording in milliseconds since epoch.