Added in API level 30

MediaRoute2ProviderService


abstract class MediaRoute2ProviderService : Service
kotlin.Any
   ↳ android.content.Context
   ↳ android.content.ContextWrapper
   ↳ android.app.Service
   ↳ android.media.MediaRoute2ProviderService

Base class for media route provider services.

Media route provider services are used to publish media routes such as speakers, TVs, etc. The routes are published by calling notifyRoutes(java.util.Collection). Media apps which use MediaRouter2 can request to play their media on the routes.

When media router wants to play media on a route, onCreateSession(long,java.lang.String,java.lang.String,android.os.Bundle) will be called to handle the request. A session can be considered as a group of currently selected routes for each connection. Create and manage the sessions by yourself, and notify the session infos when there are any changes.

The system media router service will bind to media route provider services when a discovery preference is registered via a media router by an application. See onDiscoveryPreferenceChanged(android.media.RouteDiscoveryPreference) for the details.

Use notifyRequestFailed(long,int) to notify the failure with previously received request ID.

Summary

Constants
static Int

The request has failed since the request is not valid.

static Int

The request has failed due to a network error.

static Int

The request has failed since this service rejected the request.

static Int

The request has failed since the requested route is no longer available.

static Int

The request has failed due to unknown reason.

static Long

The request ID to pass notifySessionCreated(long,android.media.RoutingSessionInfo) when MediaRoute2ProviderService created a session although there was no creation request.

static String

The Intent action that must be declared as handled by the service.

Inherited constants
Public constructors

Public methods
MutableList<RoutingSessionInfo!>

Gets the list of session info that the provider service maintains.

RoutingSessionInfo?
getSessionInfo(sessionId: String)

Gets information of the session with the given id.

Unit
notifyRequestFailed(requestId: Long, reason: Int)

Notifies to the client that the request has failed.

Unit

Updates routes of the provider and notifies the system media router service.

Unit
notifySessionCreated(requestId: Long, sessionInfo: RoutingSessionInfo)

Notifies clients of that the session is created and ready for use.

Unit

Notifies that the session is released.

Unit

Notifies the existing session is updated.

open IBinder?
onBind(intent: Intent)

If overriding this method, call through to the super method for any unknown actions.

abstract Unit
onCreateSession(requestId: Long, packageName: String, routeId: String, sessionHints: Bundle?)

Called when the service receives a request to create a session.

abstract Unit
onDeselectRoute(requestId: Long, sessionId: String, routeId: String)

Called when a client requests deselecting a route from the session.

open Unit

Called when the discovery preference has changed.

abstract Unit
onReleaseSession(requestId: Long, sessionId: String)

Called when the session should be released.

abstract Unit
onSelectRoute(requestId: Long, sessionId: String, routeId: String)

Called when a client requests selecting a route for the session.

abstract Unit
onSetRouteVolume(requestId: Long, routeId: String, volume: Int)

Called when a volume setting is requested on a route of the provider

abstract Unit
onSetSessionVolume(requestId: Long, sessionId: String, volume: Int)

Called when MediaRouter2.RoutingController#setVolume(int) is called on a routing session of the provider

abstract Unit
onTransferToRoute(requestId: Long, sessionId: String, routeId: String)

Called when a client requests transferring a session to a route.

Inherited functions

Constants

REASON_INVALID_COMMAND

Added in API level 30
static val REASON_INVALID_COMMAND: Int

The request has failed since the request is not valid. For example, selecting a route which is not selectable.

Value: 4

REASON_NETWORK_ERROR

Added in API level 30
static val REASON_NETWORK_ERROR: Int

The request has failed due to a network error.

Value: 2

REASON_REJECTED

Added in API level 30
static val REASON_REJECTED: Int

The request has failed since this service rejected the request.

Value: 1

REASON_ROUTE_NOT_AVAILABLE

Added in API level 30
static val REASON_ROUTE_NOT_AVAILABLE: Int

The request has failed since the requested route is no longer available.

Value: 3

REASON_UNKNOWN_ERROR

Added in API level 30
static val REASON_UNKNOWN_ERROR: Int

The request has failed due to unknown reason.

Value: 0

REQUEST_ID_NONE

Added in API level 30
static val REQUEST_ID_NONE: Long

The request ID to pass notifySessionCreated(long,android.media.RoutingSessionInfo) when MediaRoute2ProviderService created a session although there was no creation request.

Value: 0L

SERVICE_INTERFACE

Added in API level 30
static val SERVICE_INTERFACE: String

The Intent action that must be declared as handled by the service. Put this in your manifest to provide media routes.

Value: "android.media.MediaRoute2ProviderService"

Public constructors

MediaRoute2ProviderService

Added in API level 30
MediaRoute2ProviderService()

Public methods

getAllSessionInfo

Added in API level 30
fun getAllSessionInfo(): MutableList<RoutingSessionInfo!>

Gets the list of session info that the provider service maintains.

Return
MutableList<RoutingSessionInfo!> This value cannot be null.

getSessionInfo

Added in API level 30
fun getSessionInfo(sessionId: String): RoutingSessionInfo?

Gets information of the session with the given id.

Parameters
sessionId String: the ID of the session This value cannot be null.
Return
RoutingSessionInfo? information of the session with the given id. null if the session is released or ID is not valid.

notifyRoutes

Added in API level 30
fun notifyRoutes(routes: MutableCollection<MediaRoute2Info!>): Unit

Updates routes of the provider and notifies the system media router service.

Parameters
routes MutableCollection<MediaRoute2Info!>: This value cannot be null.

notifySessionCreated

Added in API level 30
fun notifySessionCreated(
    requestId: Long,
    sessionInfo: RoutingSessionInfo
): Unit

Notifies clients of that the session is created and ready for use.

If this session is created without any creation request, use REQUEST_ID_NONE as the request ID.

Parameters
requestId Long: the ID of the previous request to create this session provided in onCreateSession(long,java.lang.String,java.lang.String,android.os.Bundle). Can be REQUEST_ID_NONE if this session is created without any request.
sessionInfo RoutingSessionInfo: information of the new session. The id of the session must be unique. This value cannot be null.

notifySessionReleased

Added in API level 30
fun notifySessionReleased(sessionId: String): Unit

Notifies that the session is released.

Parameters
sessionId String: the ID of the released session. This value cannot be null.

notifySessionUpdated

Added in API level 30
fun notifySessionUpdated(sessionInfo: RoutingSessionInfo): Unit

Notifies the existing session is updated. For example, when selected routes are changed.

Parameters
sessionInfo RoutingSessionInfo: This value cannot be null.

onBind

Added in API level 30
open fun onBind(intent: Intent): IBinder?

If overriding this method, call through to the super method for any unknown actions.

Return the communication channel to the service. May return null if clients can not bind to the service. The returned android.os.IBinder is usually for a complex interface that has been described using aidl.

Note that unlike other application components, calls on to the IBinder interface returned here may not happen on the main thread of the process. More information about the main thread can be found in Processes and Threads.


If you override this method you must call through to the superclass implementation.
Parameters
intent Intent: This value cannot be null.
Return
IBinder? This value may be null.

onCreateSession

Added in API level 30
abstract fun onCreateSession(
    requestId: Long,
    packageName: String,
    routeId: String,
    sessionHints: Bundle?
): Unit

Called when the service receives a request to create a session.

You should create and maintain your own session and notifies the client of session info. Call notifySessionCreated(long,android.media.RoutingSessionInfo) with the given requestId to notify the information of a new session. The created session must have the same route feature and must include the given route specified by routeId.

If the session can be controlled, you can optionally pass the control hints to RoutingSessionInfo.Builder#setControlHints(Bundle). Control hints is a Bundle which contains how to control the session.

If you can't create the session or want to reject the request, call notifyRequestFailed(long,int) with the given requestId.

Parameters
requestId Long: the ID of this request
packageName String: the package name of the application that selected the route This value cannot be null.
routeId String: the ID of the route initially being connected This value cannot be null.
sessionHints Bundle?: an optional bundle of app-specific arguments sent by MediaRouter2, or null if none. The contents of this bundle may affect the result of session creation.

onDeselectRoute

Added in API level 30
abstract fun onDeselectRoute(
    requestId: Long,
    sessionId: String,
    routeId: String
): Unit

Called when a client requests deselecting a route from the session. After the route is deselected, call notifySessionUpdated(android.media.RoutingSessionInfo) to update session info.

Parameters
requestId Long: the ID of this request
sessionId String: the ID of the session This value cannot be null.
routeId String: the ID of the route This value cannot be null.

onDiscoveryPreferenceChanged

Added in API level 30
open fun onDiscoveryPreferenceChanged(preference: RouteDiscoveryPreference): Unit

Called when the discovery preference has changed.

Whenever an application registers a callback, it also provides a discovery preference to specify features of routes that it is interested in. The media router combines all of these discovery request into a single discovery preference and notifies each provider.

The provider should examine preferred features in the discovery preference to determine what kind of routes it should try to discover and whether it should perform active or passive scans. In many cases, the provider may be able to save power by not performing any scans when the request doesn't have any matching route features.

Parameters
preference RouteDiscoveryPreference: the new discovery preference This value cannot be null.

onReleaseSession

Added in API level 30
abstract fun onReleaseSession(
    requestId: Long,
    sessionId: String
): Unit

Called when the session should be released. A client of the session or system can request a session to be released.

After releasing the session, call notifySessionReleased(java.lang.String) with the ID of the released session. Note: Calling notifySessionReleased(java.lang.String) will NOT trigger this method to be called.

Parameters
requestId Long: the ID of this request
sessionId String: the ID of the session being released. This value cannot be null.

onSelectRoute

Added in API level 30
abstract fun onSelectRoute(
    requestId: Long,
    sessionId: String,
    routeId: String
): Unit

Called when a client requests selecting a route for the session. After the route is selected, call notifySessionUpdated(android.media.RoutingSessionInfo) to update session info.

Parameters
requestId Long: the ID of this request
sessionId String: the ID of the session This value cannot be null.
routeId String: the ID of the route This value cannot be null.

onSetRouteVolume

Added in API level 30
abstract fun onSetRouteVolume(
    requestId: Long,
    routeId: String,
    volume: Int
): Unit

Called when a volume setting is requested on a route of the provider

Parameters
requestId Long: the ID of this request
routeId String: the ID of the route This value cannot be null.
volume Int: the target volume

onSetSessionVolume

Added in API level 30
abstract fun onSetSessionVolume(
    requestId: Long,
    sessionId: String,
    volume: Int
): Unit

Called when MediaRouter2.RoutingController#setVolume(int) is called on a routing session of the provider

Parameters
requestId Long: the ID of this request
sessionId String: the ID of the routing session This value cannot be null.
volume Int: the target volume

onTransferToRoute

Added in API level 30
abstract fun onTransferToRoute(
    requestId: Long,
    sessionId: String,
    routeId: String
): Unit

Called when a client requests transferring a session to a route. After the transfer is finished, call notifySessionUpdated(android.media.RoutingSessionInfo) to update session info.

Parameters
requestId Long: the ID of this request
sessionId String: the ID of the session This value cannot be null.
routeId String: the ID of the route This value cannot be null.