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.
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 |
String | SERVICE_INTERFACE The |
Inherited constants |
|---|
Public constructors | |
|---|---|
MediaRoute2ProviderService() | |
Public methods | |
|---|---|
final List<RoutingSessionInfo> | getAllSessionInfo() Gets the list of |
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 |
void | onDiscoveryPreferenceChanged(RouteDiscoveryPreference compositePreference, Map<String, RouteDiscoveryPreference> perAppPreferences) Called when any individual app's |
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 |
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
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.
See also:
Constant Value: 4 (0x00000004)
REASON_NETWORK_ERROR
public static final int REASON_NETWORK_ERROR
The request has failed due to a network error.
See also:
Constant Value: 2 (0x00000002)
REASON_REJECTED
public static final int REASON_REJECTED
The request has failed since this service rejected the request.
See also:
Constant Value: 1 (0x00000001)
REASON_ROUTE_NOT_AVAILABLE
public static final int REASON_ROUTE_NOT_AVAILABLE
The request has failed since the requested route is no longer available.
See also:
Constant Value: 3 (0x00000003)
REASON_UNKNOWN_ERROR
public static final int REASON_UNKNOWN_ERROR
The request has failed due to unknown reason.
See also:
Constant Value: 0 (0x00000000)
REQUEST_ID_NONE
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
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
Public methods
getAllSessionInfo
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
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
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, REASON_INVALID_COMMAND, android.media.MediaRoute2ProviderService.REASON_UNIMPLEMENTED, or android.media.MediaRoute2ProviderService.REASON_FAILED_TO_REROUTE_SYSTEM_MEDIA |
notifyRoutes
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. |
| Throws | |
|---|---|
IllegalArgumentException | If routes contains a route that ERROR(supports/android.media.MediaRoute2Info#getSupportedRoutingTypes() supports) both system media routing and remote routing but doesn't contain any deduplication ids. |
notifySessionCreated
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
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. |
See also:
notifySessionUpdated
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
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
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
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
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. |
onDiscoveryPreferenceChanged
public void onDiscoveryPreferenceChanged (RouteDiscoveryPreference compositePreference, Map<String, RouteDiscoveryPreference> perAppPreferences)
Called when any individual app's discovery preference has changed, which typically means the composite preference has also changed.
This is similar to onDiscoveryPreferenceChanged(android.media.RouteDiscoveryPreference) but provides more granular per-app preference information if the provider has permission to see it.
| Parameters | |
|---|---|
compositePreference | RouteDiscoveryPreference: A composite object aggregating the route preferences for all apps with registered callbacks. This value cannot be null. |
perAppPreferences | Map: A mapping of app package name to the discovery preference just for that app. This map will only be populated if the caller holds the MEDIA_CONTENT_CONTROL permission. This value cannot be null. |
onReleaseSession
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
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
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 |
See also:
onSetSessionVolume
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
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. |