Merge "Add MediaRouter2#stop" into rvc-dev

api/current.txt

@@ -27053,7 +27053,8 @@ package android.media {
     method public void registerRouteCallback(@NonNull java.util.concurrent.Executor, @NonNull android.media.MediaRouter2.RouteCallback, @NonNull android.media.RouteDiscoveryPreference);
     method public void registerTransferCallback(@NonNull java.util.concurrent.Executor, @NonNull android.media.MediaRouter2.TransferCallback);
     method public void setOnGetControllerHintsListener(@Nullable android.media.MediaRouter2.OnGetControllerHintsListener);
-    method public void transferTo(@Nullable android.media.MediaRoute2Info);
+    method public void stop();
+    method public void transferTo(@NonNull android.media.MediaRoute2Info);
     method public void unregisterControllerCallback(@NonNull android.media.MediaRouter2.ControllerCallback);
     method public void unregisterRouteCallback(@NonNull android.media.MediaRouter2.RouteCallback);
     method public void unregisterTransferCallback(@NonNull android.media.MediaRouter2.TransferCallback);
@@ -27093,8 +27094,9 @@ package android.media {
 
   public abstract static class MediaRouter2.TransferCallback {
     ctor public MediaRouter2.TransferCallback();
+    method public void onStopped(@NonNull android.media.MediaRouter2.RoutingController);
     method public void onTransferFailed(@NonNull android.media.MediaRoute2Info);
-    method public void onTransferred(@NonNull android.media.MediaRouter2.RoutingController, @Nullable android.media.MediaRouter2.RoutingController);
+    method public void onTransferred(@NonNull android.media.MediaRouter2.RoutingController, @NonNull android.media.MediaRouter2.RoutingController);
   }
 
   public class MediaScannerConnection implements android.content.ServiceConnection {

media/java/android/media/MediaRouter2.java

@@ -377,27 +377,35 @@ public class MediaRouter2 {
      * @see TransferCallback#onTransferred
      * @see TransferCallback#onTransferFailed
      */
-    public void transferTo(@Nullable MediaRoute2Info route) {
+    public void transferTo(@NonNull MediaRoute2Info route) {
+        Objects.requireNonNull(route, "route must not be null");
+
         List<RoutingController> controllers = getControllers();
         RoutingController controller = controllers.get(controllers.size() - 1);
 
         transfer(controller, route);
     }
 
+    /**
+     * Stops the current media routing. If the {@link #getSystemController() system controller}
+     * controls the media routing, this method is a no-op.
+     */
+    public void stop() {
+        List<RoutingController> controllers = getControllers();
+        RoutingController controller = controllers.get(controllers.size() - 1);
+
+        controller.release();
+    }
+
     /**
      * Transfers the media of a routing controller to the given route.
      * @param controller a routing controller controlling media routing.
-     * @param route the route you want to transfer the media to. Pass {@code null} to stop
+     * @param route the route you want to transfer the media to.
-     *              routing controlled by the given controller.
      * @hide
      */
-    void transfer(@NonNull RoutingController controller, @Nullable MediaRoute2Info route) {
+    void transfer(@NonNull RoutingController controller, @NonNull MediaRoute2Info route) {
         Objects.requireNonNull(controller, "controller must not be null");
-
+        Objects.requireNonNull(route, "route must not be null");
-        if (route == null) {
-            controller.release();
-            return;
-        }
 
         // TODO: Check thread-safety
         if (!mRoutes.containsKey(route.getId())) {
@@ -681,7 +689,7 @@ public class MediaRouter2 {
 
         if (removed) {
             matchingController.release();
-            notifyControllerReleased(matchingController);
+            notifyStopped(matchingController);
         }
     }
 
@@ -738,16 +746,16 @@ public class MediaRouter2 {
         }
     }
 
-    private void notifyControllerUpdated(RoutingController controller) {
+    private void notifyStopped(RoutingController controller) {
-        for (ControllerCallbackRecord record: mControllerCallbackRecords) {
+        for (TransferCallbackRecord record: mTransferCallbackRecords) {
-            record.mExecutor.execute(() -> record.mCallback.onControllerUpdated(controller));
+            record.mExecutor.execute(
+                    () -> record.mTransferCallback.onStopped(controller));
         }
     }
 
-    private void notifyControllerReleased(RoutingController controller) {
+    private void notifyControllerUpdated(RoutingController controller) {
-        for (TransferCallbackRecord record: mTransferCallbackRecords) {
+        for (ControllerCallbackRecord record: mControllerCallbackRecords) {
-            record.mExecutor.execute(
+            record.mExecutor.execute(() -> record.mCallback.onControllerUpdated(controller));
-                    () -> record.mTransferCallback.onTransferred(controller, null));
         }
     }
 
@@ -788,20 +796,26 @@ public class MediaRouter2 {
          * This can happen by calling {@link #transferTo(MediaRoute2Info)} or
          * {@link RoutingController#release()}.
          *
-         * @param oldController the previous controller that controlled routing.
+         * @param oldController the previous controller that controlled routing
-         * @param newController the new controller to control routing or {@code null} if the
+         * @param newController the new controller to control routing
-         *                      previous controller is released.
          * @see #transferTo(MediaRoute2Info)
          */
         public void onTransferred(@NonNull RoutingController oldController,
-                @Nullable RoutingController newController) {}
+                @NonNull RoutingController newController) {}
 
         /**
          * Called when {@link #transferTo(MediaRoute2Info)} failed.
          *
-         * @param requestedRoute the route info which was used for the transfer.
+         * @param requestedRoute the route info which was used for the transfer
          */
         public void onTransferFailed(@NonNull MediaRoute2Info requestedRoute) {}
+
+        /**
+         * Called when a media routing stops. It can be stopped by a user or a provider.
+         *
+         * @param controller the controller that controlled the stopped media routing.
+         */
+        public void onStopped(@NonNull RoutingController controller) { }
     }
 
     /**
@@ -1186,7 +1200,7 @@ public class MediaRouter2 {
             }
 
             if (removed) {
-                mHandler.post(() -> notifyControllerReleased(RoutingController.this));
+                mHandler.post(() -> notifyStopped(RoutingController.this));
             }
 
             if (stub != null) {