From 4e3ded556100f674ccba0d0e40adcbd0d30f9b23 Mon Sep 17 00:00:00 2001 From: Jae Seo Date: Wed, 13 Apr 2016 17:32:52 -0700 Subject: [PATCH] TIF: Update documentation on time shifting start/current position Now that we use the same set of API for both time shifting and recording, the descriptions should be updated to support both use cases. Bug: 28067038 Change-Id: I036446eca373ca27005f74b008a259f27b7c5f61 --- .../java/android/media/tv/TvInputManager.java | 15 +++------- .../java/android/media/tv/TvInputService.java | 23 +++++++------- media/java/android/media/tv/TvView.java | 30 ++++++++++--------- 3 files changed, 33 insertions(+), 35 deletions(-) diff --git a/media/java/android/media/tv/TvInputManager.java b/media/java/android/media/tv/TvInputManager.java index b4536b1135810..c3aa0ea16072b 100644 --- a/media/java/android/media/tv/TvInputManager.java +++ b/media/java/android/media/tv/TvInputManager.java @@ -483,26 +483,19 @@ public final class TvInputManager { } /** - * This is called when the start playback position is changed. - * - *

The start playback position of the time shifted program should be adjusted when the TV - * input cannot retain the whole recorded program due to some reason (e.g. limitation on - * storage space). This is necessary to prevent the application from allowing the user to - * seek to a time position that is not reachable. + * This is called when the start position for time shifting has changed. * * @param session A {@link TvInputManager.Session} associated with this callback. - * @param timeMs The start playback position of the time shifted program, in milliseconds - * since the epoch. + * @param timeMs The start position for time shifting, in milliseconds since the epoch. */ public void onTimeShiftStartPositionChanged(Session session, long timeMs) { } /** - * This is called when the current playback position is changed. + * This is called when the current position for time shifting is changed. * * @param session A {@link TvInputManager.Session} associated with this callback. - * @param timeMs The current playback position of the time shifted program, in milliseconds - * since the epoch. + * @param timeMs The current position for time shifting, in milliseconds since the epoch. */ public void onTimeShiftCurrentPositionChanged(Session session, long timeMs) { } diff --git a/media/java/android/media/tv/TvInputService.java b/media/java/android/media/tv/TvInputService.java index 97ef6d83607d4..479389b55333e 100644 --- a/media/java/android/media/tv/TvInputService.java +++ b/media/java/android/media/tv/TvInputService.java @@ -995,15 +995,18 @@ public abstract class TvInputService extends Service { } /** - * Returns the start playback position for time shifting, in milliseconds since the epoch. + * Returns the start position for time shifting, in milliseconds since the epoch. * Returns {@link TvInputManager#TIME_SHIFT_INVALID_TIME} if the position is unknown at the * moment. * - *

The start playback position of the time shifted program should be adjusted when the - * implementation cannot retain the whole recorded program due to some reason (e.g. - * limitation on storage space). It is the earliest possible time position that the user can - * seek to, thus failure to notifying its change immediately might result in bad experience - * where the application allows the user to seek to an invalid time position. + *

The start position for time shifting indicates the earliest possible time the user can + * seek to. Initially this is equivalent to the time when the implementation starts + * recording. Later it may be adjusted because there is insufficient space or the duration + * of recording is limited by the implementation. The application does not allow the user to + * seek to a position earlier than the start position. + * + *

For playback of a recorded program initiated by {@link #onTimeShiftPlay(Uri)}, the + * start position is the time when playback starts. It does not change. * * @see #onTimeShiftPlay(Uri) * @see #onTimeShiftResume() @@ -1017,13 +1020,13 @@ public abstract class TvInputService extends Service { } /** - * Returns the current playback position for time shifting, in milliseconds since the epoch. + * Returns the current position for time shifting, in milliseconds since the epoch. * Returns {@link TvInputManager#TIME_SHIFT_INVALID_TIME} if the position is unknown at the * moment. * - *

Note that the current playback position should be equal to or greater than the start - * playback position reported by {@link #onTimeShiftGetStartPosition}. Failure to notifying - * the correct current position might lead to bad user experience. + *

The current position for time shifting is the same as the current position of + * playback. It should be equal to or greater than the start position reported by + * {@link #onTimeShiftGetStartPosition()}. * * @see #onTimeShiftPlay(Uri) * @see #onTimeShiftResume() diff --git a/media/java/android/media/tv/TvView.java b/media/java/android/media/tv/TvView.java index 02ee0cc8deb52..4d53b75416135 100644 --- a/media/java/android/media/tv/TvView.java +++ b/media/java/android/media/tv/TvView.java @@ -847,32 +847,34 @@ public class TvView extends ViewGroup { public abstract static class TimeShiftPositionCallback { /** - * This is called when the start playback position is changed. + * This is called when the start position for time shifting has changed. * - *

The start playback position of the time shifted program can be adjusted by the TV - * input when it cannot retain the whole recorded program due to some reason (e.g. - * limitation on storage space). The application should not allow the user to seek to a - * position earlier than the start position. + *

The start position for time shifting indicates the earliest possible time the user can + * seek to. Initially this is equivalent to the time when the underlying TV input starts + * recording. Later it may be adjusted because there is insufficient space or the duration + * of recording is limited. The application must not allow the user to seek to a position + * earlier than the start position. * - *

Note that {@code timeMs} is not relative time in the program but wall-clock time, - * which is intended to avoid calling this method unnecessarily around program boundaries. + *

For playback of a recorded program initiated by {@link #timeShiftPlay(String, Uri)}, + * the start position is the time when playback starts. It does not change. * * @param inputId The ID of the TV input bound to this view. - * @param timeMs The start playback position of the time shifted program, in milliseconds - * since the epoch. + * @param timeMs The start position for time shifting, in milliseconds since the epoch. */ public void onTimeShiftStartPositionChanged(String inputId, long timeMs) { } /** - * This is called when the current playback position is changed. + * This is called when the current position for time shifting has changed. * - *

Note that {@code timeMs} is not relative time in the program but wall-clock time, - * which is intended to avoid calling this method unnecessarily around program boundaries. + *

The current position for time shifting is the same as the current position of + * playback. During playback, the current position changes continuously. When paused, it + * does not change. + * + *

Note that {@code timeMs} is wall-clock time. * * @param inputId The ID of the TV input bound to this view. - * @param timeMs The current playback position of the time shifted program, in milliseconds - * since the epoch. + * @param timeMs The current position for time shifting, in milliseconds since the epoch. */ public void onTimeShiftCurrentPositionChanged(String inputId, long timeMs) { }