diff options
| -rw-r--r-- | media/java/android/media/MediaRouter2.java | 22 | ||||
| -rw-r--r-- | media/java/android/media/RoutingSessionInfo.java | 52 |
2 files changed, 65 insertions, 9 deletions
diff --git a/media/java/android/media/MediaRouter2.java b/media/java/android/media/MediaRouter2.java index 3499c438086d..20108e7369d7 100644 --- a/media/java/android/media/MediaRouter2.java +++ b/media/java/android/media/MediaRouter2.java @@ -1771,10 +1771,12 @@ public final class MediaRouter2 { } /** - * A class to control media routing session in media route provider. For example, - * selecting/deselecting/transferring to routes of a session can be done through this. Instances - * are created when {@link TransferCallback#onTransfer(RoutingController, RoutingController)} is - * called, which is invoked after {@link #transferTo(MediaRoute2Info)} is called. + * Controls a media routing session. + * + * <p>Routing controllers wrap a {@link RoutingSessionInfo}, taking care of mapping route ids to + * {@link MediaRoute2Info} instances. You can still access the underlying session using {@link + * #getRoutingSessionInfo()}, but keep in mind it can be changed by other threads. Changes to + * the routing session are notified via {@link ControllerCallback}. */ public class RoutingController { private final Object mControllerLock = new Object(); @@ -1836,7 +1838,9 @@ public final class MediaRouter2 { } /** - * @return the unmodifiable list of currently selected routes + * Returns the unmodifiable list of currently selected routes + * + * @see RoutingSessionInfo#getSelectedRoutes() */ @NonNull public List<MediaRoute2Info> getSelectedRoutes() { @@ -1848,7 +1852,9 @@ public final class MediaRouter2 { } /** - * @return the unmodifiable list of selectable routes for the session. + * Returns the unmodifiable list of selectable routes for the session. + * + * @see RoutingSessionInfo#getSelectableRoutes() */ @NonNull public List<MediaRoute2Info> getSelectableRoutes() { @@ -1860,7 +1866,9 @@ public final class MediaRouter2 { } /** - * @return the unmodifiable list of deselectable routes for the session. + * Returns the unmodifiable list of deselectable routes for the session. + * + * @see RoutingSessionInfo#getDeselectableRoutes() */ @NonNull public List<MediaRoute2Info> getDeselectableRoutes() { diff --git a/media/java/android/media/RoutingSessionInfo.java b/media/java/android/media/RoutingSessionInfo.java index 83a4dd5a682a..3b8cf3fb2909 100644 --- a/media/java/android/media/RoutingSessionInfo.java +++ b/media/java/android/media/RoutingSessionInfo.java @@ -262,7 +262,8 @@ public final class RoutingSessionInfo implements Parcelable { } /** - * Gets the provider id of the session. + * Gets the provider ID of the session. + * * @hide */ @Nullable @@ -271,7 +272,15 @@ public final class RoutingSessionInfo implements Parcelable { } /** - * Gets the list of IDs of selected routes for the session. It shouldn't be empty. + * Gets the list of IDs of selected routes for the session. + * + * <p>Selected routes are the routes that this session is actively routing media to. + * + * <p>The behavior of a routing session with multiple selected routes is ultimately defined by + * the {@link MediaRoute2ProviderService} implementation. However, typically, it's expected that + * all the selected routes of a routing session are playing the same media in sync. + * + * @return A non-empty list of selected route ids. */ @NonNull public List<String> getSelectedRoutes() { @@ -280,6 +289,16 @@ public final class RoutingSessionInfo implements Parcelable { /** * Gets the list of IDs of selectable routes for the session. + * + * <p>Selectable routes can be added to a routing session (via {@link + * MediaRouter2.RoutingController#selectRoute}) in order to add them to the {@link + * #getSelectedRoutes() selected routes}, so that media plays on the newly selected route along + * with the other selected routes. + * + * <p>Not to be confused with {@link #getTransferableRoutes() transferable routes}. Transferring + * to a route makes it the sole selected route. + * + * @return A possibly empty list of selectable route ids. */ @NonNull public List<String> getSelectableRoutes() { @@ -288,6 +307,17 @@ public final class RoutingSessionInfo implements Parcelable { /** * Gets the list of IDs of deselectable routes for the session. + * + * <p>Deselectable routes can be removed from the {@link #getSelectedRoutes() selected routes}, + * so that the routing session stops routing to the newly deselected route, but continues on any + * remaining selected routes. + * + * <p>Deselectable routes should be a subset of the {@link #getSelectedRoutes() selected + * routes}, meaning not all of the selected routes might be deselectable. For example, one of + * the selected routes may be a leader device coordinating group playback, which must always + * remain selected while the session is active. + * + * @return A possibly empty list of deselectable route ids. */ @NonNull public List<String> getDeselectableRoutes() { @@ -296,6 +326,24 @@ public final class RoutingSessionInfo implements Parcelable { /** * Gets the list of IDs of transferable routes for the session. + * + * <p>Transferring to a route (for example, using {@link MediaRouter2#transferTo}) replaces the + * list of {@link #getSelectedRoutes() selected routes} with the target route, causing playback + * to move from one route to another. + * + * <p>Note that this is different from {@link #getSelectableRoutes() selectable routes}, because + * selecting a route makes it part of the selected routes, while transferring to a route makes + * it the selected route. A route can be both transferable and selectable. + * + * <p>Note that playback may transfer across routes without the target route being in the list + * of transferable routes. This can happen by creating a new routing session to the target + * route, and releasing the routing session being transferred from. The difference is that a + * transfer to a route in the transferable list can happen with no intervention from the app, + * with the route provider taking care of the entire operation. A transfer to a route that is + * not in the list of transferable routes (by creating a new session) requires the app to move + * the playback state from one device to the other. + * + * @return A possibly empty list of transferable route ids. */ @NonNull public List<String> getTransferableRoutes() { |