MediaRouter2

cancelScanRequest

public void cancelScanRequest (MediaRouter2.ScanToken token)

Releases the active scan request linked to the provided ScanToken.

getController

public MediaRouter2.RoutingController getController (String id)

Gets a RoutingController whose ID is equal to the given ID. Returns null if there is no matching controller.

getControllers

public List<MediaRouter2.RoutingController> getControllers ()

Gets the list of currently active routing controllers on which media can be played.

Note: The list returned here will never be empty. The first element in the list is always the system controller.

getInstance

public static MediaRouter2 getInstance (Context context)

Gets an instance of the media router associated with the context.

getInstance

public static MediaRouter2 getInstance (Context context, 
                String clientPackageName, 
                Executor executor, 
                Runnable onInstanceInvalidatedListener)

Returns a proxy MediaRouter2 instance that allows you to control the routing of an app specified by clientPackageName. Returns null if the specified package name does not exist.

Proxy MediaRouter2 instances operate differently than regular MediaRouter2 instances:

• registerRouteCallback(Executor, RouteCallback, RouteDiscoveryPreference) ignores any preference passed by a proxy router. Use ERROR(RouteDiscoveryPreference#EMPTY/android.media.RouteDiscoveryPreference#EMPTY RouteDiscoveryPreference#EMPTY) when setting a route callback.

• Methods returning non-system controllers always return new instances with the latest data. Do not attempt to compare or store them. Instead, use getController(java.lang.String) or getControllers() to query the most up-to-date state.

• Calls to setOnGetControllerHintsListener(OnGetControllerHintsListener) are ignored.

Use this method when you only hold a revocable version of Manifest.permission.MEDIA_ROUTING_CONTROL (e.g. acquired via the AppOpsManager). Otherwise, use ERROR(/#getInstance(android.content.Context,java.lang.String)).

onInstanceInvalidatedListener is called when the instance is invalidated because the calling app has lost Manifest.permission#MEDIA_ROUTING_CONTROL and does not hold Manifest.permission#MEDIA_CONTENT_CONTROL. Do not use the invalidated instance after receiving this callback, as the system will ignore all operations. Call getInstance(android.content.Context, java.lang.String, java.util.concurrent.Executor, java.lang.Runnable) again after reacquiring the relevant permissions.
Requires Manifest.permission.MEDIA_CONTENT_CONTROL or Manifest.permission.MEDIA_ROUTING_CONTROL

getRouteListingPreference

public RouteListingPreference getRouteListingPreference ()

Returns the current RouteListingPreference of the target router.

If this instance was created using #getInstance(Context, String), then it returns the last RouteListingPreference set by the process this router was created for.

getRoutes

public List<MediaRoute2Info> getRoutes ()

Gets the unmodifiable list of routes currently known to the media router.

Please note that the list can be changed before callbacks are invoked.

getSystemController

public MediaRouter2.RoutingController getSystemController ()

Gets a RoutingController which can control the routes provided by system. e.g. Phone speaker, wired headset, Bluetooth, etc.

Note: The system controller can't be released. Calling RoutingController#release() will be ignored.

This method always returns the same instance.

registerControllerCallback

public void registerControllerCallback (Executor executor, 
                MediaRouter2.ControllerCallback callback)

Registers a ControllerCallback. If you register the same callback twice or more, it will be ignored.

registerRouteCallback

public void registerRouteCallback (Executor executor, 
                MediaRouter2.RouteCallback routeCallback, 
                RouteDiscoveryPreference preference)

Registers a callback to discover routes and to receive events when they change.

Clients can register multiple callbacks, as long as the RouteCallback instances are different. Each callback can provide a unique preference and will only receive updates related to that set preference.

If the specified callback is already registered, its registration will be updated for the given executor and discovery preference.

Local routers must register a route callback to register in the system and start receiving updates. Otherwise, all operations will be no-ops.

Any discovery preference passed by a ERROR(proxy router/#getInstance(android.content.Context,java.lang.String) proxy router) will be ignored and will receive route updates based on the preference set by its matching local router.

registerRouteListingPreferenceUpdatedCallback

public void registerRouteListingPreferenceUpdatedCallback (Executor executor, 
                Consumer<RouteListingPreference> routeListingPreferenceCallback)

Registers the given callback to be invoked when the RouteListingPreference of the target router changes.

Calls using a previously registered callback will overwrite the previous executor.

registerTransferCallback

public void registerTransferCallback (Executor executor, 
                MediaRouter2.TransferCallback callback)

Registers a callback to get the result of transferTo(android.media.MediaRoute2Info). If you register the same callback twice or more, it will be ignored.

requestScan

public MediaRouter2.ScanToken requestScan (MediaRouter2.ScanRequest scanRequest)

Requests the system to actively scan for routes based on the router's route discovery preference.

You must call cancelScanRequest(android.media.MediaRouter2.ScanToken) promptly to preserve system resources like battery. Avoid scanning unless there is clear intention from the user to start routing their media.

scanRequest specifies relevant scanning options, like whether the system should scan with the screen off. Screen off scanning requires Manifest.permission.MEDIA_ROUTING_CONTROL or Manifest.permission.MEDIA_CONTENT_CONTROL.

Proxy routers use the registered RouteDiscoveryPreference of their target routers.

setOnGetControllerHintsListener

public void setOnGetControllerHintsListener (MediaRouter2.OnGetControllerHintsListener listener)

Sets an OnGetControllerHintsListener to send hints when creating a RoutingController. To send the hints, listener should be set BEFORE calling transferTo(android.media.MediaRoute2Info).

setRouteListingPreference

public void setRouteListingPreference (RouteListingPreference routeListingPreference)

Sets the RouteListingPreference of the app associated to this media router.

Use this method to inform the system UI of the routes that you would like to list for media routing, via the Output Switcher.

You should call this method before registering any route callbacks and immediately after receiving any updates in order to keep the system UI in a consistent state. You can also call this method at any other point to update the listing preference dynamically.

Any calls to this method from a privileged router will throw an UnsupportedOperationException.

Notes:

1. You should not include the ids of two or more routes with a match in their deduplication ids. If you do, the system will deduplicate them using its own criteria.
2. You can use this method to rank routes in the output switcher, placing the more important routes first. The system might override the proposed ranking.
3. You can use this method to avoid listing routes using dynamic criteria. For example, you can limit access to a specific type of device according to runtime criteria.

setRouteVolume

public void setRouteVolume (MediaRoute2Info route, 
                int volume)

Sets the volume for a specific route.

The call may have no effect if the route is currently not selected.

This method is only supported by ERROR(proxy MediaRouter2 instances/#getInstance(android.content.Context,java.lang.String) proxy MediaRouter2 instances). Use RoutingController#setVolume(int) instead for local MediaRouter2 instances.

showSystemOutputSwitcher

public boolean showSystemOutputSwitcher ()

Shows the system output switcher dialog.

Should only be called when the context of MediaRouter2 is in the foreground and visible on the screen.

The appearance and precise behaviour of the system output switcher dialog may vary across different devices, OS versions, and form factors, but the basic functionality stays the same.

See Output Switcher documentation for more details.

stop

public void stop ()

Stops the current media routing. If the system controller controls the media routing, this method is a no-op.

transferTo

public void transferTo (MediaRoute2Info route)

Transfers the current media to the given route. If it's necessary a new RoutingController is created or it is handled within the current routing controller.

unregisterControllerCallback

public void unregisterControllerCallback (MediaRouter2.ControllerCallback callback)

Unregisters a ControllerCallback. The callback will no longer receive events. If the callback has not been added or been removed already, it is ignored.

unregisterRouteCallback

public void unregisterRouteCallback (MediaRouter2.RouteCallback routeCallback)

Unregisters the given callback. The callback will no longer receive events. If the callback has not been added or been removed already, it is ignored.

unregisterRouteListingPreferenceUpdatedCallback

public void unregisterRouteListingPreferenceUpdatedCallback (Consumer<RouteListingPreference> callback)

Unregisters the given callback to not receive RouteListingPreference change events.

unregisterTransferCallback

public void unregisterTransferCallback (MediaRouter2.TransferCallback callback)

Unregisters the given callback. The callback will no longer receive events. If the callback has not been added or been removed already, it is ignored.