Merge "MediaRouter: Address API review issues"

api/current.txt

@@ -26704,7 +26704,6 @@ package android.media {
     method public int getVolume();
     method public int getVolumeHandling();
     method public int getVolumeMax();
-    method public boolean hasAnyFeatures(@NonNull java.util.Collection<java.lang.String>);
     method public void writeToParcel(@NonNull android.os.Parcel, int);
     field public static final int CONNECTION_STATE_CONNECTED = 2; // 0x2
     field public static final int CONNECTION_STATE_CONNECTING = 1; // 0x1

media/java/android/media/MediaRoute2Info.java

@@ -79,6 +79,11 @@ public final class MediaRoute2Info implements Parcelable {
      */
     public static final int CONNECTION_STATE_CONNECTED = 2;
 
+    /** @hide */
+    @IntDef({PLAYBACK_VOLUME_FIXED, PLAYBACK_VOLUME_VARIABLE})
+    @Retention(RetentionPolicy.SOURCE)
+    public @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,
@@ -326,6 +331,7 @@ public final class MediaRoute2Info implements Parcelable {
      *
      * @return {@link #PLAYBACK_VOLUME_FIXED} or {@link #PLAYBACK_VOLUME_VARIABLE}
      */
+    @PlaybackVolume
     public int getVolumeHandling() {
         return mVolumeHandling;
     }
@@ -375,6 +381,7 @@ public final class MediaRoute2Info implements Parcelable {
      *
      * @param features the list of route features to consider
      * @return true if the route has at least one feature in the list
+     * @hide
      */
     public boolean hasAnyFeatures(@NonNull Collection<String> features) {
         Objects.requireNonNull(features, "features must not be null");
@@ -548,6 +555,12 @@ public final class MediaRoute2Info implements Parcelable {
 
         /**
          * Adds a feature for the route.
+         * @param feature a feature that the route has. May be one of predefined features
+         *                such as {@link #FEATURE_LIVE_AUDIO}, {@link #FEATURE_LIVE_VIDEO} or
+         *                {@link #FEATURE_REMOTE_PLAYBACK} or a custom feature defined by
+         *                a provider.
+         *
+         * @see #addFeatures(Collection)
          */
         @NonNull
         public Builder addFeature(@NonNull String feature) {
@@ -560,6 +573,12 @@ public final class MediaRoute2Info implements Parcelable {
 
         /**
          * Adds features for the route. A route must support at least one route type.
+         * @param features features that the route has. May include predefined features
+         *                such as {@link #FEATURE_LIVE_AUDIO}, {@link #FEATURE_LIVE_VIDEO} or
+         *                {@link #FEATURE_REMOTE_PLAYBACK} or custom features defined by
+         *                a provider.
+         *
+         * @see #addFeature(String)
          */
         @NonNull
         public Builder addFeatures(@NonNull Collection<String> features) {
@@ -643,7 +662,7 @@ public final class MediaRoute2Info implements Parcelable {
          * Sets the route's volume handling.
          */
         @NonNull
-        public Builder setVolumeHandling(int volumeHandling) {
+        public Builder setVolumeHandling(@PlaybackVolume int volumeHandling) {
             mVolumeHandling = volumeHandling;
             return this;
         }

media/java/android/media/MediaRoute2ProviderService.java

@@ -21,6 +21,7 @@ import static com.android.internal.util.function.pooled.PooledLambda.obtainMessa
 import android.annotation.CallSuper;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
+import android.annotation.SdkConstant;
 import android.app.Service;
 import android.content.Intent;
 import android.os.Binder;
@@ -57,6 +58,11 @@ import java.util.concurrent.atomic.AtomicBoolean;
 public abstract class MediaRoute2ProviderService extends Service {
     private static final String TAG = "MR2ProviderService";
 
+    /**
+     * The {@link Intent} action that must be declared as handled by the service.
+     * Put this in your manifest to provide media routes.
+     */
+    @SdkConstant(SdkConstant.SdkConstantType.SERVICE_ACTION)
     public static final String SERVICE_INTERFACE = "android.media.MediaRoute2ProviderService";
 
     /**

media/java/android/media/MediaRouter2.java

@@ -49,10 +49,10 @@ import java.util.stream.Collectors;
 /**
  * Media Router 2 allows applications to control the routing of media channels
  * and streams from the current device to remote speakers and devices.
- *
  */
 // TODO: Add method names at the beginning of log messages. (e.g. updateControllerOnHandler)
 //       Not only MediaRouter2, but also to service / manager / provider.
+// TODO: ensure thread-safe and document it
 public class MediaRouter2 {
     private static final String TAG = "MR2";
     private static final boolean DEBUG = Log.isLoggable(TAG, Log.DEBUG);
@@ -159,7 +159,8 @@ public class MediaRouter2 {
     /**
      * Registers a callback to discover routes and to receive events when they change.
      * <p>
-     * If you register the same callback twice or more, it will be ignored.
+     * If the specified callback is already registered, its registration will be updated for the
+     * given {@link Executor executor} and {@link RouteDiscoveryPreference discovery preference}.
      * </p>
      */
     public void registerRouteCallback(@NonNull @CallbackExecutor Executor executor,
@@ -170,10 +171,11 @@ public class MediaRouter2 {
         Objects.requireNonNull(preference, "preference must not be null");
 
         RouteCallbackRecord record = new RouteCallbackRecord(executor, routeCallback, preference);
-        if (!mRouteCallbackRecords.addIfAbsent(record)) {
-            Log.w(TAG, "Ignoring the same callback");
-            return;
-        }
+
+        mRouteCallbackRecords.remove(record);
+        // It can fail to add the callback record if another registration with the same callback
+        // is happening but it's okay because either this or the other registration should be done.
+        mRouteCallbackRecords.addIfAbsent(record);
 
         synchronized (sRouterLock) {
             if (mClient == null) {