Add stream/volume apis to sessions

This adds RemoteVolumeProviders which handle volume change
events and a way to switch a session between local stream
playback and remote playback handling.

This also adds a way for an app to specify the PendingIntent
to launch when we want to show their ongoing playback UI.

Change-Id: I3a72bf2ec7ca55f61f50859ddc2988eebd491e9d

2 files changed, 131 insertions, 1 deletions

diff --git a/media/java/android/media/session/MediaSession.java b/media/java/android/media/session/MediaSession.java
index 6a62dc2..24bbc49 100644
--- a/media/java/android/media/session/MediaSession.java
+++ b/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;
@@ -218,6 +222,16 @@ public final class MediaSession {
     }
 
     /**
+     * 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.
      *
      * @param flags The flags to set for this session.
@@ -231,6 +245,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
      * set the session to active before it can start receiving media button
@@ -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 {
 
diff --git a/media/java/android/media/session/RemoteVolumeProvider.java b/media/java/android/media/session/RemoteVolumeProvider.java
new file mode 100644
index 0000000..9526cc8
--- /dev/null
+++ b/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) {
+    }
+}
\ No newline at end of file