public abstract static class TvInputService.Session extends Object implements KeyEvent.Callback
Constructor and Description |
---|
Session(Context context)
Creates a new Session.
|
Modifier and Type | Method and Description |
---|---|
void |
layoutSurface(int left,
int top,
int right,
int bottom)
Assigns a size and position to the surface passed in
onSetSurface(android.view.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 |
notifySessionEvent(String eventType,
Bundle eventArgs)
Dispatches an event to the application using this session.
|
void |
notifyTimeShiftStatusChanged(int status)
Informs the application that the time shift status is changed.
|
void |
notifyTracksChanged(List<TvTrackInfo> tracks)
Sends the list of all audio/video/subtitle tracks.
|
void |
notifyTrackSelected(int type,
String trackId)
Sends the type and ID of a selected track.
|
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.
|
void |
onAppPrivateCommand(String action,
Bundle data)
Processes a private command sent from the application to the TV input.
|
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.
|
void |
onSetMain(boolean isMain)
Sets the current session as the main session.
|
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(android.view.Surface) . |
long |
onTimeShiftGetCurrentPosition()
Returns the current position for time shifting, in milliseconds since the epoch.
|
long |
onTimeShiftGetStartPosition()
Returns the start position for time shifting, in milliseconds since the epoch.
|
void |
onTimeShiftPause()
Called when the application requests to pause playback.
|
void |
onTimeShiftPlay(Uri recordedProgramUri)
Called when the application requests to play a given recorded TV program.
|
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.
|
boolean |
onTune(Uri channelUri,
Bundle params)
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.
|
public Session(Context context)
context
- The context of the applicationpublic void setOverlayViewEnabled(boolean enable)
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.
enable
- true
if you want to enable the overlay view. false
otherwise.public void notifySessionEvent(String eventType, Bundle eventArgs)
eventType
- The type of the event.eventArgs
- Optional arguments of the event.public void notifyChannelRetuned(Uri channelUri)
channelUri
- The URI of the new channel.public void notifyTracksChanged(List<TvTrackInfo> tracks)
TvView.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.tracks
- A list which includes track information.public void notifyTrackSelected(int type, String trackId)
onSelectTrack(int, java.lang.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.type
- The type of the selected track. The type can be
TvTrackInfo.TYPE_AUDIO
, TvTrackInfo.TYPE_VIDEO
or
TvTrackInfo.TYPE_SUBTITLE
.trackId
- The ID of the selected track.onSelectTrack(int, java.lang.String)
public void notifyVideoAvailable()
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(android.net.Uri)
is called.
notifyVideoUnavailable(int)
public void notifyVideoUnavailable(int reason)
reason
- The reason why the video became unavailable:
notifyVideoAvailable()
public void notifyContentAllowed()
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
TvInputManager.ACTION_BLOCKED_RATINGS_CHANGED
and
TvInputManager.ACTION_PARENTAL_CONTROLS_ENABLED_CHANGED
and immediately
reevaluate the current program with the new parental controls settings.
public void notifyContentBlocked(TvContentRating rating)
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 TvContentRating.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
TvInputManager.ACTION_BLOCKED_RATINGS_CHANGED
and
TvInputManager.ACTION_PARENTAL_CONTROLS_ENABLED_CHANGED
and immediately
reevaluate the current program with the new parental controls settings.
rating
- The content rating for the current TV program. Can be
TvContentRating.UNRATED
.notifyContentAllowed()
,
TvInputManager
public void notifyTimeShiftStatusChanged(int status)
Prior to calling this method, the application assumes the status
TvInputManager.TIME_SHIFT_STATUS_UNKNOWN
. Right after the session is created, it
is important to invoke the method with the status
TvInputManager.TIME_SHIFT_STATUS_AVAILABLE
if the implementation does support
time shifting, or TvInputManager.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 TvInputManager.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(android.media.PlaybackParams)
.
status
- The current time shift status. Should be one of the followings.
public void layoutSurface(int left, int top, int right, int bottom)
onSetSurface(android.view.Surface)
. The position
is relative to the overlay view that sits on top of this surface.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.onOverlayViewSizeChanged(int, int)
public abstract void onRelease()
public void onSetMain(boolean isMain)
TV input service that manages HDMI-CEC logical device should implement onSetMain(boolean)
to (1) select the corresponding HDMI logical device as the source device
when isMain
is true
, and to (2) select the internal device (= TV itself)
as the source device when isMain
is false
and the session is still main.
Also, if a surface is passed to a non-main session and active source is changed to
initiate the surface, the active source should be returned to the main session.
TvView
guarantees that, when tuning involves a session transition, onSetMain(true)
for new session is called first, onSetMain(false)
for old
session is called afterwards. This allows onSetMain(false)
to be no-op when TV
input service knows that the next main session corresponds to another HDMI logical
device. Practically, this implies that one TV input service should handle all HDMI port
and HDMI-CEC logical devices for smooth active source transition.
isMain
- If true, session should become main.TvView.setMain()
public abstract boolean onSetSurface(Surface 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.
surface
- The surface to be used for video rendering. Can be null
.true
if the surface was set successfully, false
otherwise.public void onSurfaceChanged(int format, int width, int height)
onSetSurface(android.view.Surface)
. This method is always called at least once, after
onSetSurface(android.view.Surface)
is called with non-null surface.format
- The new PixelFormat of the surface.width
- The new width of the surface.height
- The new height of the surface.public void onOverlayViewSizeChanged(int width, int height)
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)
.
width
- The width of the overlay view.height
- The height of the overlay view.public abstract void onSetStreamVolume(float volume)
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
.
volume
- A volume value between 0.0f
to 1.0f
.public abstract boolean onTune(Uri channelUri)
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.
channelUri
- The URI of the channel.true
if the tuning was successful, false
otherwise.public boolean onTune(Uri channelUri, Bundle params)
The default implementation calls onTune(Uri)
.
channelUri
- The URI of the channel.params
- Domain-specific data for this tune request. Keys must be a scoped
name, i.e. prefixed with a package name you own, so that different developers
will not create conflicting keys.true
if the tuning was successful, false
otherwise.public abstract void onSetCaptionEnabled(boolean enabled)
The locale for the user's preferred captioning language can be obtained by calling
CaptioningManager.getLocale()
.
enabled
- true
to enable, false
to disable.CaptioningManager
public void onUnblockContent(TvContentRating unblockedRating)
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.
unblockedRating
- An unblocked content ratingpublic boolean onSelectTrack(int type, String trackId)
If this is done successfully, the implementation should call
notifyTrackSelected(int, java.lang.String)
to help applications maintain the up-to-date list of the
selected tracks.
trackId
- The ID of the track to select. null
means to unselect the current
track for a given type.type
- The type of the track to select. The type can be
TvTrackInfo.TYPE_AUDIO
, TvTrackInfo.TYPE_VIDEO
or
TvTrackInfo.TYPE_SUBTITLE
.true
if the track selection was successful, false
otherwise.notifyTrackSelected(int, java.lang.String)
public void onAppPrivateCommand(String action, Bundle data)
action
- Name of the command to be performed. This must be a scoped name,
i.e. prefixed with a package name you own, so that different developers will
not create conflicting commands.data
- Any data to include with the command.public View onCreateOverlayView()
public void onTimeShiftPlay(Uri recordedProgramUri)
recordedProgramUri
- The URI of a recorded TV program.onTimeShiftResume()
,
onTimeShiftPause()
,
onTimeShiftSeekTo(long)
,
onTimeShiftSetPlaybackParams(PlaybackParams)
,
onTimeShiftGetStartPosition()
,
onTimeShiftGetCurrentPosition()
public void onTimeShiftPause()
public void onTimeShiftResume()
public void onTimeShiftSeekTo(long timeMs)
timeMs
- The time position to seek to, in milliseconds since the epoch.onTimeShiftPlay(Uri)
,
onTimeShiftResume()
,
onTimeShiftPause()
,
onTimeShiftSetPlaybackParams(PlaybackParams)
,
onTimeShiftGetStartPosition()
,
onTimeShiftGetCurrentPosition()
public void onTimeShiftSetPlaybackParams(PlaybackParams params)
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.
params
- The playback params.onTimeShiftPlay(Uri)
,
onTimeShiftResume()
,
onTimeShiftPause()
,
onTimeShiftSeekTo(long)
,
onTimeShiftGetStartPosition()
,
onTimeShiftGetCurrentPosition()
public long onTimeShiftGetStartPosition()
TvInputManager.TIME_SHIFT_INVALID_TIME
if the position is unknown at the
moment.
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 onTimeShiftPlay(Uri)
, the
start position is the time when playback starts. It does not change.
public long onTimeShiftGetCurrentPosition()
TvInputManager.TIME_SHIFT_INVALID_TIME
if the position is unknown at the
moment.
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
onTimeShiftGetStartPosition()
.
public boolean onKeyDown(int keyCode, KeyEvent event)
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.
onKeyDown
in interface KeyEvent.Callback
keyCode
- The value in event.getKeyCode().event
- Description of the key event.true
. If you want to allow the event to
be handled by the next receiver, return false
.public boolean onKeyLongPress(int keyCode, KeyEvent event)
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.
onKeyLongPress
in interface KeyEvent.Callback
keyCode
- The value in event.getKeyCode().event
- Description of the key event.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)
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.
onKeyMultiple
in interface KeyEvent.Callback
keyCode
- The value in event.getKeyCode().count
- The number of times the action was made.event
- Description of the key event.true
. If you want to allow the event to
be handled by the next receiver, return false
.public boolean onKeyUp(int keyCode, KeyEvent event)
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.
onKeyUp
in interface KeyEvent.Callback
keyCode
- The value in event.getKeyCode().event
- Description of the key event.true
. If you want to allow the event to
be handled by the next receiver, return false
.public boolean onTouchEvent(MotionEvent event)
event
- The motion event being received.true
. If you want to allow the event to
be handled by the next receiver, return false
.View.onTouchEvent(android.view.MotionEvent)
public boolean onTrackballEvent(MotionEvent event)
event
- The motion event being received.true
. If you want to allow the event to
be handled by the next receiver, return false
.View.onTrackballEvent(android.view.MotionEvent)
public boolean onGenericMotionEvent(MotionEvent event)
event
- The motion event being received.true
. If you want to allow the event to
be handled by the next receiver, return false
.View.onGenericMotionEvent(android.view.MotionEvent)