MediaSession.SessionCallback
public
static
abstract
class
MediaSession.SessionCallback
extends Object
java.lang.Object | |
↳ | androidx.media2.session.MediaSession.SessionCallback |
Callback to be called for all incoming commands from MediaController
s.
If it's not set, the session will accept all controllers and all incoming commands by default.
Summary
Public constructors | |
---|---|
SessionCallback()
|
Public methods | |
---|---|
int
|
onCommandRequest(MediaSession session, MediaSession.ControllerInfo controller, SessionCommand command)
Called when a controller sent a command which will be sent directly to one of the following:
Return |
SessionCommandGroup
|
onConnect(MediaSession session, MediaSession.ControllerInfo controller)
Called when a controller is created for this session. |
MediaItem
|
onCreateMediaItem(MediaSession session, MediaSession.ControllerInfo controller, String mediaId)
Called when a controller has sent a command with a |
SessionResult
|
onCustomCommand(MediaSession session, MediaSession.ControllerInfo controller, SessionCommand customCommand, Bundle args)
Called when a controller sent a custom command through
|
void
|
onDisconnected(MediaSession session, MediaSession.ControllerInfo controller)
Called when a controller is disconnected. |
int
|
onFastForward(MediaSession session, MediaSession.ControllerInfo controller)
Called when a controller called |
void
|
onPostConnect(MediaSession session, MediaSession.ControllerInfo controller)
Called immediately after a controller is connected. |
int
|
onRewind(MediaSession session, MediaSession.ControllerInfo controller)
Called when a controller called |
int
|
onSetMediaUri(MediaSession session, MediaSession.ControllerInfo controller, Uri uri, Bundle extras)
Called when a controller requested to set the specific media item(s) represented by a URI
through |
int
|
onSetRating(MediaSession session, MediaSession.ControllerInfo controller, String mediaId, Rating rating)
Called when a controller set rating of a media item through
|
int
|
onSkipBackward(MediaSession session, MediaSession.ControllerInfo controller)
Called when a controller called |
int
|
onSkipForward(MediaSession session, MediaSession.ControllerInfo controller)
Called when a controller called |
Inherited methods | |
---|---|
Public constructors
SessionCallback
public SessionCallback ()
Public methods
onCommandRequest
public int onCommandRequest (MediaSession session, MediaSession.ControllerInfo controller, SessionCommand command)
Called when a controller sent a command which will be sent directly to one of the following:
Return SessionResult.RESULT_SUCCESS
to proceed the command. If something
else is returned, command wouldn't be sent and the controller would receive the code with
it.
Parameters | |
---|---|
session |
MediaSession : the session for this event |
controller |
MediaSession.ControllerInfo : controller information. |
command |
SessionCommand : a command. This method will be called for every single command. |
Returns | |
---|---|
int |
RESULT_SUCCESS if you want to proceed with incoming command.
Another code for ignore. |
See also:
SessionCommand.COMMAND_CODE_PLAYER_PLAY
SessionCommand.COMMAND_CODE_PLAYER_PAUSE
SessionCommand.COMMAND_CODE_PLAYER_SKIP_TO_NEXT_PLAYLIST_ITEM
SessionCommand.COMMAND_CODE_PLAYER_SKIP_TO_PREVIOUS_PLAYLIST_ITEM
SessionCommand.COMMAND_CODE_PLAYER_PREPARE
SessionCommand.COMMAND_CODE_PLAYER_SEEK_TO
SessionCommand.COMMAND_CODE_PLAYER_SKIP_TO_PLAYLIST_ITEM
SessionCommand.COMMAND_CODE_PLAYER_SET_SHUFFLE_MODE
SessionCommand.COMMAND_CODE_PLAYER_SET_REPEAT_MODE
SessionCommand.COMMAND_CODE_PLAYER_ADD_PLAYLIST_ITEM
SessionCommand.COMMAND_CODE_PLAYER_REMOVE_PLAYLIST_ITEM
SessionCommand.COMMAND_CODE_PLAYER_REPLACE_PLAYLIST_ITEM
SessionCommand.COMMAND_CODE_PLAYER_GET_PLAYLIST
SessionCommand.COMMAND_CODE_PLAYER_SET_PLAYLIST
SessionCommand.COMMAND_CODE_PLAYER_GET_PLAYLIST_METADATA
SessionCommand.COMMAND_CODE_PLAYER_UPDATE_LIST_METADATA
SessionCommand.COMMAND_CODE_VOLUME_SET_VOLUME
SessionCommand.COMMAND_CODE_VOLUME_ADJUST_VOLUME
onConnect
public SessionCommandGroup onConnect (MediaSession session, MediaSession.ControllerInfo controller)
Called when a controller is created for this session. Return allowed commands for controller. By default it allows all connection requests and commands.
You can reject the connection by return null
. In that case, the controller
receives MediaController.ControllerCallback.onDisconnected(MediaController)
and
cannot be used.
The controller hasn't connected yet in this method, so calls to the controller
(e.g. MediaSession.sendCustomCommand(MediaSession.ControllerInfo, SessionCommand, Bundle)
, MediaSession.setCustomLayout(MediaSession.ControllerInfo, List
) would be ignored. Override
onPostConnect(MediaSession, MediaSession.ControllerInfo)
for the custom initialization for the controller instead.
Parameters | |
---|---|
session |
MediaSession : the session for this event |
controller |
MediaSession.ControllerInfo : controller information. |
Returns | |
---|---|
SessionCommandGroup |
allowed commands. Can be null to reject connection. |
onCreateMediaItem
public MediaItem onCreateMediaItem (MediaSession session, MediaSession.ControllerInfo controller, String mediaId)
Called when a controller has sent a command with a MediaItem
to add a new media
item to this session. Being specific, this will be called for following APIs.
MediaController.addPlaylistItem(int, String)
MediaController.replacePlaylistItem(int, String)
MediaController.setPlaylist(List, MediaMetadata)
MediaController.setMediaItem(String)
mediaId
to a MediaItem
to be
understood by your player. For example, a player may only understand
FileMediaItem
, UriMediaItem
,
and CallbackMediaItem
. Check the documentation of the player that you're using.
If the given media ID is valid, you should return the media item with the given media ID.
If the ID doesn't match, an RuntimeException
will be thrown.
You may return null
if the given item is invalid. Here's the behavior when it
happens.
Controller command | Behavior when null is returned |
---|---|
addPlaylistItem | Ignore |
replacePlaylistItem | Ignore |
setPlaylist | Ignore null items, and build a list with non-null items. Call
SessionPlayer.setPlaylist(List, MediaMetadata) with the list |
setMediaItem | Ignore |
This will be called on the same thread where onCommandRequest(MediaSession, MediaSession.ControllerInfo, SessionCommand)
and commands with
the media controller will be executed.
Default implementation returns the null
.
Parameters | |
---|---|
session |
MediaSession : the session for this event |
controller |
MediaSession.ControllerInfo : controller information |
mediaId |
String : non-empty media id for creating item with |
Returns | |
---|---|
MediaItem |
translated media item for player with the mediaId. Can be null to ignore. |
See also:
onCustomCommand
public SessionResult onCustomCommand (MediaSession session, MediaSession.ControllerInfo controller, SessionCommand customCommand, Bundle args)
Called when a controller sent a custom command through
MediaController.sendCustomCommand(SessionCommand, Bundle)
.
Interoperability: This would be also called by #sendCustomAction(String, Bundle, CustomActionCallback)
. If so, extra from
sendCustomAction will be considered as args and customCommand would have null extra.
Parameters | |
---|---|
session |
MediaSession : the session for this event |
controller |
MediaSession.ControllerInfo : controller information |
customCommand |
SessionCommand : custom command. |
args |
Bundle : optional arguments |
Returns | |
---|---|
SessionResult |
result of handling custom command. A runtime exception will be thrown if
null is returned. |
See also:
onDisconnected
public void onDisconnected (MediaSession session, MediaSession.ControllerInfo controller)
Called when a controller is disconnected.
Interoperability: For legacy controller, this is called when the controller doesn't send any command for a while. It's because there were no explicit disconnect API in legacy controller API.
Parameters | |
---|---|
session |
MediaSession : the session for this event |
controller |
MediaSession.ControllerInfo : controller information
|
onFastForward
public int onFastForward (MediaSession session, MediaSession.ControllerInfo controller)
Called when a controller called MediaController.fastForward()
.
It can be implemented in many ways. For example, it can be implemented by seeking forward once, series of seeking forward, or increasing playback speed.
Parameters | |
---|---|
session |
MediaSession : the session for this event |
controller |
MediaSession.ControllerInfo : controller information |
Returns | |
---|---|
int |
onPostConnect
public void onPostConnect (MediaSession session, MediaSession.ControllerInfo controller)
Called immediately after a controller is connected. This is a convenient method to add custom initialization between the session and a controller.
Note that calls to the controller (e.g. MediaSession.sendCustomCommand(MediaSession.ControllerInfo, SessionCommand, Bundle)
,
MediaSession.setCustomLayout(MediaSession.ControllerInfo, List
) work here but don't work in onConnect(MediaSession, MediaSession.ControllerInfo)
because the
controller hasn't connected yet in onConnect(MediaSession, MediaSession.ControllerInfo)
.
Parameters | |
---|---|
session |
MediaSession : the session for this event |
controller |
MediaSession.ControllerInfo : controller information.
|
onRewind
public int onRewind (MediaSession session, MediaSession.ControllerInfo controller)
Called when a controller called MediaController.rewind()
.
It can be implemented in many ways. For example, it can be implemented by seeking backward once, series of seeking backward, or decreasing playback speed.
Parameters | |
---|---|
session |
MediaSession : the session for this event |
controller |
MediaSession.ControllerInfo : controller information |
Returns | |
---|---|
int |
onSetMediaUri
public int onSetMediaUri (MediaSession session, MediaSession.ControllerInfo controller, Uri uri, Bundle extras)
Called when a controller requested to set the specific media item(s) represented by a URI
through MediaController.setMediaUri(Uri, Bundle)
.
The implementation should create proper media item(s)
for the given
uri
and call SessionPlayer.setMediaItem(MediaItem)
or
SessionPlayer.setPlaylist(List
.
When MediaControllerCompat
is connected and sends commands with following
methods, the uri
would have the following patterns:
Method | Uri pattern |
---|---|
prepareFromUri
| The uri passed as argument |
prepareFromMediaId
| androidx://media2-session/prepareFromMediaId?id=[mediaId] |
prepareFromSearch
| androidx://media2-session/prepareFromSearch?query=[query] |
playFromUri
| The uri passed as argument |
playFromMediaId
| androidx://media2-session/playFromMediaId?id=[mediaId] |
playFromSearch
| androidx://media2-session/playFromSearch?query=[query] |
SessionPlayer.prepare()
or SessionPlayer.play()
would be followed if
this is called by above methods.
Parameters | |
---|---|
session |
MediaSession : the session for this event |
controller |
MediaSession.ControllerInfo : controller information |
uri |
Uri : uri |
extras |
Bundle : optional extra bundle
|
Returns | |
---|---|
int |
onSetRating
public int onSetRating (MediaSession session, MediaSession.ControllerInfo controller, String mediaId, Rating rating)
Called when a controller set rating of a media item through
MediaController.setRating(String, Rating)
.
To allow setting user rating for a MediaItem
, the media item's metadata
should have Rating
with the key MediaMetadata.METADATA_KEY_USER_RATING
,
in order to provide possible rating style for controller. Controller will follow the
rating style.
Parameters | |
---|---|
session |
MediaSession : the session for this event |
controller |
MediaSession.ControllerInfo : controller information |
mediaId |
String : non-empty media id |
rating |
Rating : new rating from the controller |
Returns | |
---|---|
int |
onSkipBackward
public int onSkipBackward (MediaSession session, MediaSession.ControllerInfo controller)
Called when a controller called MediaController.skipBackward()
.
It's recommended to seek backward within the current media item, but its detail may vary. For example, it can be implemented by seeking backward for the fixed amount of seconds, or seeking backward to the nearest bookmark.
Parameters | |
---|---|
session |
MediaSession : the session for this event |
controller |
MediaSession.ControllerInfo : controller information |
Returns | |
---|---|
int |
onSkipForward
public int onSkipForward (MediaSession session, MediaSession.ControllerInfo controller)
Called when a controller called MediaController.skipForward()
.
It's recommended to seek forward within the current media item, but its detail may vary. For example, it can be implemented by seeking forward for the fixed amount of seconds, or seeking forward to the nearest bookmark.
Parameters | |
---|---|
session |
MediaSession : the session for this event |
controller |
MediaSession.ControllerInfo : controller information |
Returns | |
---|---|
int |