/*
* Copyright (C) 2013 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package androidx.mediarouter.media;
import static androidx.annotation.RestrictTo.Scope.LIBRARY;
import static androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP;
import android.app.ActivityManager;
import android.content.ComponentName;
import android.content.ContentResolver;
import android.content.Context;
import android.content.Intent;
import android.content.IntentFilter;
import android.content.IntentSender;
import android.content.res.Resources;
import android.net.Uri;
import android.os.Bundle;
import android.os.Looper;
import android.os.SystemClock;
import android.support.v4.media.session.MediaSessionCompat;
import android.text.TextUtils;
import android.util.Log;
import android.view.Display;
import androidx.annotation.IntDef;
import androidx.annotation.MainThread;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.annotation.RestrictTo;
import androidx.collection.ArrayMap;
import androidx.core.util.ObjectsCompat;
import androidx.core.util.Pair;
import androidx.mediarouter.app.MediaRouteDiscoveryFragment;
import androidx.mediarouter.media.MediaRouteProvider.DynamicGroupRouteController;
import androidx.mediarouter.media.MediaRouteProvider.DynamicGroupRouteController.DynamicRouteDescriptor;
import androidx.mediarouter.media.MediaRouteProvider.ProviderMetadata;
import androidx.mediarouter.media.MediaRouteProvider.RouteController;
import com.google.common.util.concurrent.ListenableFuture;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.ref.WeakReference;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.List;
import java.util.ListIterator;
import java.util.Map;
/**
* MediaRouter allows applications to control the routing of media channels
* and streams from the current device to external speakers and destination devices.
* <p>
* A MediaRouter instance is retrieved through {@link #getInstance}. Applications
* can query the media router about the currently selected route and its capabilities
* to determine how to send content to the route's destination. Applications can
* also {@link RouteInfo#sendControlRequest send control requests} to the route
* to ask the route's destination to perform certain remote control functions
* such as playing media.
* </p><p>
* See also {@link MediaRouteProvider} for information on how an application
* can publish new media routes to the media router.
* </p><p>
* The media router API is not thread-safe; all interactions with it must be
* done from the main thread of the process.
* </p>
*/
// TODO: Add the javadoc for manifest requirements about 'Package visibility' in Android 11
public final class MediaRouter {
// The "Ax" prefix disambiguates from the platform's MediaRouter.
static final String TAG = "AxMediaRouter";
static final boolean DEBUG = Log.isLoggable(TAG, Log.DEBUG);
@IntDef({
UNSELECT_REASON_UNKNOWN,
UNSELECT_REASON_DISCONNECTED,
UNSELECT_REASON_STOPPED,
UNSELECT_REASON_ROUTE_CHANGED
})
@Retention(RetentionPolicy.SOURCE)
@interface UnselectReason {}
/**
* Passed to {@link MediaRouteProvider.RouteController#onUnselect(int)},
* {@link Callback#onRouteUnselected(MediaRouter, RouteInfo, int)} and
* {@link Callback#onRouteSelected(MediaRouter, RouteInfo, int)} when the reason the route
* was unselected is unknown.
*/
public static final int UNSELECT_REASON_UNKNOWN = 0;
/**
* Passed to {@link MediaRouteProvider.RouteController#onUnselect(int)},
* {@link Callback#onRouteUnselected(MediaRouter, RouteInfo, int)} and
* {@link Callback#onRouteSelected(MediaRouter, RouteInfo, int)} when the user pressed
* the disconnect button to disconnect and keep playing.
* <p>
*
* @see MediaRouteDescriptor#canDisconnectAndKeepPlaying()
*/
public static final int UNSELECT_REASON_DISCONNECTED = 1;
/**
* Passed to {@link MediaRouteProvider.RouteController#onUnselect(int)},
* {@link Callback#onRouteUnselected(MediaRouter, RouteInfo, int)} and
* {@link Callback#onRouteSelected(MediaRouter, RouteInfo, int)} when the user pressed
* the stop casting button.
* <p>
* Media should stop when this reason is passed.
*/
public static final int UNSELECT_REASON_STOPPED = 2;
/**
* Passed to {@link MediaRouteProvider.RouteController#onUnselect(int)},
* {@link Callback#onRouteUnselected(MediaRouter, RouteInfo, int)} and
* {@link Callback#onRouteSelected(MediaRouter, RouteInfo, int)} when the user selected
* a different route.
*/
public static final int UNSELECT_REASON_ROUTE_CHANGED = 3;
/** Maintains global media router state for the process. */
static GlobalMediaRouter sGlobal;
// Context-bound state of the media router.
final Context mContext;
final ArrayList<CallbackRecord> mCallbackRecords = new ArrayList<>();
@IntDef(
flag = true,
value = {
CALLBACK_FLAG_PERFORM_ACTIVE_SCAN,
CALLBACK_FLAG_REQUEST_DISCOVERY,
CALLBACK_FLAG_UNFILTERED_EVENTS,
CALLBACK_FLAG_FORCE_DISCOVERY
})
@Retention(RetentionPolicy.SOURCE)
private @interface CallbackFlags {}
/**
* Flag for {@link #addCallback}: Actively scan for routes while this callback
* is registered.
* <p>
* When this flag is specified, the media router will actively scan for new
* routes. Certain routes, such as wifi display routes, may not be discoverable
* except when actively scanning. This flag is typically used when the route picker
* dialog has been opened by the user to ensure that the route information is
* up to date.
* </p><p>
* Active scanning may consume a significant amount of power and may have intrusive
* effects on wireless connectivity. Therefore it is important that active scanning
* only be requested when it is actually needed to satisfy a user request to
* discover and select a new route.
* </p><p>
* This flag implies {@link #CALLBACK_FLAG_REQUEST_DISCOVERY} but performing
* active scans is much more expensive than a normal discovery request.
* </p>
*
* @see #CALLBACK_FLAG_REQUEST_DISCOVERY
*/
public static final int CALLBACK_FLAG_PERFORM_ACTIVE_SCAN = 1 << 0;
/**
* Flag for {@link #addCallback}: Do not filter route events.
* <p>
* When this flag is specified, the callback will be invoked for events that affect any
* route even if they do not match the callback's filter.
* </p>
*/
public static final int CALLBACK_FLAG_UNFILTERED_EVENTS = 1 << 1;
/**
* Flag for {@link #addCallback}: Request passive route discovery while this
* callback is registered, except on {@link ActivityManager#isLowRamDevice low-RAM devices}.
* <p>
* When this flag is specified, the media router will try to discover routes.
* Although route discovery is intended to be efficient, checking for new routes may
* result in some network activity and could slowly drain the battery. Therefore
* applications should only specify this flag when
* they are running in the foreground and would like to provide the user with the
* option of connecting to new routes.
* </p><p>
* Applications should typically add a callback using this flag in the
* {@link android.app.Activity activity's} {@link android.app.Activity#onStart onStart}
* method and remove it in the {@link android.app.Activity#onStop onStop} method.
* The {@link MediaRouteDiscoveryFragment} fragment may
* also be used for this purpose.
* </p><p class="note">
* On {@link ActivityManager#isLowRamDevice low-RAM devices} this flag
* will be ignored. Refer to
* {@link #addCallback(MediaRouteSelector, Callback, int) addCallback} for details.
* </p>
*
* @see MediaRouteDiscoveryFragment
*/
public static final int CALLBACK_FLAG_REQUEST_DISCOVERY = 1 << 2;
/**
* Flag for {@link #addCallback}: Request passive route discovery while this
* callback is registered, even on {@link ActivityManager#isLowRamDevice low-RAM devices}.
* <p class="note">
* This flag has a significant performance impact on low-RAM devices
* since it may cause many media route providers to be started simultaneously.
* It is much better to use {@link #CALLBACK_FLAG_REQUEST_DISCOVERY} instead to avoid
* performing passive discovery on these devices altogether. Refer to
* {@link #addCallback(MediaRouteSelector, Callback, int) addCallback} for details.
* </p>
*
* @see MediaRouteDiscoveryFragment
*/
public static final int CALLBACK_FLAG_FORCE_DISCOVERY = 1 << 3;
/**
* Flag for {@link #isRouteAvailable}: Ignore the default route.
* <p>
* This flag is used to determine whether a matching non-default route is available.
* This constraint may be used to decide whether to offer the route chooser dialog
* to the user. There is no point offering the chooser if there are no
* non-default choices.
* </p>
*/
public static final int AVAILABILITY_FLAG_IGNORE_DEFAULT_ROUTE = 1 << 0;
/**
* Flag for {@link #isRouteAvailable}: Require an actual route to be matched.
* <p>
* If this flag is not set, then {@link #isRouteAvailable} will return true
* if it is possible to discover a matching route even if discovery is not in
* progress or if no matching route has yet been found. This feature is used to
* save resources by removing the need to perform passive route discovery on
* {@link ActivityManager#isLowRamDevice low-RAM devices}.
* </p><p>
* If this flag is set, then {@link #isRouteAvailable} will only return true if
* a matching route has actually been discovered.
* </p>
*/
public static final int AVAILABILITY_FLAG_REQUIRE_MATCH = 1 << 1;
/* package */ MediaRouter(Context context) {
mContext = context;
}
/**
* Gets an instance of the media router service associated with the context.
* <p>
* The application is responsible for holding a strong reference to the returned
* {@link MediaRouter} instance, such as by storing the instance in a field of
* the {@link android.app.Activity}, to ensure that the media router remains alive
* as long as the application is using its features.
* </p><p>
* In other words, the support library only holds a {@link WeakReference weak reference}
* to each media router instance. When there are no remaining strong references to the
* media router instance, all of its callbacks will be removed and route discovery
* will no longer be performed on its behalf.
* </p>
*
* <p>Must be called on the main thread.
*
* @return The media router instance for the context. The application must hold
* a strong reference to this object as long as it is in use.
*/
@MainThread
@NonNull
public static MediaRouter getInstance(@NonNull Context context) {
if (context == null) {
throw new IllegalArgumentException("context must not be null");
}
checkCallingThread();
if (sGlobal == null) {
sGlobal = new GlobalMediaRouter(context.getApplicationContext());
}
// Use sGlobal directly to avoid initialization.
return sGlobal.getRouter(context);
}
/**
* Resets all internal state for testing. Should be only used for testing purpose.
* <p>
* After calling this method, the caller should stop using the existing media router instances.
* Instead, the caller should create a new media router instance again by calling
* {@link #getInstance(Context)}.
* <p>
* Note that the following classes' instances need to be recreated after calling this method,
* as these classes store the media router instance on their constructor:
* <ul>
* <li>{@link androidx.mediarouter.app.MediaRouteActionProvider}
* <li>{@link androidx.mediarouter.app.MediaRouteButton}
* <li>{@link androidx.mediarouter.app.MediaRouteChooserDialog}
* <li>{@link androidx.mediarouter.app.MediaRouteControllerDialog}
* <li>{@link androidx.mediarouter.app.MediaRouteDiscoveryFragment}
* </ul>
*/
@RestrictTo(LIBRARY_GROUP)
public static void resetGlobalRouter() {
if (sGlobal == null) {
return;
}
sGlobal.reset();
sGlobal = null;
}
/** Gets the initialized global router. */
@RestrictTo(LIBRARY_GROUP)
@NonNull
static GlobalMediaRouter getGlobalRouter() {
if (sGlobal == null) {
throw new IllegalStateException(
"getGlobalRouter cannot be called when sGlobal is " + "null");
}
return sGlobal;
}
/**
* Gets information about the {@link MediaRouter.RouteInfo routes} currently known to
* this media router.
*
* <p>Must be called on the main thread.
*/
@MainThread
@NonNull
public List<RouteInfo> getRoutes() {
checkCallingThread();
return getGlobalRouter().getRoutes();
}
/**
* Gets information about the {@link MediaRouter.ProviderInfo route providers}
* currently known to this media router.
*
* <p>Must be called on the main thread.
*/
@MainThread
@NonNull
public List<ProviderInfo> getProviders() {
checkCallingThread();
return getGlobalRouter().getProviders();
}
/**
* Gets the default route for playing media content on the system.
* <p>
* The system always provides a default route.
* </p>
*
* <p>Must be called on the main thread.
*
* @return The default route, which is guaranteed to never be null.
*/
@MainThread
@NonNull
public RouteInfo getDefaultRoute() {
checkCallingThread();
return getGlobalRouter().getDefaultRoute();
}
/**
* Gets a bluetooth route for playing media content on the system.
*
* <p>Must be called on the main thread.
*
* @return A bluetooth route, if exist, otherwise null.
*/
@MainThread
@Nullable
public RouteInfo getBluetoothRoute() {
checkCallingThread();
return getGlobalRouter().getBluetoothRoute();
}
/**
* Gets the currently selected route.
* <p>
* The application should examine the route's
* {@link RouteInfo#getControlFilters media control intent filters} to assess the
* capabilities of the route before attempting to use it.
* </p>
*
* <h3>Example</h3>
* <pre>
* public boolean playMovie() {
* MediaRouter mediaRouter = MediaRouter.getInstance(context);
* MediaRouter.RouteInfo route = mediaRouter.getSelectedRoute();
*
* // First try using the remote playback interface, if supported.
* if (route.supportsControlCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)) {
* // The route supports remote playback.
* // Try to send it the Uri of the movie to play.
* Intent intent = new Intent(MediaControlIntent.ACTION_PLAY);
* intent.addCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK);
* intent.setDataAndType("http://example.com/videos/movie.mp4", "video/mp4");
* if (route.supportsControlRequest(intent)) {
* route.sendControlRequest(intent, null);
* return true; // sent the request to play the movie
* }
* }
*
* // If remote playback was not possible, then play locally.
* if (route.supportsControlCategory(MediaControlIntent.CATEGORY_LIVE_VIDEO)) {
* // The route supports live video streaming.
* // Prepare to play content locally in a window or in a presentation.
* return playMovieInWindow();
* }
*
* // Neither interface is supported, so we can't play the movie to this route.
* return false;
* }
* </pre>
*
* <p>Must be called on the main thread.
*
* @return The selected route, which is guaranteed to never be null.
* @see RouteInfo#getControlFilters
* @see RouteInfo#supportsControlCategory
* @see RouteInfo#supportsControlRequest
*/
@MainThread
@NonNull
public RouteInfo getSelectedRoute() {
checkCallingThread();
return getGlobalRouter().getSelectedRoute();
}
/**
* Returns the selected route if it matches the specified selector, otherwise
* selects the default route and returns it. If there is one live audio route
* (usually Bluetooth A2DP), it will be selected instead of default route.
*
* <p>Must be called on the main thread.
*
* @param selector The selector to match.
* @return The previously selected route if it matched the selector, otherwise the
* newly selected default route which is guaranteed to never be null.
* @see MediaRouteSelector
* @see RouteInfo#matchesSelector
*/
@MainThread
@NonNull
public RouteInfo updateSelectedRoute(@NonNull MediaRouteSelector selector) {
if (selector == null) {
throw new IllegalArgumentException("selector must not be null");
}
checkCallingThread();
if (DEBUG) {
Log.d(TAG, "updateSelectedRoute: " + selector);
}
GlobalMediaRouter globalRouter = getGlobalRouter();
RouteInfo route = globalRouter.getSelectedRoute();
if (!route.isDefaultOrBluetooth() && !route.matchesSelector(selector)) {
route = globalRouter.chooseFallbackRoute();
globalRouter.selectRoute(route, MediaRouter.UNSELECT_REASON_ROUTE_CHANGED);
}
return route;
}
/**
* Selects the specified route.
*
* <p>Must be called on the main thread.
*
* @param route The route to select.
*/
@MainThread
public void selectRoute(@NonNull RouteInfo route) {
if (route == null) {
throw new IllegalArgumentException("route must not be null");
}
checkCallingThread();
if (DEBUG) {
Log.d(TAG, "selectRoute: " + route);
}
getGlobalRouter().selectRoute(route, MediaRouter.UNSELECT_REASON_ROUTE_CHANGED);
}
/**
* Unselects the current route and selects the default route instead.
* <p>
* The reason given must be one of:
* <ul>
* <li>{@link MediaRouter#UNSELECT_REASON_UNKNOWN}</li>
* <li>{@link MediaRouter#UNSELECT_REASON_DISCONNECTED}</li>
* <li>{@link MediaRouter#UNSELECT_REASON_STOPPED}</li>
* <li>{@link MediaRouter#UNSELECT_REASON_ROUTE_CHANGED}</li>
* </ul>
*
* <p>Must be called on the main thread.
*
* @param reason The reason for disconnecting the current route.
*/
@MainThread
public void unselect(@UnselectReason int reason) {
if (reason < MediaRouter.UNSELECT_REASON_UNKNOWN ||
reason > MediaRouter.UNSELECT_REASON_ROUTE_CHANGED) {
throw new IllegalArgumentException("Unsupported reason to unselect route");
}
checkCallingThread();
// Choose the fallback route if it's not already selected.
// Otherwise, select the default route.
GlobalMediaRouter globalRouter = getGlobalRouter();
RouteInfo fallbackRoute = globalRouter.chooseFallbackRoute();
if (globalRouter.getSelectedRoute() != fallbackRoute) {
globalRouter.selectRoute(fallbackRoute, reason);
}
}
/**
* Adds the specified route as a member to the current dynamic group.
*/
@RestrictTo(LIBRARY)
@MainThread
public void addMemberToDynamicGroup(@NonNull RouteInfo route) {
if (route == null) {
throw new NullPointerException("route must not be null");
}
checkCallingThread();
getGlobalRouter().addMemberToDynamicGroup(route);
}
/**
* Removes the specified route from the current dynamic group.
*/
@RestrictTo(LIBRARY)
@MainThread
public void removeMemberFromDynamicGroup(@NonNull RouteInfo route) {
if (route == null) {
throw new NullPointerException("route must not be null");
}
checkCallingThread();
getGlobalRouter().removeMemberFromDynamicGroup(route);
}
/**
* Transfers the current dynamic group to the specified route.
*/
@RestrictTo(LIBRARY)
@MainThread
public void transferToRoute(@NonNull RouteInfo route) {
if (route == null) {
throw new NullPointerException("route must not be null");
}
checkCallingThread();
getGlobalRouter().transferToRoute(route);
}
/**
* Returns true if there is a route that matches the specified selector.
*
* <p>This method returns true if there are any available routes that match the selector
* regardless of whether they are enabled or disabled. If the {@link
* #AVAILABILITY_FLAG_IGNORE_DEFAULT_ROUTE} flag is specified, then the method will only
* consider non-default routes.
*
* <p class="note">On {@link ActivityManager#isLowRamDevice low-RAM devices} this method will
* return true if it is possible to discover a matching route even if discovery is not in
* progress or if no matching route has yet been found. Use {@link
* #AVAILABILITY_FLAG_REQUIRE_MATCH} to require an actual match.
*
* <p>Must be called on the main thread.
*
* @param selector The selector to match.
* @param flags Flags to control the determination of whether a route may be available. May be
* zero or some combination of {@link #AVAILABILITY_FLAG_IGNORE_DEFAULT_ROUTE} and {@link
* #AVAILABILITY_FLAG_REQUIRE_MATCH}.
* @return True if a matching route may be available.
*/
@MainThread
public boolean isRouteAvailable(@NonNull MediaRouteSelector selector, int flags) {
if (selector == null) {
throw new IllegalArgumentException("selector must not be null");
}
checkCallingThread();
return getGlobalRouter().isRouteAvailable(selector, flags);
}
/**
* Registers a callback to discover routes that match the selector and to receive events when
* they change.
*
* <p>This is a convenience method that has the same effect as calling {@link
* #addCallback(MediaRouteSelector, Callback, int)} without flags.
*
* <p>Must be called on the main thread.
*
* @param selector A route selector that indicates the kinds of routes that the callback would
* like to discover.
* @param callback The callback to add.
* @see #removeCallback
*/
@MainThread
public void addCallback(@NonNull MediaRouteSelector selector, @NonNull Callback callback) {
addCallback(selector, callback, 0);
}
/**
* Registers a callback to discover routes that match the selector and to receive events when
* they change.
*
* <p>The selector describes the kinds of routes that the application wants to discover. For
* example, if the application wants to use live audio routes then it should include the {@link
* MediaControlIntent#CATEGORY_LIVE_AUDIO live audio media control intent category} in its
* selector when it adds a callback to the media router. The selector may include any number of
* categories.
*
* <p>If the callback has already been registered, then the selector is added to the set of
* selectors being monitored by the callback.
*
* <p>By default, the callback will only be invoked for events that affect routes that match the
* specified selector. Event filtering may be disabled by specifying the {@link
* #CALLBACK_FLAG_UNFILTERED_EVENTS} flag when the callback is registered.
*
* <p>Applications should use the {@link #isRouteAvailable} method to determine whether is it
* possible to discover a route with the desired capabilities and therefore whether the media
* route button should be shown to the user.
*
* <p>The {@link #CALLBACK_FLAG_REQUEST_DISCOVERY} flag should be used while the application is
* in the foreground to request that passive discovery be performed if there are sufficient
* resources to allow continuous passive discovery. On {@link ActivityManager#isLowRamDevice
* low-RAM devices} this flag will be ignored to conserve resources.
*
* <p>The {@link #CALLBACK_FLAG_FORCE_DISCOVERY} flag should be used when passive discovery
* absolutely must be performed, even on low-RAM devices. This flag has a significant
* performance impact on low-RAM devices since it may cause many media route providers to be
* started simultaneously. It is much better to use {@link #CALLBACK_FLAG_REQUEST_DISCOVERY}
* instead to avoid performing passive discovery on these devices altogether.
*
* <p>The {@link #CALLBACK_FLAG_PERFORM_ACTIVE_SCAN} flag should be used when the media route
* chooser dialog is showing to confirm the presence of available routes that the user may
* connect to. This flag may use substantially more power. Once active scan is requested, it
* will be effective for 30 seconds and will be suppressed after the delay. If you need active
* scan after this duration, you have to add your callback again with the {@link
* #CALLBACK_FLAG_PERFORM_ACTIVE_SCAN} flag.
*
* <h3>Example</h3>
*
* <pre>
* public class MyActivity extends Activity {
* private MediaRouter mRouter;
* private MediaRouter.Callback mCallback;
* private MediaRouteSelector mSelector;
*
* // Add the callback on start to tell the media router what kinds of routes
* // the application is interested in so that it can get events about media routing changes
* // from the system.
* protected void onCreate(Bundle savedInstanceState) {
* super.onCreate(savedInstanceState);
*
* mRouter = MediaRouter.getInstance(this);
* mCallback = new MyCallback();
* mSelector = new MediaRouteSelector.Builder()
* .addControlCategory(MediaControlIntent.CATEGORY_LIVE_AUDIO)
* .addControlCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)
* .build();
* mRouter.addCallback(mSelector, mCallback, /* flags= */ 0);
* }
*
* // Add the callback flag CALLBACK_FLAG_REQUEST_DISCOVERY on start by calling
* // addCallback() again so that the media router can try to discover suitable ones.
* public void onStart() {
* super.onStart();
*
* mRouter.addCallback(mSelector, mCallback,
* MediaRouter.CALLBACK_FLAG_REQUEST_DISCOVERY);
*
* MediaRouter.RouteInfo route = mRouter.updateSelectedRoute(mSelector);
* // do something with the route...
* }
*
* // Remove the callback flag CALLBACK_FLAG_REQUEST_DISCOVERY on stop by calling
* // addCallback() again in order to tell the media router that it no longer
* // needs to invest effort trying to discover routes of these kinds for now.
* public void onStop() {
* mRouter.addCallback(mSelector, mCallback, /* flags= */ 0);
*
* super.onStop();
* }
*
* // Remove the callback when the activity is destroyed.
* public void onDestroy() {
* mRouter.removeCallback(mCallback);
*
* super.onDestroy();
* }
*
* private final class MyCallback extends MediaRouter.Callback {
* // Implement callback methods as needed.
* }
* }
* </pre>
*
* <p>Must be called on the main thread.
*
* @param selector A route selector that indicates the kinds of routes that the callback would
* like to discover.
* @param callback The callback to add.
* @param flags Flags to control the behavior of the callback. May be zero or a combination of
* {@link #CALLBACK_FLAG_PERFORM_ACTIVE_SCAN} and {@link #CALLBACK_FLAG_UNFILTERED_EVENTS}.
* @see #removeCallback
*/
// TODO: Change the usages of addCallback() for changing flags when setCallbackFlags() is added.
@MainThread
public void addCallback(
@NonNull MediaRouteSelector selector,
@NonNull Callback callback,
@CallbackFlags int flags) {
if (selector == null) {
throw new IllegalArgumentException("selector must not be null");
}
if (callback == null) {
throw new IllegalArgumentException("callback must not be null");
}
checkCallingThread();
if (DEBUG) {
Log.d(TAG, "addCallback: selector=" + selector
+ ", callback=" + callback + ", flags=" + Integer.toHexString(flags));
}
CallbackRecord record;
int index = findCallbackRecord(callback);
if (index < 0) {
record = new CallbackRecord(this, callback);
mCallbackRecords.add(record);
} else {
record = mCallbackRecords.get(index);
}
boolean updateNeeded = false;
if (flags != record.mFlags) {
record.mFlags = flags;
updateNeeded = true;
}
long currentTime = SystemClock.elapsedRealtime();
if ((flags & CALLBACK_FLAG_PERFORM_ACTIVE_SCAN) != 0) {
// If the flag has active scan, the active scan might be suppressed previously if the
// previous change is too long ago. In this case, the discovery request needs to be
// updated so that the active scan state can be true again.
updateNeeded = true;
}
record.mTimestamp = currentTime;
if (!record.mSelector.contains(selector)) {
record.mSelector = new MediaRouteSelector.Builder(record.mSelector)
.addSelector(selector)
.build();
updateNeeded = true;
}
if (updateNeeded) {
getGlobalRouter().updateDiscoveryRequest();
}
}
/**
* Removes the specified callback. It will no longer receive events about
* changes to media routes.
*
* <p>Must be called on the main thread.
*
* @param callback The callback to remove.
* @see #addCallback
*/
@MainThread
public void removeCallback(@NonNull Callback callback) {
if (callback == null) {
throw new IllegalArgumentException("callback must not be null");
}
checkCallingThread();
if (DEBUG) {
Log.d(TAG, "removeCallback: callback=" + callback);
}
int index = findCallbackRecord(callback);
if (index >= 0) {
mCallbackRecords.remove(index);
getGlobalRouter().updateDiscoveryRequest();
}
}
private int findCallbackRecord(Callback callback) {
final int count = mCallbackRecords.size();
for (int i = 0; i < count; i++) {
if (mCallbackRecords.get(i).mCallback == callback) {
return i;
}
}
return -1;
}
/**
* Sets a listener for receiving events when the selected route is about to be changed.
*
* <p>Must be called on the main thread.
*/
@MainThread
public void setOnPrepareTransferListener(@Nullable OnPrepareTransferListener listener) {
checkCallingThread();
getGlobalRouter().mOnPrepareTransferListener = listener;
}
/**
* Registers a media route provider within this application process.
* <p>
* The provider will be added to the list of providers that all {@link MediaRouter}
* instances within this process can use to discover routes.
* </p>
*
* <p>Must be called on the main thread.
*
* @param providerInstance The media route provider instance to add.
* @see MediaRouteProvider
* @see #removeCallback
*/
@MainThread
public void addProvider(@NonNull MediaRouteProvider providerInstance) {
if (providerInstance == null) {
throw new IllegalArgumentException("providerInstance must not be null");
}
checkCallingThread();
if (DEBUG) {
Log.d(TAG, "addProvider: " + providerInstance);
}
getGlobalRouter().addProvider(providerInstance);
}
/**
* Unregisters a media route provider within this application process.
* <p>
* The provider will be removed from the list of providers that all {@link MediaRouter}
* instances within this process can use to discover routes.
* </p>
*
* <p>Must be called on the main thread.
*
* @param providerInstance The media route provider instance to remove.
* @see MediaRouteProvider
* @see #addCallback
*/
@MainThread
public void removeProvider(@NonNull MediaRouteProvider providerInstance) {
if (providerInstance == null) {
throw new IllegalArgumentException("providerInstance must not be null");
}
checkCallingThread();
if (DEBUG) {
Log.d(TAG, "removeProvider: " + providerInstance);
}
getGlobalRouter().removeProvider(providerInstance);
}
/**
* Adds a remote control client to enable remote control of the volume of the selected route.
*
* <p>The remote control client must have previously been registered with the audio manager
* using the {@link android.media.AudioManager#registerRemoteControlClient
* AudioManager.registerRemoteControlClient} method.
*
* <p>Must be called on the main thread.
*
* @param remoteControlClient The {@link android.media.RemoteControlClient} to register.
* @deprecated Use {@link #setMediaSessionCompat} instead.
*/
@MainThread
@Deprecated
public void addRemoteControlClient(@NonNull Object remoteControlClient) {
if (remoteControlClient == null) {
throw new IllegalArgumentException("remoteControlClient must not be null");
}
checkCallingThread();
if (DEBUG) {
Log.d(TAG, "addRemoteControlClient: " + remoteControlClient);
}
getGlobalRouter()
.addRemoteControlClient((android.media.RemoteControlClient) remoteControlClient);
}
/**
* Removes a remote control client.
*
* <p>Must be called on the main thread.
*
* @param remoteControlClient The {@link android.media.RemoteControlClient} to unregister.
*/
@MainThread
public void removeRemoteControlClient(@NonNull Object remoteControlClient) {
if (remoteControlClient == null) {
throw new IllegalArgumentException("remoteControlClient must not be null");
}
checkCallingThread();
if (DEBUG) {
Log.d(TAG, "removeRemoteControlClient: " + remoteControlClient);
}
getGlobalRouter()
.removeRemoteControlClient((android.media.RemoteControlClient) remoteControlClient);
}
/**
* Equivalent to {@link #setMediaSessionCompat}, except it takes an {@link
* android.media.session.MediaSession}.
*/
@MainThread
public void setMediaSession(@Nullable Object mediaSession) {
checkCallingThread();
if (DEBUG) {
Log.d(TAG, "setMediaSession: " + mediaSession);
}
getGlobalRouter().setMediaSession(mediaSession);
}
/**
* Associates the provided {@link MediaSessionCompat} to this router.
*
* <p>Maintains the internal state of the provided session to signal it's linked to the
* currently selected route at any given time. This guarantees that the system UI shows the
* correct route name when applicable.
*
* <p>Must be called on the main thread.
*
* @param mediaSession The {@link MediaSessionCompat} to associate to this media router, or null
* to clear the existing association.
*/
@MainThread
public void setMediaSessionCompat(@Nullable MediaSessionCompat mediaSession) {
checkCallingThread();
if (DEBUG) {
Log.d(TAG, "setMediaSessionCompat: " + mediaSession);
}
getGlobalRouter().setMediaSessionCompat(mediaSession);
}
@Nullable
public MediaSessionCompat.Token getMediaSessionToken() {
return sGlobal == null ? null : sGlobal.getMediaSessionToken();
// Use sGlobal exceptionally due to unchecked thread.
}
/**
* Gets {@link MediaRouterParams parameters} of the media router service associated with this
* media router.
*
* <p>Must be called on the main thread.
*/
@MainThread
@Nullable
public MediaRouterParams getRouterParams() {
checkCallingThread();
return getGlobalRouter().getRouterParams();
}
/**
* Sets {@link MediaRouterParams parameters} of the media router service associated with this
* media router.
*
* <p>Must be called on the main thread.
*
* @param params The parameter to set
*/
@MainThread
public void setRouterParams(@Nullable MediaRouterParams params) {
checkCallingThread();
getGlobalRouter().setRouterParams(params);
}
/**
* Sets the {@link RouteListingPreference} of the app associated to this media router.
*
* <p>This method does nothing on devices running API 33 or older.
*
* <p>Use this method to inform the system UI of the routes that you would like to list for
* media routing, via the Output Switcher.
*
* <p>You should call this method immediately after creating an instance and immediately after
* receiving any {@link Callback route list changes} 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 (which reflect in the system's Output Switcher).
*
* <p>Notes:
*
* <ul>
* <li>You should not include the ids of two or more routes with a match in their {@link
* MediaRouteDescriptor#getDeduplicationIds() deduplication ids}. If you do, the system
* will deduplicate them using its own criteria.
* <li>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.
* <li>You can use this method to change how routes are listed using dynamic criteria. For
* example, you can disable routing while an {@link
* RouteListingPreference.Item#SUBTEXT_AD_ROUTING_DISALLOWED ad is playing}).
* </ul>
*
* @param routeListingPreference The {@link RouteListingPreference} for the system to use for
* route listing. When null, the system uses its default listing criteria.
*/
@MainThread
public void setRouteListingPreference(@Nullable RouteListingPreference routeListingPreference) {
checkCallingThread();
getGlobalRouter().setRouteListingPreference(routeListingPreference);
}
/**
* Throws an {@link IllegalStateException} if the calling thread is not the main thread.
*/
static void checkCallingThread() {
if (Looper.myLooper() != Looper.getMainLooper()) {
throw new IllegalStateException("The media router service must only be "
+ "accessed on the application's main thread.");
}
}
/**
* Returns whether the media transfer feature is enabled.
*
* @see MediaRouter
*/
@RestrictTo(LIBRARY)
public static boolean isMediaTransferEnabled() {
if (sGlobal == null) {
return false;
}
return getGlobalRouter().isMediaTransferEnabled();
}
@RestrictTo(LIBRARY)
public static boolean isGroupVolumeUxEnabled() {
if (sGlobal == null) {
return false;
}
return getGlobalRouter().isGroupVolumeUxEnabled();
}
/**
* Returns how many {@link MediaRouter.Callback callbacks} are registered throughout the all
* {@link MediaRouter media routers} in this process.
*/
static int getGlobalCallbackCount() {
if (sGlobal == null) {
return 0;
}
return getGlobalRouter().getCallbackCount();
}
/**
* Returns whether transferring media from remote to local is enabled.
*/
static boolean isTransferToLocalEnabled() {
return getGlobalRouter().isTransferToLocalEnabled();
}
/**
* Provides information about a media route.
* <p>
* Each media route has a list of {@link MediaControlIntent media control}
* {@link #getControlFilters intent filters} that describe the capabilities of the
* route and the manner in which it is used and controlled.
* </p>
*/
public static class RouteInfo {
private final ProviderInfo mProvider;
final String mDescriptorId;
final String mUniqueId;
private String mName;
private String mDescription;
private Uri mIconUri;
boolean mEnabled;
private @ConnectionState int mConnectionState;
private boolean mCanDisconnect;
private final ArrayList<IntentFilter> mControlFilters = new ArrayList<>();
private int mPlaybackType;
private int mPlaybackStream;
private @DeviceType int mDeviceType;
private int mVolumeHandling;
private int mVolume;
private int mVolumeMax;
private Display mPresentationDisplay;
private int mPresentationDisplayId = PRESENTATION_DISPLAY_ID_NONE;
private Bundle mExtras;
private IntentSender mSettingsIntent;
MediaRouteDescriptor mDescriptor;
private List<RouteInfo> mMemberRoutes = new ArrayList<>();
private Map<String, DynamicRouteDescriptor> mDynamicGroupDescriptors;
@IntDef({
CONNECTION_STATE_DISCONNECTED,
CONNECTION_STATE_CONNECTING,
CONNECTION_STATE_CONNECTED
})
@Retention(RetentionPolicy.SOURCE)
private @interface ConnectionState {}
/**
* The default connection state indicating the route is disconnected.
*
* @see #getConnectionState
*/
public static final int CONNECTION_STATE_DISCONNECTED = 0;
/**
* A connection state indicating the route is in the process of connecting and is not yet
* ready for use.
*
* @see #getConnectionState
*/
public static final int CONNECTION_STATE_CONNECTING = 1;
/**
* A connection state indicating the route is connected.
*
* @see #getConnectionState
*/
public static final int CONNECTION_STATE_CONNECTED = 2;
@IntDef({PLAYBACK_TYPE_LOCAL, PLAYBACK_TYPE_REMOTE})
@Retention(RetentionPolicy.SOURCE)
private @interface PlaybackType {}
/**
* The default playback type, "local", indicating the presentation of the media
* is happening on the same device (e.g. a phone, a tablet) as where it is
* controlled from.
*
* @see #getPlaybackType
*/
public static final int PLAYBACK_TYPE_LOCAL = 0;
/**
* A playback type indicating the presentation of the media is happening on
* a different device (i.e. the remote device) than where it is controlled from.
*
* @see #getPlaybackType
*/
public static final int PLAYBACK_TYPE_REMOTE = 1;
@RestrictTo(LIBRARY)
@IntDef({
DEVICE_TYPE_UNKNOWN,
DEVICE_TYPE_TV,
DEVICE_TYPE_SPEAKER,
DEVICE_TYPE_BLUETOOTH,
DEVICE_TYPE_AUDIO_VIDEO_RECEIVER,
DEVICE_TYPE_TABLET,
DEVICE_TYPE_TABLET_DOCKED,
DEVICE_TYPE_COMPUTER,
DEVICE_TYPE_GAME_CONSOLE,
DEVICE_TYPE_CAR,
DEVICE_TYPE_SMARTWATCH,
DEVICE_TYPE_GROUP
})
@Retention(RetentionPolicy.SOURCE)
public @interface DeviceType {}
/**
* The default receiver device type of the route indicating the type is unknown.
*
* @see #getDeviceType
*/
@RestrictTo(LIBRARY)
public static final int DEVICE_TYPE_UNKNOWN = 0;
/**
* A receiver device type of the route indicating the presentation of the media is happening
* on a TV.
*
* @see #getDeviceType
*/
public static final int DEVICE_TYPE_TV = 1;
/**
* A receiver device type of the route indicating the presentation of the media is happening
* on a speaker.
*
* @see #getDeviceType
*/
public static final int DEVICE_TYPE_SPEAKER = 2;
/**
* A receiver device type of the route indicating the presentation of the media is happening
* on a bluetooth device such as a bluetooth speaker.
*
* @see #getDeviceType
*/
@RestrictTo(LIBRARY)
public static final int DEVICE_TYPE_BLUETOOTH = 3;
/**
* A receiver device type indicating that the presentation of the media is happening on an
* Audio/Video receiver (AVR).
*
* @see #getDeviceType
*/
public static final int DEVICE_TYPE_AUDIO_VIDEO_RECEIVER = 4;
/**
* A receiver device type indicating that the presentation of the media is happening on a
* tablet.
*
* @see #getDeviceType
*/
public static final int DEVICE_TYPE_TABLET = 5;
/**
* A receiver device type indicating that the presentation of the media is happening on a
* docked tablet.
*
* @see #getDeviceType
*/
public static final int DEVICE_TYPE_TABLET_DOCKED = 6;
/**
* A receiver device type indicating that the presentation of the media is happening on a
* computer.
*
* @see #getDeviceType
*/
public static final int DEVICE_TYPE_COMPUTER = 7;
/**
* A receiver device type indicating that the presentation of the media is happening on a
* gaming console.
*
* @see #getDeviceType
*/
public static final int DEVICE_TYPE_GAME_CONSOLE = 8;
/**
* A receiver device type indicating that the presentation of the media is happening on a
* car.
*
* @see #getDeviceType
*/
public static final int DEVICE_TYPE_CAR = 9;
/**
* A receiver device type indicating that the presentation of the media is happening on a
* smartwatch.
*
* @see #getDeviceType
*/
public static final int DEVICE_TYPE_SMARTWATCH = 10;
/**
* A receiver device type indicating that the presentation of the media is happening on a
* group of devices.
*
* @see #getDeviceType
*/
public static final int DEVICE_TYPE_GROUP = 1000;
@IntDef({PLAYBACK_VOLUME_FIXED, PLAYBACK_VOLUME_VARIABLE})
@Retention(RetentionPolicy.SOURCE)
private @interface PlaybackVolume {}
/**
* Playback information indicating the playback volume is fixed, i.e. it cannot be
* controlled from this object. An example of fixed playback volume is a remote player,
* playing over HDMI where the user prefers to control the volume on the HDMI sink, rather
* than attenuate at the source.
*
* @see #getVolumeHandling
*/
public static final int PLAYBACK_VOLUME_FIXED = 0;
/**
* Playback information indicating the playback volume is variable and can be controlled
* from this object.
*
* @see #getVolumeHandling
*/
public static final int PLAYBACK_VOLUME_VARIABLE = 1;
/**
* The default presentation display id indicating no presentation display is associated
* with the route.
*/
@RestrictTo(LIBRARY)
public static final int PRESENTATION_DISPLAY_ID_NONE = -1;
static final int CHANGE_GENERAL = 1 << 0;
static final int CHANGE_VOLUME = 1 << 1;
static final int CHANGE_PRESENTATION_DISPLAY = 1 << 2;
// Should match to SystemMediaRouteProvider.PACKAGE_NAME.
static final String SYSTEM_MEDIA_ROUTE_PROVIDER_PACKAGE_NAME = "android";
RouteInfo(ProviderInfo provider, String descriptorId, String uniqueId) {
mProvider = provider;
mDescriptorId = descriptorId;
mUniqueId = uniqueId;
}
/**
* Gets information about the provider of this media route.
*/
@NonNull
public ProviderInfo getProvider() {
return mProvider;
}
/**
* Gets the unique id of the route.
* <p>
* The route unique id functions as a stable identifier by which the route is known.
* For example, an application can use this id as a token to remember the
* selected route across restarts or to communicate its identity to a service.
* </p>
*
* @return The unique id of the route, never null.
*/
@NonNull
public String getId() {
return mUniqueId;
}
/**
* Gets the user-visible name of the route.
* <p>
* The route name identifies the destination represented by the route.
* It may be a user-supplied name, an alias, or device serial number.
* </p>
*
* @return The user-visible name of a media route. This is the string presented
* to users who may select this as the active route.
*/
@NonNull
public String getName() {
return mName;
}
/**
* Gets the user-visible description of the route.
* <p>
* The route description describes the kind of destination represented by the route.
* It may be a user-supplied string, a model number or brand of device.
* </p>
*
* @return The description of the route, or null if none.
*/
@Nullable
public String getDescription() {
return mDescription;
}
/**
* Gets the URI of the icon representing this route.
* <p>
* This icon will be used in picker UIs if available.
* </p>
*
* @return The URI of the icon representing this route, or null if none.
*/
@Nullable
public Uri getIconUri() {
return mIconUri;
}
/**
* Returns true if this route is enabled and may be selected.
*
* @return True if this route is enabled.
*/
public boolean isEnabled() {
return mEnabled;
}
/**
* Returns true if the route is in the process of connecting and is not
* yet ready for use.
*
* @return True if this route is in the process of connecting.
* @deprecated use {@link #getConnectionState} instead.
*/
@Deprecated
public boolean isConnecting() {
return mConnectionState == CONNECTION_STATE_CONNECTING;
}
/**
* Gets the connection state of the route.
*
* @return The connection state of this route: {@link #CONNECTION_STATE_DISCONNECTED},
* {@link #CONNECTION_STATE_CONNECTING}, or {@link #CONNECTION_STATE_CONNECTED}.
*/
@ConnectionState
public int getConnectionState() {
return mConnectionState;
}
/**
* Returns true if this route is currently selected.
*
* <p>Must be called on the main thread.
*
* @return True if this route is currently selected.
* @see MediaRouter#getSelectedRoute
*/
// Note: Only one representative route can return true. For instance:
// - If this route is a selected (non-group) route, it returns true.
// - If this route is a selected group route, it returns true.
// - If this route is a selected member route of a group, it returns false.
@MainThread
public boolean isSelected() {
checkCallingThread();
return getGlobalRouter().getSelectedRoute() == this;
}
/**
* Returns true if this route is the default route.
*
* <p>Must be called on the main thread.
*
* @return True if this route is the default route.
* @see MediaRouter#getDefaultRoute
*/
@MainThread
public boolean isDefault() {
checkCallingThread();
return getGlobalRouter().getDefaultRoute() == this;
}
/**
* Returns true if this route is a bluetooth route.
*
* <p>Must be called on the main thread.
*
* @return True if this route is a bluetooth route.
* @see MediaRouter#getBluetoothRoute
*/
@MainThread
public boolean isBluetooth() {
checkCallingThread();
return getGlobalRouter().getBluetoothRoute() == this;
}
/**
* Returns true if this route is the default route and the device speaker.
*
* @return True if this route is the default route and the device speaker.
*/
public boolean isDeviceSpeaker() {
int defaultAudioRouteNameResourceId = Resources.getSystem().getIdentifier(
"default_audio_route_name", "string", "android");
return isDefault() && TextUtils.equals(
Resources.getSystem().getText(defaultAudioRouteNameResourceId), mName);
}
/**
* Gets a list of {@link MediaControlIntent media control intent} filters that
* describe the capabilities of this route and the media control actions that
* it supports.
*
* @return A list of intent filters that specifies the media control intents that
* this route supports.
* @see MediaControlIntent
* @see #supportsControlCategory
* @see #supportsControlRequest
*/
@NonNull
public List<IntentFilter> getControlFilters() {
return mControlFilters;
}
/**
* Returns true if the route supports at least one of the capabilities
* described by a media route selector.
*
* <p>Must be called on the main thread.
*
* @param selector The selector that specifies the capabilities to check.
* @return True if the route supports at least one of the capabilities
* described in the media route selector.
*/
@MainThread
public boolean matchesSelector(@NonNull MediaRouteSelector selector) {
if (selector == null) {
throw new IllegalArgumentException("selector must not be null");
}
checkCallingThread();
return selector.matchesControlFilters(mControlFilters);
}
/**
* Returns true if the route supports the specified {@link MediaControlIntent media control}
* category.
*
* <p>Media control categories describe the capabilities of this route such as whether it
* supports live audio streaming or remote playback.
*
* <p>Must be called on the main thread.
*
* @param category A {@link MediaControlIntent media control} category such as {@link
* MediaControlIntent#CATEGORY_LIVE_AUDIO}, {@link
* MediaControlIntent#CATEGORY_LIVE_VIDEO}, {@link
* MediaControlIntent#CATEGORY_REMOTE_PLAYBACK}, or a provider-defined media control
* category.
* @return True if the route supports the specified intent category.
* @see MediaControlIntent
* @see #getControlFilters
*/
@MainThread
public boolean supportsControlCategory(@NonNull String category) {
if (category == null) {
throw new IllegalArgumentException("category must not be null");
}
checkCallingThread();
for (IntentFilter intentFilter : mControlFilters) {
if (intentFilter.hasCategory(category)) {
return true;
}
}
return false;
}
/**
* Returns true if the route supports the specified {@link MediaControlIntent media control}
* category and action.
*
* <p>Media control actions describe specific requests that an application can ask a route
* to perform.
*
* <p>Must be called on the main thread.
*
* @param category A {@link MediaControlIntent media control} category such as {@link
* MediaControlIntent#CATEGORY_LIVE_AUDIO}, {@link
* MediaControlIntent#CATEGORY_LIVE_VIDEO}, {@link
* MediaControlIntent#CATEGORY_REMOTE_PLAYBACK}, or a provider-defined media control
* category.
* @param action A {@link MediaControlIntent media control} action such as {@link
* MediaControlIntent#ACTION_PLAY}.
* @return True if the route supports the specified intent action.
* @see MediaControlIntent
* @see #getControlFilters
*/
@MainThread
public boolean supportsControlAction(@NonNull String category, @NonNull String action) {
if (category == null) {
throw new IllegalArgumentException("category must not be null");
}
if (action == null) {
throw new IllegalArgumentException("action must not be null");
}
checkCallingThread();
for (IntentFilter intentFilter : mControlFilters) {
if (intentFilter.hasCategory(category) && intentFilter.hasAction(action)) {
return true;
}
}
return false;
}
/**
* Returns true if the route supports the specified
* {@link MediaControlIntent media control} request.
* <p>
* Media control requests are used to request the route to perform
* actions such as starting remote playback of a media item.
* </p>
*
* <p>Must be called on the main thread.
*
* @param intent A {@link MediaControlIntent media control intent}.
* @return True if the route can handle the specified intent.
* @see MediaControlIntent
* @see #getControlFilters
*/
@MainThread
public boolean supportsControlRequest(@NonNull Intent intent) {
if (intent == null) {
throw new IllegalArgumentException("intent must not be null");
}
checkCallingThread();
ContentResolver contentResolver = getGlobalRouter().getContentResolver();
for (IntentFilter intentFilter : mControlFilters) {
if (intentFilter.match(contentResolver, intent, true, TAG) >= 0) {
return true;
}
}
return false;
}
/**
* Sends a {@link MediaControlIntent media control} request to be performed asynchronously
* by the route's destination.
*
* <p>Media control requests are used to request the route to perform actions such as
* starting remote playback of a media item.
*
* <p>This function may only be called on a selected route. Control requests sent to
* unselected routes will fail.
*
* <p>Must be called on the main thread.
*
* @param intent A {@link MediaControlIntent media control intent}.
* @param callback A {@link ControlRequestCallback} to invoke with the result of the
* request, or null if no result is required.
* @see MediaControlIntent
*/
@MainThread
public void sendControlRequest(
@NonNull Intent intent, @Nullable ControlRequestCallback callback) {
if (intent == null) {
throw new IllegalArgumentException("intent must not be null");
}
checkCallingThread();
getGlobalRouter().sendControlRequest(this, intent, callback);
}
/**
* Gets the type of playback associated with this route.
*
* @return The type of playback associated with this route: {@link #PLAYBACK_TYPE_LOCAL}
* or {@link #PLAYBACK_TYPE_REMOTE}.
*/
@PlaybackType
public int getPlaybackType() {
return mPlaybackType;
}
/**
* Gets the audio stream over which the playback associated with this route is performed.
*
* @return The stream over which the playback associated with this route is performed.
*/
public int getPlaybackStream() {
return mPlaybackStream;
}
/**
* Gets the type of the receiver device associated with this route.
*
* @return The type of the receiver device associated with this route.
*/
@DeviceType
public int getDeviceType() {
return mDeviceType;
}
/** */
@RestrictTo(LIBRARY)
public boolean isDefaultOrBluetooth() {
if (isDefault() || mDeviceType == DEVICE_TYPE_BLUETOOTH) {
return true;
}
// This is a workaround for platform version 23 or below where the system route
// provider doesn't specify device type for bluetooth media routes.
return isSystemMediaRouteProvider(this)
&& supportsControlCategory(MediaControlIntent.CATEGORY_LIVE_AUDIO)
&& !supportsControlCategory(MediaControlIntent.CATEGORY_LIVE_VIDEO);
}
/**
* Returns {@code true} if the route is selectable.
*/
boolean isSelectable() {
// This tests whether the route is still valid and enabled.
// The route descriptor field is set to null when the route is removed.
return mDescriptor != null && mEnabled;
}
private static boolean isSystemMediaRouteProvider(MediaRouter.RouteInfo route) {
return TextUtils.equals(route.getProviderInstance().getMetadata().getPackageName(),
SYSTEM_MEDIA_ROUTE_PROVIDER_PACKAGE_NAME);
}
/**
* Gets information about how volume is handled on the route.
*
* @return How volume is handled on the route: {@link #PLAYBACK_VOLUME_FIXED}
* or {@link #PLAYBACK_VOLUME_VARIABLE}.
*/
@PlaybackVolume
public int getVolumeHandling() {
if (isGroup() && !isGroupVolumeUxEnabled()) {
return PLAYBACK_VOLUME_FIXED;
}
return mVolumeHandling;
}
/**
* Gets the current volume for this route. Depending on the route, this may only
* be valid if the route is currently selected.
*
* @return The volume at which the playback associated with this route is performed.
*/
public int getVolume() {
return mVolume;
}
/**
* Gets the maximum volume at which the playback associated with this route is performed.
*
* @return The maximum volume at which the playback associated with
* this route is performed.
*/
public int getVolumeMax() {
return mVolumeMax;
}
/**
* Gets whether this route supports disconnecting without interrupting playback.
*
* @return True if this route can disconnect without stopping playback, false otherwise.
*/
public boolean canDisconnect() {
return mCanDisconnect;
}
/**
* Requests a volume change for this route asynchronously.
* <p>
* This function may only be called on a selected route. It will have
* no effect if the route is currently unselected.
* </p>
*
* <p>Must be called on the main thread.
*
* @param volume The new volume value between 0 and {@link #getVolumeMax}.
*/
@MainThread
public void requestSetVolume(int volume) {
checkCallingThread();
getGlobalRouter().requestSetVolume(this, Math.min(mVolumeMax, Math.max(0, volume)));
}
/**
* Requests an incremental volume update for this route asynchronously.
* <p>
* This function may only be called on a selected route. It will have
* no effect if the route is currently unselected.
* </p>
*
* <p>Must be called on the main thread.
*
* @param delta The delta to add to the current volume.
*/
@MainThread
public void requestUpdateVolume(int delta) {
checkCallingThread();
if (delta != 0) {
getGlobalRouter().requestUpdateVolume(this, delta);
}
}
/**
* Gets the {@link Display} that should be used by the application to show
* a {@link android.app.Presentation} on an external display when this route is selected.
* Depending on the route, this may only be valid if the route is currently
* selected.
* <p>
* The preferred presentation display may change independently of the route
* being selected or unselected. For example, the presentation display
* of the default system route may change when an external HDMI display is connected
* or disconnected even though the route itself has not changed.
* </p><p>
* This method may return null if there is no external display associated with
* the route or if the display is not ready to show UI yet.
* </p><p>
* The application should listen for changes to the presentation display
* using the {@link Callback#onRoutePresentationDisplayChanged} callback and
* show or dismiss its {@link android.app.Presentation} accordingly when the display
* becomes available or is removed.
* </p><p>
* This method only makes sense for
* {@link MediaControlIntent#CATEGORY_LIVE_VIDEO live video} routes.
* </p>
*
* <p>Must be called on the main thread.
*
* @return The preferred presentation display to use when this route is
* selected or null if none.
* @see MediaControlIntent#CATEGORY_LIVE_VIDEO
* @see android.app.Presentation
*/
@MainThread
@Nullable
public Display getPresentationDisplay() {
checkCallingThread();
if (mPresentationDisplayId >= 0 && mPresentationDisplay == null) {
mPresentationDisplay = getGlobalRouter().getDisplay(mPresentationDisplayId);
}
return mPresentationDisplay;
}
/**
* Gets the route's presentation display id, or -1 if none.
*/
@RestrictTo(LIBRARY)
public int getPresentationDisplayId() {
return mPresentationDisplayId;
}
/**
* Gets a collection of extra properties about this route that were supplied
* by its media route provider, or null if none.
*/
@Nullable
public Bundle getExtras() {
return mExtras;
}
/**
* Gets an intent sender for launching a settings activity for this
* route.
*/
@Nullable
public IntentSender getSettingsIntent() {
return mSettingsIntent;
}
/**
* Selects this media route.
*
* <p>Must be called on the main thread.
*/
@MainThread
public void select() {
checkCallingThread();
getGlobalRouter().selectRoute(this, MediaRouter.UNSELECT_REASON_ROUTE_CHANGED);
}
/**
* Returns true if the route has one or more members
*/
@RestrictTo(LIBRARY)
public boolean isGroup() {
return getMemberRoutes().size() >= 1;
}
/**
* Gets the dynamic group state of the given route.
*/
@RestrictTo(LIBRARY)
@Nullable
public DynamicGroupState getDynamicGroupState(@NonNull RouteInfo route) {
if (route == null) {
throw new NullPointerException("route must not be null");
}
if (mDynamicGroupDescriptors != null
&& mDynamicGroupDescriptors.containsKey(route.mUniqueId)) {
return new DynamicGroupState(mDynamicGroupDescriptors.get(route.mUniqueId));
}
return null;
}
/**
* Returns the routes in this group
*
* @return The list of the routes in this group
*/
@RestrictTo(LIBRARY)
@NonNull
public List<RouteInfo> getMemberRoutes() {
return Collections.unmodifiableList(mMemberRoutes);
}
/**
*
*/
@MainThread
@RestrictTo(LIBRARY)
@Nullable
public DynamicGroupRouteController getDynamicGroupController() {
checkCallingThread();
//TODO: handle multiple controllers case
RouteController controller = getGlobalRouter().mSelectedRouteController;
if (controller instanceof DynamicGroupRouteController) {
return (DynamicGroupRouteController) controller;
}
return null;
}
@Override
@NonNull
public String toString() {
StringBuilder sb = new StringBuilder();
sb.append("MediaRouter.RouteInfo{ uniqueId=").append(mUniqueId)
.append(", name=").append(mName)
.append(", description=").append(mDescription)
.append(", iconUri=").append(mIconUri)
.append(", enabled=").append(mEnabled)
.append(", connectionState=").append(mConnectionState)
.append(", canDisconnect=").append(mCanDisconnect)
.append(", playbackType=").append(mPlaybackType)
.append(", playbackStream=").append(mPlaybackStream)
.append(", deviceType=").append(mDeviceType)
.append(", volumeHandling=").append(mVolumeHandling)
.append(", volume=").append(mVolume)
.append(", volumeMax=").append(mVolumeMax)
.append(", presentationDisplayId=").append(mPresentationDisplayId)
.append(", extras=").append(mExtras)
.append(", settingsIntent=").append(mSettingsIntent)
.append(", providerPackageName=").append(mProvider.getPackageName());
if (isGroup()) {
sb.append(", members=[");
final int count = mMemberRoutes.size();
for (int i = 0; i < count; i++) {
if (i > 0) sb.append(", ");
if (mMemberRoutes.get(i) != this) {
sb.append(mMemberRoutes.get(i).getId());
}
}
sb.append(']');
}
sb.append(" }");
return sb.toString();
}
int maybeUpdateDescriptor(MediaRouteDescriptor descriptor) {
int changes = 0;
if (mDescriptor != descriptor) {
changes = updateDescriptor(descriptor);
}
return changes;
}
private boolean isSameControlFilters(List<IntentFilter> filters1,
List<IntentFilter> filters2) {
if (filters1 == filters2) {
return true;
}
if (filters1 == null || filters2 == null) {
return false;
}
ListIterator<IntentFilter> e1 = filters1.listIterator();
ListIterator<IntentFilter> e2 = filters2.listIterator();
while (e1.hasNext() && e2.hasNext()) {
if (!isSameControlFilter(e1.next(), e2.next())) {
return false;
}
}
return !(e1.hasNext() || e2.hasNext());
}
private boolean isSameControlFilter(IntentFilter filter1, IntentFilter filter2) {
if (filter1 == filter2) {
return true;
}
if (filter1 == null || filter2 == null) {
return false;
}
// Check only actions and categories for a brief comparison
int countActions = filter1.countActions();
if (countActions != filter2.countActions()) {
return false;
}
for (int i = 0; i < countActions; ++i) {
if (!filter1.getAction(i).equals(filter2.getAction(i))) {
return false;
}
}
int countCategories = filter1.countCategories();
if (countCategories != filter2.countCategories()) {
return false;
}
for (int i = 0; i < countCategories; ++i) {
if (!filter1.getCategory(i).equals(filter2.getCategory(i))) {
return false;
}
}
return true;
}
int updateDescriptor(MediaRouteDescriptor descriptor) {
int changes = 0;
mDescriptor = descriptor;
if (descriptor != null) {
if (!ObjectsCompat.equals(mName, descriptor.getName())) {
mName = descriptor.getName();
changes |= CHANGE_GENERAL;
}
if (!ObjectsCompat.equals(mDescription, descriptor.getDescription())) {
mDescription = descriptor.getDescription();
changes |= CHANGE_GENERAL;
}
if (!ObjectsCompat.equals(mIconUri, descriptor.getIconUri())) {
mIconUri = descriptor.getIconUri();
changes |= CHANGE_GENERAL;
}
if (mEnabled != descriptor.isEnabled()) {
mEnabled = descriptor.isEnabled();
changes |= CHANGE_GENERAL;
}
if (mConnectionState != descriptor.getConnectionState()) {
mConnectionState = descriptor.getConnectionState();
changes |= CHANGE_GENERAL;
}
// Use custom method to compare two control filters to confirm it is changed.
if (!isSameControlFilters(mControlFilters, descriptor.getControlFilters())) {
mControlFilters.clear();
mControlFilters.addAll(descriptor.getControlFilters());
changes |= CHANGE_GENERAL;
}
if (mPlaybackType != descriptor.getPlaybackType()) {
mPlaybackType = descriptor.getPlaybackType();
changes |= CHANGE_GENERAL;
}
if (mPlaybackStream != descriptor.getPlaybackStream()) {
mPlaybackStream = descriptor.getPlaybackStream();
changes |= CHANGE_GENERAL;
}
if (mDeviceType != descriptor.getDeviceType()) {
mDeviceType = descriptor.getDeviceType();
changes |= CHANGE_GENERAL;
}
if (mVolumeHandling != descriptor.getVolumeHandling()) {
mVolumeHandling = descriptor.getVolumeHandling();
changes |= CHANGE_GENERAL | CHANGE_VOLUME;
}
if (mVolume != descriptor.getVolume()) {
mVolume = descriptor.getVolume();
changes |= CHANGE_GENERAL | CHANGE_VOLUME;
}
if (mVolumeMax != descriptor.getVolumeMax()) {
mVolumeMax = descriptor.getVolumeMax();
changes |= CHANGE_GENERAL | CHANGE_VOLUME;
}
if (mPresentationDisplayId != descriptor.getPresentationDisplayId()) {
mPresentationDisplayId = descriptor.getPresentationDisplayId();
mPresentationDisplay = null;
changes |= CHANGE_GENERAL | CHANGE_PRESENTATION_DISPLAY;
}
if (!ObjectsCompat.equals(mExtras, descriptor.getExtras())) {
mExtras = descriptor.getExtras();
changes |= CHANGE_GENERAL;
}
if (!ObjectsCompat.equals(mSettingsIntent, descriptor.getSettingsActivity())) {
mSettingsIntent = descriptor.getSettingsActivity();
changes |= CHANGE_GENERAL;
}
if (mCanDisconnect != descriptor.canDisconnectAndKeepPlaying()) {
mCanDisconnect = descriptor.canDisconnectAndKeepPlaying();
changes |= CHANGE_GENERAL | CHANGE_PRESENTATION_DISPLAY;
}
boolean memberChanged = false;
List<String> groupMemberIds = descriptor.getGroupMemberIds();
List<RouteInfo> routes = new ArrayList<>();
if (groupMemberIds.size() != mMemberRoutes.size()) {
memberChanged = true;
}
//TODO: Clean this up not to reference the global router
if (!groupMemberIds.isEmpty()) {
GlobalMediaRouter globalRouter = getGlobalRouter();
for (String groupMemberId : groupMemberIds) {
String uniqueId = globalRouter.getUniqueId(getProvider(), groupMemberId);
RouteInfo groupMember = globalRouter.getRoute(uniqueId);
if (groupMember != null) {
routes.add(groupMember);
if (!memberChanged && !mMemberRoutes.contains(groupMember)) {
memberChanged = true;
}
}
}
}
if (memberChanged) {
mMemberRoutes = routes;
changes |= CHANGE_GENERAL;
}
}
return changes;
}
String getDescriptorId() {
return mDescriptorId;
}
@RestrictTo(LIBRARY)
@NonNull
public MediaRouteProvider getProviderInstance() {
return mProvider.getProviderInstance();
}
void updateDynamicDescriptors(Collection<DynamicRouteDescriptor> dynamicDescriptors) {
mMemberRoutes.clear();
if (mDynamicGroupDescriptors == null) {
mDynamicGroupDescriptors = new ArrayMap<>();
}
mDynamicGroupDescriptors.clear();
for (DynamicRouteDescriptor dynamicDescriptor : dynamicDescriptors) {
RouteInfo route = findRouteByDynamicRouteDescriptor(dynamicDescriptor);
if (route == null) {
continue;
}
mDynamicGroupDescriptors.put(route.mUniqueId, dynamicDescriptor);
if ((dynamicDescriptor.getSelectionState() == DynamicRouteDescriptor.SELECTING)
|| (dynamicDescriptor.getSelectionState()
== DynamicRouteDescriptor.SELECTED)) {
mMemberRoutes.add(route);
}
}
getGlobalRouter().mCallbackHandler.post(
GlobalMediaRouter.CallbackHandler.MSG_ROUTE_CHANGED, this);
}
RouteInfo findRouteByDynamicRouteDescriptor(DynamicRouteDescriptor dynamicDescriptor) {
String descriptorId = dynamicDescriptor.getRouteDescriptor().getId();
return getProvider().findRouteByDescriptorId(descriptorId);
}
/**
* Represents the dynamic group state of the {@link RouteInfo}.
*/
@RestrictTo(LIBRARY)
public static final class DynamicGroupState {
final DynamicRouteDescriptor mDynamicDescriptor;
DynamicGroupState(DynamicRouteDescriptor descriptor) {
mDynamicDescriptor = descriptor;
}
/**
* Gets the selection state of the route when the {@link MediaRouteProvider} of the
* route supports
* {@link MediaRouteProviderDescriptor#supportsDynamicGroupRoute() dynamic group}.
*
* @return The selection state of the route: {@link DynamicRouteDescriptor#UNSELECTED},
* {@link DynamicRouteDescriptor#SELECTING}, or {@link DynamicRouteDescriptor#SELECTED}.
*/
@RestrictTo(LIBRARY)
public int getSelectionState() {
return (mDynamicDescriptor != null) ? mDynamicDescriptor.getSelectionState()
: DynamicRouteDescriptor.UNSELECTED;
}
@RestrictTo(LIBRARY)
public boolean isUnselectable() {
return mDynamicDescriptor == null || mDynamicDescriptor.isUnselectable();
}
@RestrictTo(LIBRARY)
public boolean isGroupable() {
return mDynamicDescriptor != null && mDynamicDescriptor.isGroupable();
}
@RestrictTo(LIBRARY)
public boolean isTransferable() {
return mDynamicDescriptor != null && mDynamicDescriptor.isTransferable();
}
}
}
/**
* Provides information about a media route provider.
* <p>
* This object may be used to determine which media route provider has
* published a particular route.
* </p>
*/
public static final class ProviderInfo {
// Package private fields to avoid use of a synthetic accessor.
final MediaRouteProvider mProviderInstance;
final List<RouteInfo> mRoutes = new ArrayList<>();
final boolean mTreatRouteDescriptorIdsAsUnique;
private final ProviderMetadata mMetadata;
private MediaRouteProviderDescriptor mDescriptor;
ProviderInfo(MediaRouteProvider provider) {
this(provider, /* treatRouteDescriptorIdsAsUnique= */ false);
}
ProviderInfo(MediaRouteProvider provider, boolean treatRouteDescriptorIdsAsUnique) {
mProviderInstance = provider;
mMetadata = provider.getMetadata();
mTreatRouteDescriptorIdsAsUnique = treatRouteDescriptorIdsAsUnique;
}
/**
* Gets the provider's underlying {@link MediaRouteProvider} instance.
*
* <p>Must be called on the main thread.
*/
@NonNull
@MainThread
public MediaRouteProvider getProviderInstance() {
checkCallingThread();
return mProviderInstance;
}
/**
* Gets the package name of the media route provider.
*/
@NonNull
public String getPackageName() {
return mMetadata.getPackageName();
}
/**
* Gets the component name of the media route provider.
*/
@NonNull
public ComponentName getComponentName() {
return mMetadata.getComponentName();
}
/**
* Gets the {@link MediaRouter.RouteInfo routes} published by this route provider.
*
* <p>Must be called on the main thread.
*/
@MainThread
@NonNull
public List<RouteInfo> getRoutes() {
checkCallingThread();
return Collections.unmodifiableList(mRoutes);
}
boolean updateDescriptor(MediaRouteProviderDescriptor descriptor) {
if (mDescriptor != descriptor) {
mDescriptor = descriptor;
return true;
}
return false;
}
int findRouteIndexByDescriptorId(String id) {
final int count = mRoutes.size();
for (int i = 0; i < count; i++) {
if (mRoutes.get(i).mDescriptorId.equals(id)) {
return i;
}
}
return -1;
}
RouteInfo findRouteByDescriptorId(String id) {
for (RouteInfo route : mRoutes) {
if (route.mDescriptorId.equals(id)) {
return route;
}
}
return null;
}
boolean supportsDynamicGroup() {
return mDescriptor != null && mDescriptor.supportsDynamicGroupRoute();
}
@NonNull
@Override
public String toString() {
return "MediaRouter.RouteProviderInfo{ packageName=" + getPackageName() + " }";
}
}
/**
* Interface for receiving events about media routing changes.
* All methods of this interface will be called from the application's main thread.
* <p>
* A Callback will only receive events relevant to routes that the callback
* was registered for unless the {@link MediaRouter#CALLBACK_FLAG_UNFILTERED_EVENTS}
* flag was specified in {@link MediaRouter#addCallback(MediaRouteSelector, Callback, int)}.
* </p>
*
* @see MediaRouter#addCallback(MediaRouteSelector, Callback, int)
* @see MediaRouter#removeCallback(Callback)
*/
public static abstract class Callback {
/**
* Called when the supplied media route becomes selected as the active route.
*
* @param router The media router reporting the event.
* @param route The route that has been selected.
* @deprecated Use {@link #onRouteSelected(MediaRouter, RouteInfo, int)} instead.
*/
@Deprecated
public void onRouteSelected(@NonNull MediaRouter router, @NonNull RouteInfo route) {}
/**
* Called when the supplied media route becomes selected as the active route.
*
* <p>The reason provided will be one of the following:
*
* <ul>
* <li>{@link MediaRouter#UNSELECT_REASON_UNKNOWN}
* <li>{@link MediaRouter#UNSELECT_REASON_DISCONNECTED}
* <li>{@link MediaRouter#UNSELECT_REASON_STOPPED}
* <li>{@link MediaRouter#UNSELECT_REASON_ROUTE_CHANGED}
* </ul>
*
* @param router The media router reporting the event.
* @param route The route that has been selected.
* @param reason The reason for unselecting the previous route.
*/
public void onRouteSelected(
@NonNull MediaRouter router, @NonNull RouteInfo route, @UnselectReason int reason) {
onRouteSelected(router, route);
}
// TODO: Revise the comment when we have a feature that enables dynamic grouping on pre-R
// devices.
/**
* Called when the supplied media route becomes selected as the active route, which may be
* different from the route requested by {@link #selectRoute(RouteInfo)}. That can happen
* when {@link MediaTransferReceiver media transfer feature} is enabled. The default
* implementation calls {@link #onRouteSelected(MediaRouter, RouteInfo, int)} with the
* actually selected route.
*
* @param router The media router reporting the event.
* @param selectedRoute The route that has been selected.
* @param reason The reason for unselecting the previous route.
* @param requestedRoute The route that was requested to be selected.
*/
public void onRouteSelected(
@NonNull MediaRouter router,
@NonNull RouteInfo selectedRoute,
@UnselectReason int reason,
@NonNull RouteInfo requestedRoute) {
onRouteSelected(router, selectedRoute, reason);
}
/**
* Called when the supplied media route becomes unselected as the active route. For detailed
* reason, override {@link #onRouteUnselected(MediaRouter, RouteInfo, int)} instead.
*
* @param router The media router reporting the event.
* @param route The route that has been unselected.
* @deprecated Use {@link #onRouteUnselected(MediaRouter, RouteInfo, int)} instead.
*/
@Deprecated
public void onRouteUnselected(@NonNull MediaRouter router, @NonNull RouteInfo route) {}
/**
* Called when the supplied media route becomes unselected as the active route. The default
* implementation calls {@link #onRouteUnselected}.
*
* <p>The reason provided will be one of the following:
*
* <ul>
* <li>{@link MediaRouter#UNSELECT_REASON_UNKNOWN}
* <li>{@link MediaRouter#UNSELECT_REASON_DISCONNECTED}
* <li>{@link MediaRouter#UNSELECT_REASON_STOPPED}
* <li>{@link MediaRouter#UNSELECT_REASON_ROUTE_CHANGED}
* </ul>
*
* @param router The media router reporting the event.
* @param route The route that has been unselected.
* @param reason The reason for unselecting the route.
*/
public void onRouteUnselected(
@NonNull MediaRouter router, @NonNull RouteInfo route, @UnselectReason int reason) {
onRouteUnselected(router, route);
}
/**
* Called when a media route has been added.
*
* @param router The media router reporting the event.
* @param route The route that has become available for use.
*/
public void onRouteAdded(@NonNull MediaRouter router, @NonNull RouteInfo route) {}
/**
* Called when a media route has been removed.
*
* @param router The media router reporting the event.
* @param route The route that has been removed from availability.
*/
public void onRouteRemoved(@NonNull MediaRouter router, @NonNull RouteInfo route) {}
/**
* Called when a property of the indicated media route has changed.
*
* @param router The media router reporting the event.
* @param route The route that was changed.
*/
public void onRouteChanged(@NonNull MediaRouter router, @NonNull RouteInfo route) {}
/**
* Called when a media route's volume changes.
*
* @param router The media router reporting the event.
* @param route The route whose volume changed.
*/
public void onRouteVolumeChanged(@NonNull MediaRouter router, @NonNull RouteInfo route) {}
/**
* Called when a media route's presentation display changes.
*
* <p>This method is called whenever the route's presentation display becomes available, is
* removed or has changes to some of its properties (such as its size).
*
* @param router The media router reporting the event.
* @param route The route whose presentation display changed.
* @see RouteInfo#getPresentationDisplay()
*/
public void onRoutePresentationDisplayChanged(
@NonNull MediaRouter router, @NonNull RouteInfo route) {}
/**
* Called when a media route provider has been added.
*
* @param router The media router reporting the event.
* @param provider The provider that has become available for use.
*/
public void onProviderAdded(@NonNull MediaRouter router, @NonNull ProviderInfo provider) {}
/**
* Called when a media route provider has been removed.
*
* @param router The media router reporting the event.
* @param provider The provider that has been removed from availability.
*/
public void onProviderRemoved(
@NonNull MediaRouter router, @NonNull ProviderInfo provider) {}
/**
* Called when a property of the indicated media route provider has changed.
*
* @param router The media router reporting the event.
* @param provider The provider that was changed.
*/
public void onProviderChanged(
@NonNull MediaRouter router, @NonNull ProviderInfo provider) {}
/** */
@RestrictTo(LIBRARY)
public void onRouterParamsChanged(
@NonNull MediaRouter router, @Nullable MediaRouterParams params) {}
}
/**
* Listener for receiving events when the selected route is about to be changed.
*
* @see #setOnPrepareTransferListener(OnPrepareTransferListener)
*/
public interface OnPrepareTransferListener {
/**
* Implement this to handle transfer seamlessly.
*
* <p>Setting the listener will defer stopping the previous route, from which you may get
* the media status to resume media seamlessly on the new route. When the transfer is
* prepared, set the returned future to stop media being played on the previous route and
* release resources. This method is called on the main thread.
*
* <p>{@link Callback#onRouteUnselected(MediaRouter, RouteInfo, int)} and {@link
* Callback#onRouteSelected(MediaRouter, RouteInfo, int)} are called after the future is
* done.
*
* @param fromRoute The route that is about to be unselected.
* @param toRoute The route that is about to be selected.
* @return A {@link ListenableFuture} whose completion indicates that the transfer is
* prepared or {@code null} to indicate that no preparation is needed. If a future is
* returned, until the future is completed, the media continues to be played on the
* previous route.
*/
@MainThread
@Nullable
ListenableFuture<Void> onPrepareTransfer(
@NonNull RouteInfo fromRoute, @NonNull RouteInfo toRoute);
}
/**
* Callback which is invoked with the result of a media control request.
*
* @see RouteInfo#sendControlRequest
*/
public static abstract class ControlRequestCallback {
/**
* Called when a media control request succeeds.
*
* @param data Result data, or null if none. Contents depend on the {@link
* MediaControlIntent media control action}.
*/
public void onResult(@Nullable Bundle data) {}
/**
* Called when a media control request fails.
*
* @param error A localized error message which may be shown to the user, or null if the
* cause of the error is unclear.
* @param data Error data, or null if none. Contents depend on the {@link MediaControlIntent
* media control action}.
*/
public void onError(@Nullable String error, @Nullable Bundle data) {}
}
@RestrictTo(LIBRARY_GROUP)
static final class CallbackRecord {
public final MediaRouter mRouter;
public final Callback mCallback;
public MediaRouteSelector mSelector;
public int mFlags;
public long mTimestamp;
public CallbackRecord(MediaRouter router, Callback callback) {
mRouter = router;
mCallback = callback;
mSelector = MediaRouteSelector.EMPTY;
}
public boolean filterRouteEvent(RouteInfo route, int what, RouteInfo optionalRoute,
int reason) {
if ((mFlags & CALLBACK_FLAG_UNFILTERED_EVENTS) != 0
|| route.matchesSelector(mSelector)) {
return true;
}
// In order to notify the app of cast-to-phone event, the onRouteSelected(phone)
// should be called regaredless of the callbakck's control category.
if (isTransferToLocalEnabled() && route.isDefaultOrBluetooth()
&& what == GlobalMediaRouter.CallbackHandler.MSG_ROUTE_SELECTED
&& reason == UNSELECT_REASON_ROUTE_CHANGED
&& optionalRoute != null) {
// Check the previously selected route is remote route.
return !optionalRoute.isDefaultOrBluetooth();
}
return false;
}
}
/**
* Class to notify events about transfer.
*/
static final class PrepareTransferNotifier {
private static final long TRANSFER_TIMEOUT_MS = 15_000;
final RouteController mToRouteController;
final @UnselectReason int mReason;
private final RouteInfo mFromRoute;
final RouteInfo mToRoute;
private final RouteInfo mRequestedRoute;
@Nullable
final List<DynamicRouteDescriptor> mMemberRoutes;
private final WeakReference<GlobalMediaRouter> mRouter;
private ListenableFuture<Void> mFuture = null;
private boolean mFinished = false;
private boolean mCanceled = false;
PrepareTransferNotifier(GlobalMediaRouter router, RouteInfo route,
@Nullable RouteController routeController, @UnselectReason int reason,
@Nullable RouteInfo requestedRoute,
@Nullable Collection<DynamicRouteDescriptor> memberRoutes) {
mRouter = new WeakReference<>(router);
mToRoute = route;
mToRouteController = routeController;
mReason = reason;
mFromRoute = router.mSelectedRoute;
mRequestedRoute = requestedRoute;
mMemberRoutes = (memberRoutes == null) ? null : new ArrayList<>(memberRoutes);
// For the case it's not handled properly
router.mCallbackHandler.postDelayed(this::finishTransfer,
TRANSFER_TIMEOUT_MS);
}
void setFuture(ListenableFuture<Void> future) {
GlobalMediaRouter router = mRouter.get();
if (router == null || router.mTransferNotifier != this) {
Log.w(TAG, "Router is released. Cancel transfer");
cancel();
return;
}
if (mFuture != null) {
throw new IllegalStateException("future is already set");
}
mFuture = future;
future.addListener(this::finishTransfer, router.mCallbackHandler::post);
}
/**
* Notifies that preparation for transfer is finished.
*/
@MainThread
void finishTransfer() {
checkCallingThread();
if (mFinished || mCanceled) {
return;
}
GlobalMediaRouter router = mRouter.get();
if (router == null || router.mTransferNotifier != this
|| (mFuture != null && mFuture.isCancelled())) {
cancel();
return;
}
mFinished = true;
router.mTransferNotifier = null;
unselectFromRouteAndNotify();
selectToRouteAndNotify();
}
void cancel() {
if (mFinished || mCanceled) {
return;
}
mCanceled = true;
if (mToRouteController != null) {
mToRouteController.onUnselect(UNSELECT_REASON_UNKNOWN);
mToRouteController.onRelease();
}
}
private void unselectFromRouteAndNotify() {
GlobalMediaRouter router = mRouter.get();
if (router == null || router.mSelectedRoute != mFromRoute) {
return;
}
router.mCallbackHandler.post(GlobalMediaRouter.CallbackHandler.MSG_ROUTE_UNSELECTED,
mFromRoute, mReason);
if (router.mSelectedRouteController != null) {
router.mSelectedRouteController.onUnselect(mReason);
router.mSelectedRouteController.onRelease();
}
// Release member route controllers
if (!router.mRouteControllerMap.isEmpty()) {
for (RouteController controller : router.mRouteControllerMap.values()) {
controller.onUnselect(mReason);
controller.onRelease();
}
router.mRouteControllerMap.clear();
}
router.mSelectedRouteController = null;
}
private void selectToRouteAndNotify() {
GlobalMediaRouter router = mRouter.get();
if (router == null) {
return;
}
router.mSelectedRoute = mToRoute;
router.mSelectedRouteController = mToRouteController;
if (mRequestedRoute == null) {
router.mCallbackHandler.post(GlobalMediaRouter.CallbackHandler.MSG_ROUTE_SELECTED,
new Pair<>(mFromRoute, mToRoute), mReason);
} else {
router.mCallbackHandler.post(
GlobalMediaRouter.CallbackHandler.MSG_ROUTE_ANOTHER_SELECTED,
new Pair<>(mRequestedRoute, mToRoute), mReason);
}
router.mRouteControllerMap.clear();
router.maybeUpdateMemberRouteControllers();
router.updatePlaybackInfoFromSelectedRoute();
if (mMemberRoutes != null) {
router.mSelectedRoute.updateDynamicDescriptors(mMemberRoutes);
}
}
}
}