Fix bug 5045498 Unhide Remote Control Client API

jmtrivi · jmtrivi · commit 466ade5ad66e · 2011-09-01T16:13:50.000-07:00
The RemoteControlClient API enables media application to have
 information such as album art, current song, playback state
 be displayed on "remote control displays", as well as be
 controlled by "remote controls".
The new API consists in:
 - a new class, RemoteControlClient
 - new methods in AudioManager to register a RemoteControlClient
 - a new class, RemoteControlClient.MetadataEditor to edit and
  apply the information associated with a RemoteControlClient,
  and which will be displayed on a "remote control display"

Change-Id: I5616085e4ad58ce0bbc1a5953b0a5a28d32f8703
diff --git a/api/current.txt b/api/current.txt
@@ -10284,6 +10284,7 @@ package android.media {
     method public void playSoundEffect(int);
     method public void playSoundEffect(int, float);
     method public void registerMediaButtonEventReceiver(android.content.ComponentName);
+    method public void registerRemoteControlClient(android.media.RemoteControlClient);
     method public int requestAudioFocus(android.media.AudioManager.OnAudioFocusChangeListener, int, int);
     method public deprecated void setBluetoothA2dpOn(boolean);
     method public void setBluetoothScoOn(boolean);
@@ -10303,6 +10304,7 @@ package android.media {
     method public void stopBluetoothSco();
     method public void unloadSoundEffects();
     method public void unregisterMediaButtonEventReceiver(android.content.ComponentName);
+    method public void unregisterRemoteControlClient(android.media.RemoteControlClient);
     field public static final java.lang.String ACTION_AUDIO_BECOMING_NOISY = "android.media.AUDIO_BECOMING_NOISY";
     field public static final deprecated java.lang.String ACTION_SCO_AUDIO_STATE_CHANGED = "android.media.SCO_AUDIO_STATE_CHANGED";
     field public static final java.lang.String ACTION_SCO_AUDIO_STATE_UPDATED = "android.media.ACTION_SCO_AUDIO_STATE_UPDATED";
@@ -10844,6 +10846,40 @@ package android.media {
     field public static final int SEEK_FORWARD_AVAILABLE = 3; // 0x3
   }
 
+  public class RemoteControlClient {
+    ctor public RemoteControlClient(android.content.ComponentName);
+    ctor public RemoteControlClient(android.content.ComponentName, android.os.Looper);
+    method public android.media.RemoteControlClient.MetadataEditor editMetadata(boolean);
+    method public void setPlaybackState(int);
+    method public void setTransportControlFlags(int);
+    field public static final int FLAG_KEY_MEDIA_FAST_FORWARD = 64; // 0x40
+    field public static final int FLAG_KEY_MEDIA_NEXT = 128; // 0x80
+    field public static final int FLAG_KEY_MEDIA_PAUSE = 16; // 0x10
+    field public static final int FLAG_KEY_MEDIA_PLAY = 4; // 0x4
+    field public static final int FLAG_KEY_MEDIA_PLAY_PAUSE = 8; // 0x8
+    field public static final int FLAG_KEY_MEDIA_PREVIOUS = 1; // 0x1
+    field public static final int FLAG_KEY_MEDIA_REWIND = 2; // 0x2
+    field public static final int FLAG_KEY_MEDIA_STOP = 32; // 0x20
+    field public static final int PLAYSTATE_BUFFERING = 8; // 0x8
+    field public static final int PLAYSTATE_ERROR = 9; // 0x9
+    field public static final int PLAYSTATE_FAST_FORWARDING = 4; // 0x4
+    field public static final int PLAYSTATE_PAUSED = 2; // 0x2
+    field public static final int PLAYSTATE_PLAYING = 3; // 0x3
+    field public static final int PLAYSTATE_REWINDING = 5; // 0x5
+    field public static final int PLAYSTATE_SKIPPING_BACKWARDS = 7; // 0x7
+    field public static final int PLAYSTATE_SKIPPING_FORWARDS = 6; // 0x6
+    field public static final int PLAYSTATE_STOPPED = 1; // 0x1
+  }
+
+  public class RemoteControlClient.MetadataEditor {
+    method public synchronized void apply();
+    method public synchronized void clear();
+    method public synchronized android.media.RemoteControlClient.MetadataEditor putBitmap(int, android.graphics.Bitmap) throws java.lang.IllegalArgumentException;
+    method public synchronized android.media.RemoteControlClient.MetadataEditor putLong(int, long) throws java.lang.IllegalArgumentException;
+    method public synchronized android.media.RemoteControlClient.MetadataEditor putString(int, java.lang.String) throws java.lang.IllegalArgumentException;
+    field public static final int BITMAP_KEY_ARTWORK = 100; // 0x64
+  }
+
   public class Ringtone {
     method public int getStreamType();
     method public java.lang.String getTitle(android.content.Context);
diff --git a/media/java/android/media/AudioManager.java b/media/java/android/media/AudioManager.java
@@ -1717,12 +1717,11 @@ public void unregisterMediaButtonEventReceiver(ComponentName eventReceiver) {
 
 
     /**
-     * @hide
-     * CANDIDATE FOR SDK
      * Registers the remote control client for providing information to display on the remote
      * controls.
-     * @param rcClient the remote control client associated responsible
-     *      for providing the information to display on the remote control.
+     * @param rcClient The remote control client from which remote controls will receive
+     *      information to display.
+     * @see RemoteControlClient
      */
     public void registerRemoteControlClient(RemoteControlClient rcClient) {
         if ((rcClient == null) || (rcClient.getRcEventReceiver() == null)) {
@@ -1741,11 +1740,9 @@ public void registerRemoteControlClient(RemoteControlClient rcClient) {
     }
 
     /**
-     * @hide
-     * CANDIDATE FOR SDK
      * Unregisters the remote control client that was providing information to display on the
-     * remotes.
-     * @param rcClient the remote control client to unregister
+     * remote controls.
+     * @param rcClient The remote control client to unregister.
      * @see #registerRemoteControlClient(RemoteControlClient)
      */
     public void unregisterRemoteControlClient(RemoteControlClient rcClient) {
diff --git a/media/java/android/media/RemoteControlClient.java b/media/java/android/media/RemoteControlClient.java
@@ -17,7 +17,6 @@
 package android.media;
 
 import android.content.ComponentName;
-import android.content.SharedPreferences.Editor;
 import android.graphics.Bitmap;
 import android.graphics.Canvas;
 import android.graphics.Paint;
@@ -31,15 +30,14 @@
 import android.util.Log;
 
 import java.lang.IllegalArgumentException;
-import java.util.HashMap;
 
 /**
- * @hide
- * CANDIDATE FOR SDK
  * RemoteControlClient enables exposing information meant to be consumed by remote controls
- * capable of displaying metadata, album art and media transport control buttons.
- * A remote control client object is associated with a media button event receiver
- * when registered through
+ * capable of displaying metadata, artwork and media transport control buttons.
+ * A remote control client object is associated with a media button event receiver. This
+ * event receiver must have been previously registered with
+ * {@link AudioManager#registerMediaButtonEventReceiver(ComponentName)} before the
+ * RemoteControlClient can be registered through
  * {@link AudioManager#registerRemoteControlClient(RemoteControlClient)}.
  */
 public class RemoteControlClient
@@ -110,7 +108,8 @@ public class RemoteControlClient
     public final static int PLAYSTATE_ERROR              = 9;
     /**
      * @hide
-     * The value of a playback state when none has been declared
+     * The value of a playback state when none has been declared.
+     * Intentionally hidden as an application shouldn't set such a playback state value.
      */
     public final static int PLAYSTATE_NONE               = 0;
 
@@ -122,7 +121,7 @@ public class RemoteControlClient
      */
     public final static int FLAG_KEY_MEDIA_PREVIOUS = 1 << 0;
     /**
-     * Flag indicating a RemoteControlClient makes use of the "rewing" media key.
+     * Flag indicating a RemoteControlClient makes use of the "rewind" media key.
      *
      * @see #setTransportControlFlags(int)
      * @see android.view.KeyEvent#KEYCODE_MEDIA_REWIND
@@ -173,7 +172,9 @@ public class RemoteControlClient
 
     /**
      * @hide
-     * The flags for when no media keys are declared supported
+     * The flags for when no media keys are declared supported.
+     * Intentionally hidden as an application shouldn't set the transport control flags
+     *     to this value.
      */
     public final static int FLAGS_KEY_MEDIA_NONE = 0;
 
@@ -184,29 +185,29 @@ public class RemoteControlClient
     public final static int FLAG_INFORMATION_REQUEST_METADATA = 1 << 0;
     /**
      * @hide
-     * FIXME doc not valid
      * Flag used to signal that the transport control buttons supported by the
-     * RemoteControlClient have changed.
+     *     RemoteControlClient are requested.
      * This can for instance happen when playback is at the end of a playlist, and the "next"
      * operation is not supported anymore.
      */
     public final static int FLAG_INFORMATION_REQUEST_KEY_MEDIA = 1 << 1;
     /**
      * @hide
-     * FIXME doc not valid
-     * Flag used to signal that the playback state of the RemoteControlClient has changed.
+     * Flag used to signal that the playback state of the RemoteControlClient is requested.
      */
     public final static int FLAG_INFORMATION_REQUEST_PLAYSTATE = 1 << 2;
     /**
      * @hide
-     * FIXME doc not valid
-     * Flag used to signal that the album art for the RemoteControlClient has changed.
+     * Flag used to signal that the album art for the RemoteControlClient is requested.
      */
     public final static int FLAG_INFORMATION_REQUEST_ALBUM_ART = 1 << 3;
 
     /**
      * Class constructor.
-     * @param mediaButtonEventReceiver the receiver for the media button events.
+     * @param mediaButtonEventReceiver The receiver for the media button events. It needs to have
+     *     been registered with {@link AudioManager#registerMediaButtonEventReceiver(ComponentName)}
+     *     before this new RemoteControlClient can itself be registered with
+     *     {@link AudioManager#registerRemoteControlClient(RemoteControlClient)}.
      * @see AudioManager#registerMediaButtonEventReceiver(ComponentName)
      * @see AudioManager#registerRemoteControlClient(RemoteControlClient)
      */
@@ -227,8 +228,11 @@ public RemoteControlClient(ComponentName mediaButtonEventReceiver) {
     /**
      * Class constructor for a remote control client whose internal event handling
      * happens on a user-provided Looper.
-     * @param mediaButtonEventReceiver the receiver for the media button events.
-     * @param looper the Looper running the event loop.
+     * @param mediaButtonEventReceiver The receiver for the media button events. It needs to have
+     *     been registered with {@link AudioManager#registerMediaButtonEventReceiver(ComponentName)}
+     *     before this new RemoteControlClient can itself be registered with
+     *     {@link AudioManager#registerRemoteControlClient(RemoteControlClient)}.
+     * @param looper The Looper running the event loop.
      * @see AudioManager#registerMediaButtonEventReceiver(ComponentName)
      * @see AudioManager#registerRemoteControlClient(RemoteControlClient)
      */
@@ -257,11 +261,28 @@ public RemoteControlClient(ComponentName mediaButtonEventReceiver, Looper looper
 
     /**
      * Class used to modify metadata in a {@link RemoteControlClient} object.
+     * Use {@link RemoteControlClient#editMetadata(boolean)} to create an instance of an editor,
+     * on which you set the metadata for the RemoteControlClient instance. Once all the information
+     * has been set, use {@link #apply()} to make it the new metadata that should be displayed
+     * for the associated client. Once the metadata has been "applied", you cannot reuse this
+     * instance of the MetadataEditor.
      */
     public class MetadataEditor {
+        /**
+         * @hide
+         */
         protected boolean mMetadataChanged;
+        /**
+         * @hide
+         */
         protected boolean mArtworkChanged;
+        /**
+         * @hide
+         */
         protected Bitmap mEditorArtwork;
+        /**
+         * @hide
+         */
         protected Bundle mEditorMetadata;
         private boolean mApplied = false;
 
@@ -277,13 +298,18 @@ public Object clone() throws CloneNotSupportedException {
         /**
          * The metadata key for the content artwork / album art.
          */
-        public final static int METADATA_KEY_ARTWORK = 100;
+        public final static int BITMAP_KEY_ARTWORK = 100;
+        /**
+         * @hide
+         * TODO(jmtrivi) have lockscreen and music move to the new key name
+         */
+        public final static int METADATA_KEY_ARTWORK = BITMAP_KEY_ARTWORK;
 
         /**
          * Adds textual information to be displayed.
          * Note that none of the information added after {@link #apply()} has been called,
          * will be displayed.
-         * @param key the identifier of a the metadata field to set. Valid values are
+         * @param key The identifier of a the metadata field to set. Valid values are
          *      {@link android.media.MediaMetadataRetriever#METADATA_KEY_ALBUM},
          *      {@link android.media.MediaMetadataRetriever#METADATA_KEY_ALBUMARTIST},
          *      {@link android.media.MediaMetadataRetriever#METADATA_KEY_TITLE},
@@ -294,11 +320,11 @@ public Object clone() throws CloneNotSupportedException {
          *      {@link android.media.MediaMetadataRetriever#METADATA_KEY_DATE},
          *      {@link android.media.MediaMetadataRetriever#METADATA_KEY_GENRE},
          *      {@link android.media.MediaMetadataRetriever#METADATA_KEY_TITLE},
-         *      {@link android.media.MediaMetadataRetriever#METADATA_KEY_WRITER},
-         *      .
-         * @param value the text for the given key, or {@code null} to signify there is no valid
+         *      {@link android.media.MediaMetadataRetriever#METADATA_KEY_WRITER}.
+         * @param value The text for the given key, or {@code null} to signify there is no valid
          *      information for the field.
-         * @return      FIXME description
+         * @return Returns a reference to the same MetadataEditor object, so you can chain put
+         *      calls together.
          */
         public synchronized MetadataEditor putString(int key, String value)
                 throws IllegalArgumentException {
@@ -315,15 +341,18 @@ public synchronized MetadataEditor putString(int key, String value)
         }
 
         /**
-         * FIXME javadoc
+         * Adds numerical information to be displayed.
+         * Note that none of the information added after {@link #apply()} has been called,
+         * will be displayed.
          * @param key the identifier of a the metadata field to set. Valid values are
          *      {@link android.media.MediaMetadataRetriever#METADATA_KEY_CD_TRACK_NUMBER},
          *      {@link android.media.MediaMetadataRetriever#METADATA_KEY_DISC_NUMBER},
          *      {@link android.media.MediaMetadataRetriever#METADATA_KEY_DURATION} (with a value
          *      expressed in milliseconds),
          *      {@link android.media.MediaMetadataRetriever#METADATA_KEY_YEAR}.
-         * @param value FIXME javadoc
-         * @return FIXME javadoc
+         * @param value The long value for the given key
+         * @return Returns a reference to the same MetadataEditor object, so you can chain put
+         *      calls together.
          * @throws IllegalArgumentException
          */
         public synchronized MetadataEditor putLong(int key, long value)
@@ -342,9 +371,11 @@ public synchronized MetadataEditor putLong(int key, long value)
 
         /**
          * Sets the album / artwork picture to be displayed on the remote control.
-         * @param key FIXME description
-         * @param bitmap the bitmap for the artwork, or null if there isn't any.
-         * @return FIXME description
+         * @param key the identifier of the bitmap to set. The only valid value is
+         *      {@link #BITMAP_KEY_ARTWORK}
+         * @param bitmap The bitmap for the artwork, or null if there isn't any.
+         * @return Returns a reference to the same MetadataEditor object, so you can chain put
+         *      calls together.
          * @throws IllegalArgumentException
          * @see android.graphics.Bitmap
          */
@@ -354,7 +385,7 @@ public synchronized MetadataEditor putBitmap(int key, Bitmap bitmap)
                 Log.e(TAG, "Can't edit a previously applied MetadataEditor");
                 return this;
             }
-            if (key != METADATA_KEY_ARTWORK) {
+            if (key != BITMAP_KEY_ARTWORK) {
                 throw(new IllegalArgumentException("Invalid type 'Bitmap' for key "+ key));
             }
             if ((mArtworkExpectedWidth > 0) && (mArtworkExpectedHeight > 0)) {
@@ -369,7 +400,8 @@ public synchronized MetadataEditor putBitmap(int key, Bitmap bitmap)
         }
 
         /**
-         * FIXME description
+         * Clears all the metadata that has been set since the MetadataEditor instance was
+         *     created with {@link RemoteControlClient#editMetadata(boolean)}.
          */
         public synchronized void clear() {
             if (mApplied) {
@@ -381,7 +413,10 @@ public synchronized void clear() {
         }
 
         /**
-         * FIXME description
+         * Associates all the metadata that has been set since the MetadataEditor instance was
+         *     created with {@link RemoteControlClient#editMetadata(boolean)}, or since
+         *     {@link #clear()} was called, with the RemoteControlClient. Once "applied",
+         *     this MetadataEditor cannot be reused to edit the RemoteControlClient's metadata.
          */
         public synchronized void apply() {
             if (mApplied) {
@@ -408,9 +443,10 @@ public synchronized void apply() {
     }
 
     /**
-     * FIXME description
-     * @param startEmpty
-     * @return
+     * Creates a {@link MetadataEditor}.
+     * @param startEmpty Set to false if you want the MetadataEditor to contain the metadata that
+     *     was previously applied to the RemoteControlClient, or true if it is to be created empty.
+     * @return a new MetadataEditor instance.
      */
     public MetadataEditor editMetadata(boolean startEmpty) {
         MetadataEditor editor = new MetadataEditor();
@@ -430,7 +466,7 @@ public MetadataEditor editMetadata(boolean startEmpty) {
 
     /**
      * Sets the current playback state.
-     * @param state the current playback state, one of the following values:
+     * @param state The current playback state, one of the following values:
      *       {@link #PLAYSTATE_STOPPED},
      *       {@link #PLAYSTATE_PAUSED},
      *       {@link #PLAYSTATE_PLAYING},
@@ -453,7 +489,7 @@ public void setPlaybackState(int state) {
 
     /**
      * Sets the flags for the media transport control buttons that this client supports.
-     * @param a combination of the following flags:
+     * @param transportControlFlags A combination of the following flags:
      *      {@link #FLAG_KEY_MEDIA_PREVIOUS},
      *      {@link #FLAG_KEY_MEDIA_REWIND},
      *      {@link #FLAG_KEY_MEDIA_PLAY},
