diff --git a/api/current.txt b/api/current.txt index 27a848062a4c3..1af1226eccbf1 100644 --- a/api/current.txt +++ b/api/current.txt @@ -13065,6 +13065,7 @@ package android.media { ctor public RemoteControlClient(android.app.PendingIntent); ctor public RemoteControlClient(android.app.PendingIntent, android.os.Looper); method public android.media.RemoteControlClient.MetadataEditor editMetadata(boolean); + method public void setMetadataUpdateListener(android.media.RemoteControlClient.OnMetadataUpdateListener); method public void setOnGetPlaybackPositionListener(android.media.RemoteControlClient.OnGetPlaybackPositionListener); method public void setPlaybackPositionUpdateListener(android.media.RemoteControlClient.OnPlaybackPositionUpdateListener); method public void setPlaybackState(int); @@ -13077,6 +13078,7 @@ package android.media { field public static final int FLAG_KEY_MEDIA_PLAY_PAUSE = 8; // 0x8 field public static final int FLAG_KEY_MEDIA_POSITION_UPDATE = 256; // 0x100 field public static final int FLAG_KEY_MEDIA_PREVIOUS = 1; // 0x1 + field public static final int FLAG_KEY_MEDIA_RATING = 512; // 0x200 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 @@ -13091,18 +13093,32 @@ package android.media { } public class RemoteControlClient.MetadataEditor { + method public synchronized void addEditableKey(int); method public synchronized void apply(); method public synchronized void clear(); + method public synchronized void clearEditableKeys(); 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 + field public static final int LONG_KEY_RATING_BY_OTHERS = 102; // 0x66 + field public static final int LONG_KEY_RATING_BY_USER = 268435457; // 0x10000001 + field public static final int LONG_KEY_RATING_TYPE = 101; // 0x65 + field public static final long RATING_HEART = -1L; // 0xffffffffffffffffL + field public static final long RATING_NOT_RATED = -101L; // 0xffffffffffffff9bL + field public static final long RATING_THUMB_UP_DOWN = -2L; // 0xfffffffffffffffeL } public static abstract interface RemoteControlClient.OnGetPlaybackPositionListener { method public abstract long onGetPlaybackPosition(); } + public static abstract interface RemoteControlClient.OnMetadataUpdateListener { + method public abstract void onMetadataUpdateBitmap(int, android.graphics.Bitmap); + method public abstract void onMetadataUpdateLong(int, long); + method public abstract void onMetadataUpdateString(int, java.lang.String); + } + public static abstract interface RemoteControlClient.OnPlaybackPositionUpdateListener { method public abstract void onPlaybackPositionUpdate(long); } diff --git a/media/java/android/media/RemoteControlClient.java b/media/java/android/media/RemoteControlClient.java index 4dcac31b19288..58f5d55369d03 100644 --- a/media/java/android/media/RemoteControlClient.java +++ b/media/java/android/media/RemoteControlClient.java @@ -294,14 +294,13 @@ public class RemoteControlClient */ public final static int FLAG_KEY_MEDIA_POSITION_UPDATE = 1 << 8; /** - * @hide - * CANDIDATE FOR PUBLIC API * Flag indicating a RemoteControlClient supports ratings. * This flag must be set in order for components that display the RemoteControlClient * information, to display ratings information, and, if ratings are declared editable * (by calling {@link MetadataEditor#addEditableKey(int)} with the * {@link MetadataEditor#LONG_KEY_RATING_BY_USER} key), it will enable the user to rate - * the media. + * the media, with values being received through the interface set with + * {@link #setMetadataUpdateListener(OnMetadataUpdateListener)}. * @see #setTransportControlFlags(int) */ public final static int FLAG_KEY_MEDIA_RATING = 1 << 9; @@ -452,8 +451,6 @@ public class RemoteControlClient */ public final static int BITMAP_KEY_ARTWORK = 100; /** - * @hide - * CANDIDATE FOR PUBLIC API * The metadata key qualifying the content rating. * The value associated with this key may be: {@link #RATING_HEART}, * {@link #RATING_THUMB_UP_DOWN}, or a non-null positive integer expressing a maximum @@ -461,8 +458,6 @@ public class RemoteControlClient */ public final static int LONG_KEY_RATING_TYPE = 101; /** - * @hide - * CANDIDATE FOR PUBLIC API * The metadata key for the content's average rating, not the user's rating. * The value associated with this key may be: an integer value between 0 and 100, * or {@link #RATING_NOT_RATED} to express that no average rating is available. @@ -472,11 +467,12 @@ public class RemoteControlClient *

* When the rating type is: * * @see #LONG_KEY_RATING_BY_USER */ @@ -489,34 +485,29 @@ public class RemoteControlClient */ public final static int KEY_EDITABLE_MASK = 0x1FFFFFFF; /** - * @hide - * CANDIDATE FOR PUBLIC API - * The metadata key for the content's rating by the user. + * The metadata key for the content's user rating. * The value associated with this key may be: an integer value between 0 and 100, * or {@link #RATING_NOT_RATED} to express that the user hasn't rated this content. * Rules for the interpretation of the rating value according to the rating style are - * the same as for {@link #LONG_KEY_RATING_BY_OTHERS} + * the same as for {@link #LONG_KEY_RATING_BY_OTHERS}. + * This key can be flagged as "editable" (with {@link #addEditableKey(int)}) to enable + * receiving user rating values through the + * {@link android.media.RemoteControlClient.OnMetadataUpdateListener} interface. */ public final static int LONG_KEY_RATING_BY_USER = 0x10000001; /** - * @hide - * CANDIDATE FOR PUBLIC API * A rating style with a single degree of rating, "heart" vs "no heart". Can be used to * indicate the content referred to is a favorite (or not). * @see #LONG_KEY_RATING_TYPE */ public final static long RATING_HEART = -1; /** - * @hide - * CANDIDATE FOR PUBLIC API * A rating style for "thumb up" vs "thumb down". * @see #LONG_KEY_RATING_TYPE */ public final static long RATING_THUMB_UP_DOWN = -2; /** - * @hide - * CANDIDATE FOR PUBLIC API * A rating value indicating no rating is available. * @see #LONG_KEY_RATING_BY_OTHERS * @see #LONG_KEY_RATING_BY_USER @@ -573,7 +564,9 @@ public class RemoteControlClient * {@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}. + * {@link android.media.MediaMetadataRetriever#METADATA_KEY_YEAR}, + * {@link #LONG_KEY_RATING_BY_OTHERS}, {@link #LONG_KEY_RATING_BY_USER}, + * {@link #LONG_KEY_RATING_TYPE}. * @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. @@ -620,8 +613,9 @@ public class RemoteControlClient /** * Clears all the metadata that has been set since the MetadataEditor instance was * created with {@link RemoteControlClient#editMetadata(boolean)}. + * Note that clearing the metadata doesn't reset the editable keys + * (use {@link #clearEditableKeys()} instead). */ - // TODO add in javadoc that this doesn't call clearEditableKeys() public synchronized void clear() { if (mApplied) { Log.e(TAG, "Can't clear a previously applied MetadataEditor"); @@ -632,8 +626,11 @@ public class RemoteControlClient } /** - * @hide - * CANDIDATE FOR PUBLIC API + * Flag the given key as being editable. + * This will declare the metadata field as eligible to be updated, with new values + * received through the {@link RemoteControlClient.OnMetadataUpdateListener} interface. + * @param key the type of metadata that can be edited. The supported key is + * {@link #LONG_KEY_RATING_BY_USER}. */ public synchronized void addEditableKey(int key) { if (mApplied) { @@ -651,8 +648,7 @@ public class RemoteControlClient } /** - * @hide - * CANDIDATE FOR PUBLIC API + * Causes all metadata fields to be read-only. */ public synchronized void clearEditableKeys() { if (mApplied) { @@ -869,7 +865,8 @@ public class RemoteControlClient * {@link #FLAG_KEY_MEDIA_STOP}, * {@link #FLAG_KEY_MEDIA_FAST_FORWARD}, * {@link #FLAG_KEY_MEDIA_NEXT}, - * {@link #FLAG_KEY_MEDIA_POSITION_UPDATE} + * {@link #FLAG_KEY_MEDIA_POSITION_UPDATE}, + * {@link #FLAG_KEY_MEDIA_RATING}. */ public void setTransportControlFlags(int transportControlFlags) { synchronized(mCacheLock) { @@ -882,36 +879,39 @@ public class RemoteControlClient } /** - * @hide - * CANDIDATE FOR PUBLIC API - * TODO ADD DESCRIPTION + * Interface definition for a callback to be invoked when one of the metadata values has + * been updated. */ public interface OnMetadataUpdateListener { /** - * TODO ADD DESCRIPTION - * @param key - * @param newValue + * Called on the implementer to notify that the metadata field for the given key has + * been updated to the new value of type long. + * @param key the identifier of the updated metadata field of type long. + * @param newValue the new long value for the key */ void onMetadataUpdateLong(int key, long newValue); /** - * TODO ADD DESCRIPTION - * @param key - * @param newValue + * Called on the implementer to notify that the metadata field for the given key has + * been updated to the new String. + * @param key the identifier of the updated metadata field of type String. + * @param newValue the new String value for the key */ void onMetadataUpdateString(int key, String newValue); /** - * TODO ADD DESCRIPTION - * @param key - * @param newValue + * Called on the implementer to notify that the metadata field for the given key has + * been updated to the new {@link android.graphics.Bitmap}. + * @param key the identifier of the updated metadata field of type + * {@link android.graphics.Bitmap}. + * @param newValue the new {@link android.graphics.Bitmap} for the key */ void onMetadataUpdateBitmap(int key, Bitmap newValue); } /** - * @hide - * CANDIDATE FOR PUBLIC API - * TODO ADD DESCRIPTION - * @param l + * Sets the listener to be called whenever the metadata is updated. + * New metadata values will be received in the same thread as the one in which + * RemoteControlClient was created. + * @param l the metadata update listener */ public void setMetadataUpdateListener(OnMetadataUpdateListener l) { synchronized(mCacheLock) {