Android APIs
public static abstract class

TvInputService.Session

extends Object
implements KeyEvent.Callback
java.lang.Object
   ↳ android.media.tv.TvInputService.Session
Known Direct Subclasses

Class Overview

Base class for derived classes to implement to provide a TV input session.

Summary

Public Constructors
TvInputService.Session(Context context)
Creates a new Session.
Public Methods
void layoutSurface(int left, int top, int right, int bottom)
Assigns a size and position to the surface passed in onSetSurface(Surface).
void notifyChannelRetuned(Uri channelUri)
Informs the application that the current channel is re-tuned for some reason and the session now displays the content from a new channel.
void notifyContentAllowed()
Informs the application that the user is allowed to watch the current program content.
void notifyContentBlocked(TvContentRating rating)
Informs the application that the current program content is blocked by parent controls.
void notifyTimeShiftStatusChanged(int status)
Informs the application that the time shift status is changed.
void notifyTrackSelected(int type, String trackId)
Sends the type and ID of a selected track.
void notifyTracksChanged(List<TvTrackInfo> tracks)
Sends the list of all audio/video/subtitle tracks.
void notifyVideoAvailable()
Informs the application that the video is now available for watching.
void notifyVideoUnavailable(int reason)
Informs the application that the video became unavailable for some reason.
View onCreateOverlayView()
Called when the application requests to create an overlay view.
boolean onGenericMotionEvent(MotionEvent event)
Implement this method to handle generic motion events on the current input session.
boolean onKeyDown(int keyCode, KeyEvent event)
Default implementation of KeyEvent.Callback.onKeyDown(): always returns false (doesn't handle the event).
boolean onKeyLongPress(int keyCode, KeyEvent event)
Default implementation of KeyEvent.Callback.onKeyLongPress(): always returns false (doesn't handle the event).
boolean onKeyMultiple(int keyCode, int count, KeyEvent event)
Default implementation of KeyEvent.Callback.onKeyMultiple(): always returns false (doesn't handle the event).
boolean onKeyUp(int keyCode, KeyEvent event)
Default implementation of KeyEvent.Callback.onKeyUp(): always returns false (doesn't handle the event).
void onOverlayViewSizeChanged(int width, int height)
Called when the size of the overlay view is changed by the application.
abstract void onRelease()
Called when the session is released.
boolean onSelectTrack(int type, String trackId)
Selects a given track.
abstract void onSetCaptionEnabled(boolean enabled)
Enables or disables the caption.
abstract void onSetStreamVolume(float volume)
Sets the relative stream volume of the current TV input session.
abstract boolean onSetSurface(Surface surface)
Called when the application sets the surface.
void onSurfaceChanged(int format, int width, int height)
Called after any structural changes (format or size) have been made to the surface passed in onSetSurface(Surface).
long onTimeShiftGetCurrentPosition()
Returns the current playback position for time shifting, in milliseconds since the epoch.
long onTimeShiftGetStartPosition()
Returns the start playback position for time shifting, in milliseconds since the epoch.
void onTimeShiftPause()
Called when the application requests to pause playback.
void onTimeShiftResume()
Called when the application requests to resume playback.
void onTimeShiftSeekTo(long timeMs)
Called when the application requests to seek to a specified time position.
void onTimeShiftSetPlaybackParams(PlaybackParams params)
Called when the application sets playback parameters containing the speed and audio mode.
boolean onTouchEvent(MotionEvent event)
Implement this method to handle touch screen motion events on the current input session.
boolean onTrackballEvent(MotionEvent event)
Implement this method to handle trackball events on the current input session.
abstract boolean onTune(Uri channelUri)
Tunes to a given channel.
void onUnblockContent(TvContentRating unblockedRating)
Requests to unblock the content according to the given rating.
void setOverlayViewEnabled(boolean enable)
Enables or disables the overlay view.
[Expand]
Inherited Methods
From class java.lang.Object
From interface android.view.KeyEvent.Callback

Public Constructors

public TvInputService.Session (Context context)

Added in API level 21

Creates a new Session.

Parameters
context The context of the application

Public Methods

public void layoutSurface (int left, int top, int right, int bottom)

Added in API level 23

Assigns a size and position to the surface passed in onSetSurface(Surface). The position is relative to the overlay view that sits on top of this surface.

Parameters
left Left position in pixels, relative to the overlay view.
top Top position in pixels, relative to the overlay view.
right Right position in pixels, relative to the overlay view.
bottom Bottom position in pixels, relative to the overlay view.

public void notifyChannelRetuned (Uri channelUri)

Added in API level 21

Informs the application that the current channel is re-tuned for some reason and the session now displays the content from a new channel. This is used to handle special cases such as when the current channel becomes unavailable, it is necessary to send the user to a certain channel or the user changes channel in some other way (e.g. by using a dedicated remote).

Parameters
channelUri The URI of the new channel.

public void notifyContentAllowed ()

Added in API level 21

Informs the application that the user is allowed to watch the current program content.

Each TV input service is required to query the system whether the user is allowed to watch the current program before showing it to the user if the parental controls is enabled (i.e. TvInputManager.isParentalControlsEnabled() returns true). Whether the TV input service should block the content or not is determined by invoking TvInputManager.isRatingBlocked(TvContentRating) with the content rating for the current program. Then the TvInputManager makes a judgment based on the user blocked ratings stored in the secure settings and returns the result. If the rating in question turns out to be allowed by the user, the TV input service must call this method to notify the application that is permitted to show the content.

Each TV input service also needs to continuously listen to any changes made to the parental controls settings by registering a broadcast receiver to receive ACTION_BLOCKED_RATINGS_CHANGED and ACTION_PARENTAL_CONTROLS_ENABLED_CHANGED and immediately reevaluate the current program with the new parental controls settings.

public void notifyContentBlocked (TvContentRating rating)

Added in API level 21

Informs the application that the current program content is blocked by parent controls.

Each TV input service is required to query the system whether the user is allowed to watch the current program before showing it to the user if the parental controls is enabled (i.e. TvInputManager.isParentalControlsEnabled() returns true). Whether the TV input service should block the content or not is determined by invoking TvInputManager.isRatingBlocked(TvContentRating) with the content rating for the current program or UNRATED in case the rating information is missing. Then the TvInputManager makes a judgment based on the user blocked ratings stored in the secure settings and returns the result. If the rating in question turns out to be blocked, the TV input service must immediately block the content and call this method with the content rating of the current program to prompt the PIN verification screen.

Each TV input service also needs to continuously listen to any changes made to the parental controls settings by registering a broadcast receiver to receive ACTION_BLOCKED_RATINGS_CHANGED and ACTION_PARENTAL_CONTROLS_ENABLED_CHANGED and immediately reevaluate the current program with the new parental controls settings.

Parameters
rating The content rating for the current TV program. Can be UNRATED.

public void notifyTimeShiftStatusChanged (int status)

Added in API level 23

Informs the application that the time shift status is changed.

Prior to calling this method, the application assumes the status TIME_SHIFT_STATUS_UNKNOWN. Right after the session is created, it is important to invoke the method with the status TIME_SHIFT_STATUS_AVAILABLE if the implementation does support time shifting, or TIME_SHIFT_STATUS_UNSUPPORTED otherwise. Failure to notifying the current status change immediately might result in an undesirable behavior in the application such as hiding the play controls.

If the status TIME_SHIFT_STATUS_AVAILABLE is reported, the application assumes it can pause/resume playback, seek to a specified time position and set playback rate and audio mode. The implementation should override onTimeShiftPause(), onTimeShiftResume(), onTimeShiftSeekTo(long), onTimeShiftGetStartPosition(), onTimeShiftGetCurrentPosition() and onTimeShiftSetPlaybackParams(PlaybackParams).

Parameters
status The current time shift status. Should be one of the followings.

public void notifyTrackSelected (int type, String trackId)

Added in API level 21

Sends the type and ID of a selected track. This is used to inform the application that a specific track is selected. The TV input service must call this method as soon as a track is selected either by default or in response to a call to onSelectTrack(int, String). The selected track ID for a given type is maintained in the framework until the next call to this method even after the entire track list is updated (but is reset when the session is tuned to a new channel), so care must be taken not to result in an obsolete track ID.

Parameters
type The type of the selected track. The type can be TYPE_AUDIO, TYPE_VIDEO or TYPE_SUBTITLE.
trackId The ID of the selected track.

public void notifyTracksChanged (List<TvTrackInfo> tracks)

Added in API level 21

Sends the list of all audio/video/subtitle tracks. The is used by the framework to maintain the track information for a given session, which in turn is used by getTracks(int) for the application to retrieve metadata for a given track type. The TV input service must call this method as soon as the track information becomes available or is updated. Note that in a case where a part of the information for a certain track is updated, it is not necessary to create a new TvTrackInfo object with a different track ID.

Parameters
tracks A list which includes track information.
Throws
IllegalArgumentException if tracks contains redundant tracks.

public void notifyVideoAvailable ()

Added in API level 21

Informs the application that the video is now available for watching. Video is blocked until this method is called.

The TV input service must call this method as soon as the content rendered onto its surface is ready for viewing. This method must be called each time onTune(Uri) is called.

public void notifyVideoUnavailable (int reason)

Added in API level 21

Informs the application that the video became unavailable for some reason. This is primarily used to signal the application to block the screen not to show any intermittent video artifacts.

public View onCreateOverlayView ()

Added in API level 21

Called when the application requests to create an overlay view. Each session implementation can override this method and return its own view.

Returns
  • a view attached to the overlay window

public boolean onGenericMotionEvent (MotionEvent event)

Added in API level 21

Implement this method to handle generic motion events on the current input session.

Parameters
event The motion event being received.
Returns
  • If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

public boolean onKeyDown (int keyCode, KeyEvent event)

Added in API level 21

Default implementation of KeyEvent.Callback.onKeyDown(): always returns false (doesn't handle the event).

Override this to intercept key down events before they are processed by the application. If you return true, the application will not process the event itself. If you return false, the normal application processing will occur as if the TV input had not seen the event at all.

Parameters
keyCode The value in event.getKeyCode().
event Description of the key event.
Returns
  • If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

public boolean onKeyLongPress (int keyCode, KeyEvent event)

Added in API level 21

Default implementation of KeyEvent.Callback.onKeyLongPress(): always returns false (doesn't handle the event).

Override this to intercept key long press events before they are processed by the application. If you return true, the application will not process the event itself. If you return false, the normal application processing will occur as if the TV input had not seen the event at all.

Parameters
keyCode The value in event.getKeyCode().
event Description of the key event.
Returns
  • If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

public boolean onKeyMultiple (int keyCode, int count, KeyEvent event)

Added in API level 21

Default implementation of KeyEvent.Callback.onKeyMultiple(): always returns false (doesn't handle the event).

Override this to intercept special key multiple events before they are processed by the application. If you return true, the application will not itself process the event. If you return false, the normal application processing will occur as if the TV input had not seen the event at all.

Parameters
keyCode The value in event.getKeyCode().
count The number of times the action was made.
event Description of the key event.
Returns
  • If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

public boolean onKeyUp (int keyCode, KeyEvent event)

Added in API level 21

Default implementation of KeyEvent.Callback.onKeyUp(): always returns false (doesn't handle the event).

Override this to intercept key up events before they are processed by the application. If you return true, the application will not itself process the event. If you return false, the normal application processing will occur as if the TV input had not seen the event at all.

Parameters
keyCode The value in event.getKeyCode().
event Description of the key event.
Returns
  • If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

public void onOverlayViewSizeChanged (int width, int height)

Added in API level 23

Called when the size of the overlay view is changed by the application.

This is always called at least once when the session is created regardless of whether the overlay view is enabled or not. The overlay view size is the same as the containing TvView. Note that the size of the underlying surface can be different if the surface was changed by calling layoutSurface(int, int, int, int).

Parameters
width The width of the overlay view.
height The height of the overlay view.

public abstract void onRelease ()

Added in API level 21

Called when the session is released.

public boolean onSelectTrack (int type, String trackId)

Added in API level 21

Selects a given track.

If this is done successfully, the implementation should call notifyTrackSelected(int, String) to help applications maintain the up-to-date list of the selected tracks.

Parameters
type The type of the track to select. The type can be TYPE_AUDIO, TYPE_VIDEO or TYPE_SUBTITLE.
trackId The ID of the track to select. null means to unselect the current track for a given type.
Returns
  • true if the track selection was successful, false otherwise.

public abstract void onSetCaptionEnabled (boolean enabled)

Added in API level 21

Enables or disables the caption.

The locale for the user's preferred captioning language can be obtained by calling CaptioningManager.getLocale().

Parameters
enabled true to enable, false to disable.

public abstract void onSetStreamVolume (float volume)

Added in API level 21

Sets the relative stream volume of the current TV input session.

The implementation should honor this request in order to handle audio focus changes or mute the current session when multiple sessions, possibly from different inputs are active. If the method has not yet been called, the implementation should assume the default value of 1.0f.

Parameters
volume A volume value between 0.0f to 1.0f.

public abstract boolean onSetSurface (Surface surface)

Added in API level 21

Called when the application sets the surface.

The TV input service should render video onto the given surface. When called with null, the input service should immediately release any references to the currently set surface and stop using it.

Parameters
surface The surface to be used for video rendering. Can be null.
Returns
  • true if the surface was set successfully, false otherwise.

public void onSurfaceChanged (int format, int width, int height)

Added in API level 21

Called after any structural changes (format or size) have been made to the surface passed in onSetSurface(Surface). This method is always called at least once, after onSetSurface(Surface) is called with non-null surface.

Parameters
format The new PixelFormat of the surface.
width The new width of the surface.
height The new height of the surface.

public long onTimeShiftGetCurrentPosition ()

Added in API level 23

Returns the current playback position for time shifting, in milliseconds since the epoch. Returns 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 onTimeShiftGetStartPosition(). Failure to notifying the correct current position might lead to bad user experience.

public long onTimeShiftGetStartPosition ()

Added in API level 23

Returns the start playback position for time shifting, in milliseconds since the epoch. Returns 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.

public void onTimeShiftPause ()

Added in API level 23

public void onTimeShiftResume ()

Added in API level 23

public void onTimeShiftSeekTo (long timeMs)

Added in API level 23

Called when the application requests to seek to a specified time position. Normally, the position is given within range between the start and the current time, inclusively. The implementation is expected to seek to the nearest time position if the given position is not in the range.

Parameters
timeMs The time position to seek to, in milliseconds since the epoch.

public void onTimeShiftSetPlaybackParams (PlaybackParams params)

Added in API level 23

Called when the application sets playback parameters containing the speed and audio mode.

Once the playback parameters are set, the implementation should honor the current settings until the next tune request. Pause/resume/seek request does not reset the parameters previously set.

Parameters
params The playback params.

public boolean onTouchEvent (MotionEvent event)

Added in API level 21

Implement this method to handle touch screen motion events on the current input session.

Parameters
event The motion event being received.
Returns
  • If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

public boolean onTrackballEvent (MotionEvent event)

Added in API level 21

Implement this method to handle trackball events on the current input session.

Parameters
event The motion event being received.
Returns
  • If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

public abstract boolean onTune (Uri channelUri)

Added in API level 21

Tunes to a given channel.

No video will be displayed until notifyVideoAvailable() is called. Also, notifyVideoUnavailable(int) should be called when the TV input cannot continue playing the given channel.

Parameters
channelUri The URI of the channel.
Returns
  • true if the tuning was successful, false otherwise.

public void onUnblockContent (TvContentRating unblockedRating)

Added in API level 21

Requests to unblock the content according to the given rating.

The implementation should unblock the content. TV input service has responsibility to decide when/how the unblock expires while it can keep previously unblocked ratings in order not to ask a user to unblock whenever a content rating is changed. Therefore an unblocked rating can be valid for a channel, a program, or certain amount of time depending on the implementation.

Parameters
unblockedRating An unblocked content rating

public void setOverlayViewEnabled (boolean enable)

Added in API level 21

Enables or disables the overlay view.

By default, the overlay view is disabled. Must be called explicitly after the session is created to enable the overlay view.

The TV input service can disable its overlay view when the size of the overlay view is insufficient to display the whole information, such as when used in Picture-in-picture. Override onOverlayViewSizeChanged(int, int) to get the size of the overlay view, which then can be used to determine whether to enable/disable the overlay view.

Parameters
enable true if you want to enable the overlay view. false otherwise.