Merge changes I12774def,I45bbf1ed into main

* changes:
  Add aconfig flag to enable mirroring routes in MR2
  Tweak javadocs for selectable and transferable routes

3 files changed, 72 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() {
diff --git a/media/java/android/media/flags/media_better_together.aconfig b/media/java/android/media/flags/media_better_together.aconfig
index ba2398c12607..7895eb27b372 100644
--- a/media/java/android/media/flags/media_better_together.aconfig
+++ b/media/java/android/media/flags/media_better_together.aconfig
@@ -166,3 +166,10 @@ flag {
     description: "Allows audio input devices routing and volume control via system settings."
     bug: "355684672"
 }
+
+flag {
+    name: "enable_mirroring_in_media_router_2"
+    namespace: "media_better_together"
+    description: "Enables support for mirroring routes in the MediaRouter2 framework, allowing Output Switcher to offer mirroring routes."
+    bug: "362507305"
+}