Merge "Add stream/volume apis to sessions"

api/current.txt

@@ -15746,6 +15746,9 @@ package android.media.session {
     method public void sendEvent(java.lang.String, android.os.Bundle);
     method public void setActive(boolean);
     method public void setFlags(int);
+    method public void setLaunchPendingIntent(android.app.PendingIntent);
+    method public void useLocalPlayback(android.media.AudioAttributes);
+    method public void useRemotePlayback(android.media.session.RemoteVolumeProvider);
     field public static final int FLAG_HANDLES_MEDIA_BUTTONS = 1; // 0x1
     field public static final int FLAG_HANDLES_TRANSPORT_CONTROLS = 2; // 0x2
   }
@@ -15814,6 +15817,18 @@ package android.media.session {
     field public static final int PLAYSTATE_STOPPED = 1; // 0x1
   }
 
+  public abstract class RemoteVolumeProvider {
+    ctor public RemoteVolumeProvider(int, int);
+    method public abstract int getCurrentVolume();
+    method public final int getFlags();
+    method public final int getMaxVolume();
+    method public final void notifyVolumeChanged();
+    method public void onAdjustVolume(int);
+    method public void onSetVolume(int);
+    field public static final int FLAG_VOLUME_ABSOLUTE = 2; // 0x2
+    field public static final int FLAG_VOLUME_RELATIVE = 1; // 0x1
+  }
+
   public final class TransportController {
     method public void addStateListener(android.media.session.TransportController.TransportStateListener);
     method public void addStateListener(android.media.session.TransportController.TransportStateListener, android.os.Handler);

media/java/android/media/session/MediaSession.java

@@ -16,7 +16,10 @@
 
 package android.media.session;
 
+import android.app.PendingIntent;
 import android.content.Intent;
+import android.media.AudioAttributes;
+import android.media.AudioManager;
 import android.media.Rating;
 import android.media.session.ISessionController;
 import android.media.session.ISession;
@@ -89,6 +92,7 @@ public final class MediaSession {
     /**
      * Indicates the session was disconnected because the user that the session
      * belonged to is stopping.
+     *
      * @hide
      */
     public static final int DISCONNECT_REASON_USER_STOPPING = 1;
@@ -217,6 +221,16 @@ public final class MediaSession {
         return mPerformer;
     }
 
+    /**
+     * Set an intent for launching UI for this Session. This can be used as a
+     * quick link to an ongoing media screen.
+     *
+     * @param pi The intent to launch to show UI for this Session.
+     */
+    public void setLaunchPendingIntent(PendingIntent pi) {
+        // TODO
+    }
+
     /**
      * Set any flags for the session.
      *
@@ -230,6 +244,38 @@ public final class MediaSession {
         }
     }
 
+    /**
+     * Set the attributes for this session's local playback. This will affect
+     * the system's default volume handling for this session. If
+     * {@link #useRemotePlayback} was previously called it will stop receiving
+     * volume commands and the system will begin handling volume changes.
+     * <p>
+     * By default sessions use {@link AudioAttributes#USAGE_MEDIA}.
+     *
+     * @param attributes The {@link AudioAttributes} for this session's
+     *            playback.
+     */
+    public void useLocalPlayback(AudioAttributes attributes) {
+        // TODO
+    }
+
+    /**
+     * Configure this session to use remote volume handling. This must be called
+     * to receive volume button events, otherwise the system will adjust the
+     * current stream volume for this session. If {@link #useLocalPlayback} was
+     * previously called that stream will stop receiving volume changes for this
+     * session.
+     *
+     * @param volumeProvider The provider that will handle volume changes. May
+     *            not be null.
+     */
+    public void useRemotePlayback(RemoteVolumeProvider volumeProvider) {
+        if (volumeProvider == null) {
+            throw new IllegalArgumentException("volumeProvider may not be null!");
+        }
+        // TODO
+    }
+
     /**
      * Set if this session is currently active and ready to receive commands. If
      * set to false your session's controller may not be discoverable. You must
@@ -461,7 +507,7 @@ public final class MediaSession {
     /**
      * Receives commands or updates from controllers and routes. An app can
      * specify what commands and buttons it supports by setting them on the
-     * MediaSession (TODO).
+     * MediaSession.
      */
     public abstract static class Callback {
 

media/java/android/media/session/RemoteVolumeProvider.java

@@ -0,0 +1,84 @@
+package android.media.session;
+
+/**
+ * Handles requests to adjust or set the volume on a session. This is also used
+ * to push volume updates back to the session after a request has been handled.
+ * You can set a volume provider on a session by calling
+ * {@link MediaSession#useRemotePlayback}.
+ */
+public abstract class RemoteVolumeProvider {
+
+    /**
+     * Handles relative volume changes via {@link #onAdjustVolume(int)}.
+     */
+    public static final int FLAG_VOLUME_RELATIVE = 1 << 0;
+
+    /**
+     * Handles setting the volume via {@link #onSetVolume(int)}.
+     */
+    public static final int FLAG_VOLUME_ABSOLUTE = 1 << 1;
+
+    private final int mFlags;
+    private final int mMaxVolume;
+
+    /**
+     * Create a new volume provider for handling volume events. You must specify
+     * the type of events and the maximum volume that can be used.
+     *
+     * @param flags The flags to use with this provider.
+     * @param maxVolume The maximum allowed volume.
+     */
+    public RemoteVolumeProvider(int flags, int maxVolume) {
+        mFlags = flags;
+        mMaxVolume = maxVolume;
+    }
+
+    /**
+     * Get the current volume of the remote playback.
+     *
+     * @return The current volume.
+     */
+    public abstract int getCurrentVolume();
+
+    /**
+     * Get the flags that were set for this volume provider.
+     *
+     * @return The flags for this volume provider
+     */
+    public final int getFlags() {
+        return mFlags;
+    }
+
+    /**
+     * Get the maximum volume this provider allows.
+     *
+     * @return The max allowed volume.
+     */
+    public final int getMaxVolume() {
+        return mMaxVolume;
+    }
+
+    /**
+     * Notify the system that the remove playback's volume has been changed.
+     */
+    public final void notifyVolumeChanged() {
+        // TODO
+    }
+
+    /**
+     * Override to handle requests to set the volume of the current output.
+     *
+     * @param volume The volume to set the output to.
+     */
+    public void onSetVolume(int volume) {
+    }
+
+    /**
+     * Override to handle requests to adjust the volume of the current
+     * output.
+     *
+     * @param delta The amount to change the volume
+     */
+    public void onAdjustVolume(int delta) {
+    }
+}