MediaRouteProvider

abstract class MediaRouteProvider

Media route providers are used to publish additional media routes for use within an application. Media route providers may also be declared as a service to publish additional media routes to all applications in the system.

The purpose of a media route provider is to discover media routes that satisfy the criteria specified by the current MediaRouteDiscoveryRequest and publish a MediaRouteProviderDescriptor with information about each route by calling setDescriptor to notify the currently registered Callback.

The provider should watch for changes to the discovery request by implementing onDiscoveryRequestChanged and updating the set of routes that it is attempting to discover. It should also handle route control requests such as volume changes or media control intents by implementing onCreateRouteController to return a RouteController for a particular route.

A media route provider can support dynamic group that allows the user to add or remove a route from the selected route dynamically. To control dynamic group, DynamicGroupRouteController returned by onCreateDynamicGroupRouteController is used instead of RouteController.

A media route provider may be used privately within the scope of a single application process by calling MediaRouter.addProvider to add it to the local MediaRouter. A media route provider may also be made available globally to all applications by registering a MediaRouteProviderService in the provider's manifest. When the media route provider is registered as a service, all applications that use the media router API will be able to discover and used the provider's routes without having to install anything else.

This object must only be accessed on the main thread.

Summary

Nested types

Callback which is invoked when route information becomes available or changes.

Provides control over a dynamic group route.

Contains a route, its selection state and its capabilities.

Builder for DynamicRouteDescriptor

Describes properties of the route provider's implementation.

Provides control over a particular route.

Holds parameters for creating RouteController.

Builder for RouteControllerOptions.

Public constructors

Creates a media route provider.

Public functions
Context

Gets the context of the media route provider.
MediaRouteProviderDescriptor?

Gets the provider's descriptor.
MediaRouteDiscoveryRequest?

Gets the current discovery request which informs the provider about the kinds of routes to discover and whether to perform active scanning.
Handler

Gets the provider's handler which is associated with the main thread.
MediaRouteProvider.ProviderMetadata

Gets some metadata about the provider's implementation.
MediaRouteProvider.DynamicGroupRouteController?

Creates a DynamicGroupRouteController.
MediaRouteProvider.DynamicGroupRouteController?
onCreateDynamicGroupRouteController(
    initialMemberRouteId: String,
    routeControllerOptions: MediaRouteProvider.RouteControllerOptions
)

Creates a DynamicGroupRouteController.
MediaRouteProvider.RouteController?

Called by the media router to obtain a route controller for a particular route.
MediaRouteProvider.RouteController?
onCreateRouteController(
    routeId: String,
    routeControllerOptions: MediaRouteProvider.RouteControllerOptions
)

Creates a RouteController.
Unit

Called by the media router when the discovery request has changed.
Unit

Sets a callback to invoke when the provider's descriptor changes.
Unit

Sets the provider's descriptor.
Unit

Sets a discovery request to inform the provider about the kinds of routes that its clients would like to discover and whether to perform active scanning.

Public constructors

MediaRouteProvider

Added in 1.1.0
MediaRouteProvider(context: Context)

Creates a media route provider.

Parameters
context: Context

The context.

Public functions

getContext

Added in 1.1.0
fun getContext(): Context

Gets the context of the media route provider.

getDescriptor

Added in 1.1.0
fun getDescriptor(): MediaRouteProviderDescriptor?

Gets the provider's descriptor.

The descriptor describes the state of the media route provider and the routes that it publishes. Watch for changes to the descriptor by registering a callback with setCallback.

Returns
MediaRouteProviderDescriptor?

The media route provider descriptor, or null if none.
See also
onDescriptorChanged

getDiscoveryRequest

Added in 1.1.0
fun getDiscoveryRequest(): MediaRouteDiscoveryRequest?

Gets the current discovery request which informs the provider about the kinds of routes to discover and whether to perform active scanning.

Returns
MediaRouteDiscoveryRequest?

The current discovery request, or null if no discovery is needed at this time.
See also
onDiscoveryRequestChanged

getHandler

Added in 1.1.0
fun getHandler(): Handler

Gets the provider's handler which is associated with the main thread.

getMetadata

Added in 1.1.0
fun getMetadata(): MediaRouteProvider.ProviderMetadata

Gets some metadata about the provider's implementation.

onCreateDynamicGroupRouteController

Added in 1.1.0
fun onCreateDynamicGroupRouteController(initialMemberRouteId: String): MediaRouteProvider.DynamicGroupRouteController?

Creates a DynamicGroupRouteController.

It is equivalent to onCreateDynamicGroupRouteController, except it doesn't take RouteControllerOptions.

This method is only called when the subclass doesn't implement onCreateDynamicGroupRouteController.

Parameters
initialMemberRouteId: String

initially selected route's id.
Returns
MediaRouteProvider.DynamicGroupRouteController?

DynamicGroupRouteController. Returns null if there is no such route or if the route cannot be controlled using the DynamicGroupRouteController interface.

onCreateDynamicGroupRouteController

Added in 1.8.0
fun onCreateDynamicGroupRouteController(
    initialMemberRouteId: String,
    routeControllerOptions: MediaRouteProvider.RouteControllerOptions
): MediaRouteProvider.DynamicGroupRouteController?

Creates a DynamicGroupRouteController.

It will be called from an app or MediaRouter when a single route or a single static group is selected.

Parameters
initialMemberRouteId: String

initially selected route's id.
routeControllerOptions: MediaRouteProvider.RouteControllerOptions

the parameters to be used to create the route controller.
Returns
MediaRouteProvider.DynamicGroupRouteController?

DynamicGroupRouteController. Returns null if there is no such route or if the route cannot be controlled using the DynamicGroupRouteController interface.

onCreateRouteController

Added in 1.1.0
fun onCreateRouteController(routeId: String): MediaRouteProvider.RouteController?

Called by the media router to obtain a route controller for a particular route.

The media router will invoke the onRelease method of the route controller when it is no longer needed to allow it to free its resources.

Parameters
routeId: String

The unique id of the route.
Returns
MediaRouteProvider.RouteController?

The route controller. Returns null if there is no such route or if the route cannot be controlled using the route controller interface.

onCreateRouteController

Added in 1.8.0
fun onCreateRouteController(
    routeId: String,
    routeControllerOptions: MediaRouteProvider.RouteControllerOptions
): MediaRouteProvider.RouteController?

Creates a RouteController.

It will be called from an app or MediaRouter when a single route is selected.

Parameters
routeId: String

the selected route's ID.
routeControllerOptions: MediaRouteProvider.RouteControllerOptions

the parameters to be used to create the route controller.
Returns
MediaRouteProvider.RouteController?

RouteController. Returns null if there is no such route.

onDiscoveryRequestChanged

Added in 1.1.0
fun onDiscoveryRequestChanged(request: MediaRouteDiscoveryRequest?): Unit

Called by the media router when the discovery request has changed.

Whenever an applications calls addCallback to register a callback, it also provides a selector to specify the kinds of routes that it is interested in. The media router combines all of these selectors together to generate a MediaRouteDiscoveryRequest and notifies each provider when a change occurs by calling setDiscoveryRequest which posts a message to invoke this method asynchronously.

The provider should examine the media control categories in the discovery request's selector to determine what kinds 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 determining that the selector does not contain any categories that it supports and it can therefore avoid performing any scans at all.

Parameters
request: MediaRouteDiscoveryRequest?

The new discovery request, or null if no discovery is needed at this time.
See also
MediaRouter

setCallback

Added in 1.1.0
fun setCallback(callback: MediaRouteProvider.Callback?): Unit

Sets a callback to invoke when the provider's descriptor changes.

Parameters
callback: MediaRouteProvider.Callback?

The callback to use, or null if none.

setDescriptor

Added in 1.1.0
fun setDescriptor(descriptor: MediaRouteProviderDescriptor?): Unit

Sets the provider's descriptor.

The provider must call this method to notify the currently registered callback about the change to the provider's descriptor.

Parameters
descriptor: MediaRouteProviderDescriptor?

The updated route provider descriptor, or null if none.
See also
onDescriptorChanged

setDiscoveryRequest

Added in 1.1.0
fun setDiscoveryRequest(request: MediaRouteDiscoveryRequest?): Unit

Sets a discovery request to inform the provider about the kinds of routes that its clients would like to discover and whether to perform active scanning.

Parameters
request: MediaRouteDiscoveryRequest?

The discovery request, or null if no discovery is needed at this time.
See also
onDiscoveryRequestChanged