MediaRoute2ProviderService

public abstract class MediaRoute2ProviderService
extends Service

java.lang.Object
   ↳ 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

int REASON_INVALID_COMMAND

The request has failed since the request is not valid.

int REASON_NETWORK_ERROR

The request has failed due to a network error.

int REASON_REJECTED

The request has failed since this service rejected the request.

int REASON_ROUTE_NOT_AVAILABLE

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

int REASON_UNKNOWN_ERROR

The request has failed due to unknown reason.

long REQUEST_ID_NONE

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

String SERVICE_INTERFACE

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

Inherited constants

Public constructors

MediaRoute2ProviderService()

Public methods

final List<RoutingSessionInfo> getAllSessionInfo()

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

final RoutingSessionInfo getSessionInfo(String sessionId)

Gets information of the session with the given id.

final void notifyRequestFailed(long requestId, int reason)

Notifies to the client that the request has failed.

final void notifyRoutes(Collection<MediaRoute2Info> routes)

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

final void notifySessionCreated(long requestId, RoutingSessionInfo sessionInfo)

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

final void notifySessionReleased(String sessionId)

Notifies that the session is released.

final void notifySessionUpdated(RoutingSessionInfo sessionInfo)

Notifies the existing session is updated.

IBinder onBind(Intent intent)

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

abstract void onCreateSession(long requestId, String packageName, String routeId, Bundle sessionHints)

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

abstract void onDeselectRoute(long requestId, String sessionId, String routeId)

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

void onDiscoveryPreferenceChanged(RouteDiscoveryPreference preference)

Called when the discovery preference has changed.

abstract void onReleaseSession(long requestId, String sessionId)

Called when the session should be released.

abstract void onSelectRoute(long requestId, String sessionId, String routeId)

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

abstract void onSetRouteVolume(long requestId, String routeId, int volume)

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

abstract void onSetSessionVolume(long requestId, String sessionId, int volume)

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

abstract void onTransferToRoute(long requestId, String sessionId, String routeId)

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

Inherited methods

Constants

REASON_INVALID_COMMAND

Added in API level 30
public static final int REASON_INVALID_COMMAND

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

Constant Value: 4 (0x00000004)

REASON_NETWORK_ERROR

Added in API level 30
public static final int REASON_NETWORK_ERROR

The request has failed due to a network error.

Constant Value: 2 (0x00000002)

REASON_REJECTED

Added in API level 30
public static final int REASON_REJECTED

The request has failed since this service rejected the request.

Constant Value: 1 (0x00000001)

REASON_ROUTE_NOT_AVAILABLE

Added in API level 30
public static final int REASON_ROUTE_NOT_AVAILABLE

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

Constant Value: 3 (0x00000003)

REASON_UNKNOWN_ERROR

Added in API level 30
public static final int REASON_UNKNOWN_ERROR

The request has failed due to unknown reason.

Constant Value: 0 (0x00000000)

REQUEST_ID_NONE

Added in API level 30
public static final long REQUEST_ID_NONE

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

Constant Value: 0 (0x0000000000000000)

SERVICE_INTERFACE

Added in API level 30
public static final String SERVICE_INTERFACE

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

Constant Value: "android.media.MediaRoute2ProviderService"

Public constructors

MediaRoute2ProviderService

Added in API level 30
public MediaRoute2ProviderService ()

Public methods

getAllSessionInfo

Added in API level 30
public final List<RoutingSessionInfo> getAllSessionInfo ()

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

Returns
List<RoutingSessionInfo> This value cannot be null.

getSessionInfo

Added in API level 30
public final RoutingSessionInfo getSessionInfo (String sessionId)

Gets information of the session with the given id.

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

Returns
RoutingSessionInfo information of the session with the given id. null if the session is released or ID is not valid.

notifyRequestFailed

Added in API level 30
public final void notifyRequestFailed (long requestId, 
                int reason)

Notifies to the client that the request has failed.

Parameters
requestId long: the ID of the previous request

reason int: the reason why the request has failed Value is REASON_UNKNOWN_ERROR, REASON_REJECTED, REASON_NETWORK_ERROR, REASON_ROUTE_NOT_AVAILABLE, or REASON_INVALID_COMMAND

notifyRoutes

Added in API level 30
public final void notifyRoutes (Collection<MediaRoute2Info> routes)

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

Parameters
routes Collection: This value cannot be null.

notifySessionCreated

Added in API level 30
public final void notifySessionCreated (long requestId, 
                RoutingSessionInfo sessionInfo)

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
public final void notifySessionReleased (String sessionId)

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
public final void notifySessionUpdated (RoutingSessionInfo sessionInfo)

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
public IBinder onBind (Intent intent)

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 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.

Returns
IBinder This value may be null.

onCreateSession

Added in API level 30
public abstract void onCreateSession (long requestId, 
                String packageName, 
                String routeId, 
                Bundle sessionHints)

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
public abstract void onDeselectRoute (long requestId, 
                String sessionId, 
                String routeId)

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
public void onDiscoveryPreferenceChanged (RouteDiscoveryPreference preference)

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
public abstract void onReleaseSession (long requestId, 
                String sessionId)

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
public abstract void onSelectRoute (long requestId, 
                String sessionId, 
                String routeId)

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
public abstract void onSetRouteVolume (long requestId, 
                String routeId, 
                int volume)

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
public abstract void onSetSessionVolume (long requestId, 
                String sessionId, 
                int volume)

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
public abstract void onTransferToRoute (long requestId, 
                String sessionId, 
                String routeId)

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.