Merge "TIF: Update documentation on time shifting start/current position" into nyc-dev (abaa3395) · Commits · e / os / android_frameworks_base

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

+4 −11

Original line number	Diff line number	Diff line
		@@ -483,26 +483,19 @@ public final class TvInputManager {
		}

		/**
		* 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) {
		}

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

+13 −10

Original line number	Diff line number	Diff line
		@@ -996,15 +996,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.
		*
		* <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()
		@@ -1018,13 +1021,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.
		*
		* <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()

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

+16 −14

Original line number	Diff line number	Diff line
		@@ -848,32 +848,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.
		*
		* <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) {
		}