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
diff --git a/media/java/android/media/tv/TvInputManager.java b/media/java/android/media/tv/TvInputManager.java
index b4536b1..c3aa0ea 100644
--- a/media/java/android/media/tv/TvInputManager.java
+++ b/media/java/android/media/tv/TvInputManager.java
@@ -483,26 +483,19 @@
}
/**
- * This is called when the start playback position is changed.
- *
- * <p>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 97ef6d8..479389b 100644
--- a/media/java/android/media/tv/TvInputService.java
+++ b/media/java/android/media/tv/TvInputService.java
@@ -995,15 +995,18 @@
}
/**
- * 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.
*
- * <p>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.
+ * <p>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.
+ *
+ * <p>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 @@
}
/**
- * 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.
*
- * <p>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.
+ * <p>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 02ee0cc..4d53b75 100644
--- a/media/java/android/media/tv/TvView.java
+++ b/media/java/android/media/tv/TvView.java
@@ -847,32 +847,34 @@
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.
*
- * <p>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.
+ * <p>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.
*
- * <p>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.
+ * <p>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.
*
- * <p>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.
+ * <p>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.
+ *
+ * <p>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) {
}