Api updates to MediaSession components

-renames get/setBufferPosition to get/setBufferedPosition
-renames getLaunchActivity to getSessionActivity
-adds doc link to setVolumeTo flags param
-renames setLaunchActivity to setSessionActivity
-hides setMediaRouter
-moves PLAYBACK_TYPE_ constants to MediaController.AudioInfo
-adds addOnActiveSessionsChangedListener version with a handler parameter
-renames AudioInfo to PlaybackInfo

bug:17114404
Change-Id: I0fbfe4eb979cb2af98e3f13095c654bb131f7ae5

5 files changed, 74 insertions, 51 deletions

diff --git a/media/java/android/media/session/MediaController.java b/media/java/android/media/session/MediaController.java
index 2ec0293..d7baaa9 100644
--- a/media/java/android/media/session/MediaController.java
+++ b/media/java/android/media/session/MediaController.java
@@ -247,14 +247,14 @@ public final class MediaController {
     }
 
     /**
-     * Get the current audio info for this session.
+     * Get the current playback info for this session.
      *
-     * @return The current audio info or null.
+     * @return The current playback info or null.
      */
-    public @Nullable AudioInfo getAudioInfo() {
+    public @Nullable PlaybackInfo getPlaybackInfo() {
         try {
             ParcelableVolumeInfo result = mSessionBinder.getVolumeAttributes();
-            return new AudioInfo(result.volumeType, result.audioAttrs, result.controlType,
+            return new PlaybackInfo(result.volumeType, result.audioAttrs, result.controlType,
                     result.maxVolume, result.currentVolume);
 
         } catch (RemoteException e) {
@@ -269,7 +269,7 @@ public final class MediaController {
      *
      * @return A {@link PendingIntent} to launch UI or null.
      */
-    public @Nullable PendingIntent getLaunchActivity() {
+    public @Nullable PendingIntent getSessionActivity() {
         try {
             return mSessionBinder.getLaunchPendingIntent();
         } catch (RemoteException e) {
@@ -293,9 +293,10 @@ public final class MediaController {
      * {@link VolumeProvider#VOLUME_CONTROL_ABSOLUTE}. The flags in
      * {@link AudioManager} may be used to affect the handling.
      *
-     * @see #getAudioInfo()
+     * @see #getPlaybackInfo()
      * @param value The value to set it to, between 0 and the reported max.
-     * @param flags Any flags to pass with the command.
+     * @param flags Flags from {@link AudioManager} to include with the volume
+     *            request.
      */
     public void setVolumeTo(int value, int flags) {
         try {
@@ -314,7 +315,7 @@ public final class MediaController {
      * {@link VolumeProvider#VOLUME_CONTROL_ABSOLUTE}. The flags in
      * {@link AudioManager} may be used to affect the handling.
      *
-     * @see #getAudioInfo()
+     * @see #getPlaybackInfo()
      * @param direction The direction to adjust the volume in.
      * @param flags Any flags to pass with the command.
      */
@@ -565,7 +566,7 @@ public final class MediaController {
          *
          * @param info The current audio info for this session.
          */
-        public void onAudioInfoChanged(AudioInfo info) {
+        public void onAudioInfoChanged(PlaybackInfo info) {
         }
     }
 
@@ -773,9 +774,19 @@ public final class MediaController {
     }
 
     /**
-     * Holds information about the way audio is handled for this session.
+     * Holds information about the current playback and how audio is handled for
+     * this session.
      */
-    public static final class AudioInfo {
+    public static final class PlaybackInfo {
+        /**
+         * The session uses remote playback.
+         */
+        public static final int PLAYBACK_TYPE_REMOTE = 2;
+        /**
+         * The session uses local playback.
+         */
+        public static final int PLAYBACK_TYPE_LOCAL = 1;
+
         private final int mVolumeType;
         private final int mVolumeControl;
         private final int mMaxVolume;
@@ -785,7 +796,7 @@ public final class MediaController {
         /**
          * @hide
          */
-        public AudioInfo(int type, AudioAttributes attrs, int control, int max, int current) {
+        public PlaybackInfo(int type, AudioAttributes attrs, int control, int max, int current) {
             mVolumeType = type;
             mAudioAttrs = attrs;
             mVolumeControl = control;
@@ -794,22 +805,22 @@ public final class MediaController {
         }
 
         /**
-         * Get the type of volume handling, either local or remote. One of:
+         * Get the type of playback which affects volume handling. One of:
          * <ul>
-         * <li>{@link MediaSession#PLAYBACK_TYPE_LOCAL}</li>
-         * <li>{@link MediaSession#PLAYBACK_TYPE_REMOTE}</li>
+         * <li>{@link #PLAYBACK_TYPE_LOCAL}</li>
+         * <li>{@link #PLAYBACK_TYPE_REMOTE}</li>
          * </ul>
          *
-         * @return The type of volume handling this session is using.
+         * @return The type of playback this session is using.
          */
-        public int getVolumeType() {
+        public int getPlaybackType() {
             return mVolumeType;
         }
 
         /**
          * Get the audio attributes for this session. The attributes will affect
          * volume handling for the session. When the volume type is
-         * {@link MediaSession#PLAYBACK_TYPE_REMOTE} these may be ignored by the
+         * {@link PlaybackInfo#PLAYBACK_TYPE_REMOTE} these may be ignored by the
          * remote volume handler.
          *
          * @return The attributes for this session.
@@ -920,7 +931,7 @@ public final class MediaController {
         public void onVolumeInfoChanged(ParcelableVolumeInfo pvi) {
             MediaController controller = mController.get();
             if (controller != null) {
-                AudioInfo info = new AudioInfo(pvi.volumeType, pvi.audioAttrs, pvi.controlType,
+                PlaybackInfo info = new PlaybackInfo(pvi.volumeType, pvi.audioAttrs, pvi.controlType,
                         pvi.maxVolume, pvi.currentVolume);
                 controller.postMessage(MSG_UPDATE_VOLUME, info, null);
             }
@@ -958,7 +969,7 @@ public final class MediaController {
                     mCallback.onExtrasChanged((Bundle) msg.obj);
                     break;
                 case MSG_UPDATE_VOLUME:
-                    mCallback.onAudioInfoChanged((AudioInfo) msg.obj);
+                    mCallback.onAudioInfoChanged((PlaybackInfo) msg.obj);
                     break;
                 case MSG_DESTROYED:
                     mCallback.onSessionDestroyed();
diff --git a/media/java/android/media/session/MediaSession.java b/media/java/android/media/session/MediaSession.java
index de725fc..eac6809 100644
--- a/media/java/android/media/session/MediaSession.java
+++ b/media/java/android/media/session/MediaSession.java
@@ -101,16 +101,6 @@ public final class MediaSession {
             FLAG_EXCLUSIVE_GLOBAL_PRIORITY })
     public @interface SessionFlags { }
 
-    /**
-     * The session uses local playback.
-     */
-    public static final int PLAYBACK_TYPE_LOCAL = 1;
-
-    /**
-     * The session uses remote playback.
-     */
-    public static final int PLAYBACK_TYPE_REMOTE = 2;
-
     private final Object mLock = new Object();
 
     private final MediaSession.Token mSessionToken;
@@ -215,7 +205,7 @@ public final class MediaSession {
      *
      * @param pi The intent to launch to show UI for this Session.
      */
-    public void setLaunchActivity(@Nullable PendingIntent pi) {
+    public void setSessionActivity(@Nullable PendingIntent pi) {
         try {
             mBinder.setLaunchPendingIntent(pi);
         } catch (RemoteException e) {
diff --git a/media/java/android/media/session/MediaSessionManager.java b/media/java/android/media/session/MediaSessionManager.java
index 8a1e076..185c6d8 100644
--- a/media/java/android/media/session/MediaSessionManager.java
+++ b/media/java/android/media/session/MediaSessionManager.java
@@ -148,8 +148,29 @@ public final class MediaSessionManager {
     public void addOnActiveSessionsChangedListener(
             @NonNull OnActiveSessionsChangedListener sessionListener,
             @Nullable ComponentName notificationListener) {
+        addOnActiveSessionsChangedListener(sessionListener, notificationListener, null);
+    }
+
+    /**
+     * Add a listener to be notified when the list of active sessions
+     * changes.This requires the
+     * android.Manifest.permission.MEDIA_CONTENT_CONTROL permission be held by
+     * the calling app. You may also retrieve this list if your app is an
+     * enabled notification listener using the
+     * {@link NotificationListenerService} APIs, in which case you must pass the
+     * {@link ComponentName} of your enabled listener. Updates will be posted to
+     * the handler specified or to the caller's thread if the handler is null.
+     *
+     * @param sessionListener The listener to add.
+     * @param notificationListener The enabled notification listener component.
+     *            May be null.
+     * @param handler The handler to post events to.
+     */
+    public void addOnActiveSessionsChangedListener(
+            @NonNull OnActiveSessionsChangedListener sessionListener,
+            @Nullable ComponentName notificationListener, @Nullable Handler handler) {
         addOnActiveSessionsChangedListener(sessionListener, notificationListener,
-                UserHandle.myUserId(), null);
+                UserHandle.myUserId(), handler);
     }
 
     /**
diff --git a/media/java/android/media/session/ParcelableVolumeInfo.java b/media/java/android/media/session/ParcelableVolumeInfo.java
index 96a45d9b..f59c975 100644
--- a/media/java/android/media/session/ParcelableVolumeInfo.java
+++ b/media/java/android/media/session/ParcelableVolumeInfo.java
@@ -21,7 +21,7 @@ import android.os.Parcelable;
 
 /**
  * Convenience class for passing information about the audio configuration of a
- * session. The public implementation is {@link MediaController.AudioInfo}.
+ * session. The public implementation is {@link MediaController.PlaybackInfo}.
  *
  * @hide
  */
diff --git a/media/java/android/media/session/PlaybackState.java b/media/java/android/media/session/PlaybackState.java
index 566e218..2ca97dd 100644
--- a/media/java/android/media/session/PlaybackState.java
+++ b/media/java/android/media/session/PlaybackState.java
@@ -217,7 +217,7 @@ public final class PlaybackState implements Parcelable {
 
     private final int mState;
     private final long mPosition;
-    private final long mBufferPosition;
+    private final long mBufferedPosition;
     private final float mSpeed;
     private final long mActions;
     private List<PlaybackState.CustomAction> mCustomActions;
@@ -226,14 +226,14 @@ public final class PlaybackState implements Parcelable {
     private final long mActiveItemId;
 
     private PlaybackState(int state, long position, long updateTime, float speed,
-            long bufferPosition, long transportControls,
+            long bufferedPosition, long transportControls,
             List<PlaybackState.CustomAction> customActions, long activeItemId,
             CharSequence error) {
         mState = state;
         mPosition = position;
         mSpeed = speed;
         mUpdateTime = updateTime;
-        mBufferPosition = bufferPosition;
+        mBufferedPosition = bufferedPosition;
         mActions = transportControls;
         mCustomActions = new ArrayList<>(customActions);
         mActiveItemId = activeItemId;
@@ -245,7 +245,7 @@ public final class PlaybackState implements Parcelable {
         mPosition = in.readLong();
         mSpeed = in.readFloat();
         mUpdateTime = in.readLong();
-        mBufferPosition = in.readLong();
+        mBufferedPosition = in.readLong();
         mActions = in.readLong();
         mCustomActions = in.createTypedArrayList(CustomAction.CREATOR);
         mActiveItemId = in.readLong();
@@ -258,7 +258,7 @@ public final class PlaybackState implements Parcelable {
         StringBuilder bob = new StringBuilder("PlaybackState {");
         bob.append("state=").append(mState);
         bob.append(", position=").append(mPosition);
-        bob.append(", buffered position=").append(mBufferPosition);
+        bob.append(", buffered position=").append(mBufferedPosition);
         bob.append(", speed=").append(mSpeed);
         bob.append(", updated=").append(mUpdateTime);
         bob.append(", actions=").append(mActions);
@@ -280,7 +280,7 @@ public final class PlaybackState implements Parcelable {
         dest.writeLong(mPosition);
         dest.writeFloat(mSpeed);
         dest.writeLong(mUpdateTime);
-        dest.writeLong(mBufferPosition);
+        dest.writeLong(mBufferedPosition);
         dest.writeLong(mActions);
         dest.writeTypedList(mCustomActions);
         dest.writeLong(mActiveItemId);
@@ -310,12 +310,12 @@ public final class PlaybackState implements Parcelable {
     }
 
     /**
-     * Get the current buffer position in ms. This is the farthest playback
+     * Get the current buffered position in ms. This is the farthest playback
      * point that can be reached from the current position using only buffered
      * content.
      */
-    public long getBufferPosition() {
-        return mBufferPosition;
+    public long getBufferedPosition() {
+        return mBufferedPosition;
     }
 
     /**
@@ -711,7 +711,7 @@ public final class PlaybackState implements Parcelable {
 
         private int mState;
         private long mPosition;
-        private long mBufferPosition;
+        private long mBufferedPosition;
         private float mSpeed;
         private long mActions;
         private CharSequence mErrorMessage;
@@ -736,7 +736,7 @@ public final class PlaybackState implements Parcelable {
             }
             mState = from.mState;
             mPosition = from.mPosition;
-            mBufferPosition = from.mBufferPosition;
+            mBufferedPosition = from.mBufferedPosition;
             mSpeed = from.mSpeed;
             mActions = from.mActions;
             if (from.mCustomActions != null) {
@@ -889,15 +889,16 @@ public final class PlaybackState implements Parcelable {
         }
 
         /**
-         * Set the current buffer position in ms. This is the farthest playback
-         * point that can be reached from the current position using only
-         * buffered content.
+         * Set the current buffered position in ms. This is the farthest
+         * playback point that can be reached from the current position using
+         * only buffered content.
          *
-         * @param bufferPosition The position in ms that playback is buffered to.
+         * @param bufferedPosition The position in ms that playback is buffered
+         *            to.
          * @return this
          */
-        public Builder setBufferPosition(long bufferPosition) {
-            mBufferPosition = bufferPosition;
+        public Builder setBufferedPosition(long bufferedPosition) {
+            mBufferedPosition = bufferedPosition;
             return this;
         }
 
@@ -931,7 +932,7 @@ public final class PlaybackState implements Parcelable {
          * @return A new state instance.
          */
         public PlaybackState build() {
-            return new PlaybackState(mState, mPosition, mUpdateTime, mSpeed, mBufferPosition,
+            return new PlaybackState(mState, mPosition, mUpdateTime, mSpeed, mBufferedPosition,
                     mActions, mCustomActions, mActiveItemId, mErrorMessage);
         }
     }