Merge "Fix bug 5045498 Unhide Remote Control Client API"

marcone · Android (Google) Code Review · commit 02ea7d487732 · 2011-09-09T08:44:19.000-07:00
diff --git a/api/current.txt b/api/current.txt
@@ -10326,6 +10326,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);
@@ -10345,6 +10346,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";
@@ -10885,6 +10887,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},
