Public API for RemoteControlClient ratings and editable metadata (b23cd118) · Commits · e / os / android_frameworks_base

api/current.txt

+16 −0

Original line number	Original line	Diff line number	Diff line
	@@ -13065,6 +13065,7 @@ package android.media {
	ctor public RemoteControlClient(android.app.PendingIntent);		ctor public RemoteControlClient(android.app.PendingIntent);
	ctor public RemoteControlClient(android.app.PendingIntent, android.os.Looper);		ctor public RemoteControlClient(android.app.PendingIntent, android.os.Looper);
	method public android.media.RemoteControlClient.MetadataEditor editMetadata(boolean);		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 setOnGetPlaybackPositionListener(android.media.RemoteControlClient.OnGetPlaybackPositionListener);
	method public void setPlaybackPositionUpdateListener(android.media.RemoteControlClient.OnPlaybackPositionUpdateListener);		method public void setPlaybackPositionUpdateListener(android.media.RemoteControlClient.OnPlaybackPositionUpdateListener);
	method public void setPlaybackState(int);		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_PLAY_PAUSE = 8; // 0x8
	field public static final int FLAG_KEY_MEDIA_POSITION_UPDATE = 256; // 0x100		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_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_REWIND = 2; // 0x2
	field public static final int FLAG_KEY_MEDIA_STOP = 32; // 0x20		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_BUFFERING = 8; // 0x8
	@@ -13091,18 +13093,32 @@ package android.media {
	}		}

	public class RemoteControlClient.MetadataEditor {		public class RemoteControlClient.MetadataEditor {
			method public synchronized void addEditableKey(int);
	method public synchronized void apply();		method public synchronized void apply();
	method public synchronized void clear();		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 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 putLong(int, long) throws java.lang.IllegalArgumentException;
	method public synchronized android.media.RemoteControlClient.MetadataEditor putString(int, java.lang.String) 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 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 {		public static abstract interface RemoteControlClient.OnGetPlaybackPositionListener {
	method public abstract long onGetPlaybackPosition();		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 {		public static abstract interface RemoteControlClient.OnPlaybackPositionUpdateListener {
	method public abstract void onPlaybackPositionUpdate(long);		method public abstract void onPlaybackPositionUpdate(long);
	}		}

media/java/android/media/RemoteControlClient.java

+44 −44

Original line number	Original line	Diff line number	Diff line
	@@ -294,14 +294,13 @@ public class RemoteControlClient
	*/		*/
	public final static int FLAG_KEY_MEDIA_POSITION_UPDATE = 1 << 8;		public final static int FLAG_KEY_MEDIA_POSITION_UPDATE = 1 << 8;
	/**		/**
	* @hide
	* CANDIDATE FOR PUBLIC API
	* Flag indicating a RemoteControlClient supports ratings.		* Flag indicating a RemoteControlClient supports ratings.
	* This flag must be set in order for components that display the RemoteControlClient		* This flag must be set in order for components that display the RemoteControlClient
	* information, to display ratings information, and, if ratings are declared editable		* information, to display ratings information, and, if ratings are declared editable
	* (by calling {@link MetadataEditor#addEditableKey(int)} with the		* (by calling {@link MetadataEditor#addEditableKey(int)} with the
	* {@link MetadataEditor#LONG_KEY_RATING_BY_USER} key), it will enable the user to rate		* {@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)		* @see #setTransportControlFlags(int)
	*/		*/
	public final static int FLAG_KEY_MEDIA_RATING = 1 << 9;		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;		public final static int BITMAP_KEY_ARTWORK = 100;
	/**		/**
	* @hide
	* CANDIDATE FOR PUBLIC API
	* The metadata key qualifying the content rating.		* The metadata key qualifying the content rating.
	* The value associated with this key may be: {@link #RATING_HEART},		* 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		* {@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;		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 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,		* 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.		* or {@link #RATING_NOT_RATED} to express that no average rating is available.
	@@ -472,11 +467,12 @@ public class RemoteControlClient
	* <p></p>		* <p></p>
	* When the rating type is:		* When the rating type is:
	* <ul>		* <ul>
	* <li>{@link #RATING_HEART}, a rating of 50 to 100 means "heart selected",</li>		* <li>{@link #RATING_HEART}, a rating of 51 to 100 means "heart selected",</li>
	* <li>{@link #RATING_THUMB_UP_DOWN}, a rating of 0 to 49 means "thumb down", 50 means		* <li>{@link #RATING_THUMB_UP_DOWN}, a rating of 0 to 50 means "thumb down",
	* both "thumb up" and "thumb down" selected, 51 to 100 means "thumb up"</li>		* 51 to 100 means "thumb up"</li>
	* <li>a non-null positive integer, the rating value is mapped to the number of stars, e.g.		* <li>a non-null positive integer, the rating value is mapped to the number of stars, e.g.
	* with a maximum of 5 stars, a rating of 21 to 40 maps to 2 stars.</li>		* with a maximum of 5 stars, a rating of 0 maps to 0 stars, 1 to 20 maps to 1 star,
			* 21 to 40 maps to 2 stars, etc.</li>
	* </ul>		* </ul>
	* @see #LONG_KEY_RATING_BY_USER		* @see #LONG_KEY_RATING_BY_USER
	*/		*/
	@@ -489,34 +485,29 @@ public class RemoteControlClient
	*/		*/
	public final static int KEY_EDITABLE_MASK = 0x1FFFFFFF;		public final static int KEY_EDITABLE_MASK = 0x1FFFFFFF;
	/**		/**
	* @hide		* The metadata key for the content's user rating.
	* CANDIDATE FOR PUBLIC API
	* The metadata key for the content's rating by the user.
	* The value associated with this key may be: an integer value between 0 and 100,		* 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.		* 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		* 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;		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		* 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).		* indicate the content referred to is a favorite (or not).
	* @see #LONG_KEY_RATING_TYPE		* @see #LONG_KEY_RATING_TYPE
	*/		*/
	public final static long RATING_HEART = -1;		public final static long RATING_HEART = -1;
	/**		/**
	* @hide
	* CANDIDATE FOR PUBLIC API
	* A rating style for "thumb up" vs "thumb down".		* A rating style for "thumb up" vs "thumb down".
	* @see #LONG_KEY_RATING_TYPE		* @see #LONG_KEY_RATING_TYPE
	*/		*/
	public final static long RATING_THUMB_UP_DOWN = -2;		public final static long RATING_THUMB_UP_DOWN = -2;
	/**		/**
	* @hide
	* CANDIDATE FOR PUBLIC API
	* A rating value indicating no rating is available.		* A rating value indicating no rating is available.
	* @see #LONG_KEY_RATING_BY_OTHERS		* @see #LONG_KEY_RATING_BY_OTHERS
	* @see #LONG_KEY_RATING_BY_USER		* @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_DISC_NUMBER},
	* {@link android.media.MediaMetadataRetriever#METADATA_KEY_DURATION} (with a value		* {@link android.media.MediaMetadataRetriever#METADATA_KEY_DURATION} (with a value
	* expressed in milliseconds),		* 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		* @param value The long value for the given key
	* @return Returns a reference to the same MetadataEditor object, so you can chain put		* @return Returns a reference to the same MetadataEditor object, so you can chain put
	* calls together.		* calls together.
	@@ -620,8 +613,9 @@ public class RemoteControlClient
	/**		/**
	* Clears all the metadata that has been set since the MetadataEditor instance was		* Clears all the metadata that has been set since the MetadataEditor instance was
	* created with {@link RemoteControlClient#editMetadata(boolean)}.		* 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() {		public synchronized void clear() {
	if (mApplied) {		if (mApplied) {
	Log.e(TAG, "Can't clear a previously applied MetadataEditor");		Log.e(TAG, "Can't clear a previously applied MetadataEditor");
	@@ -632,8 +626,11 @@ public class RemoteControlClient
	}		}

	/**		/**
	* @hide		* Flag the given key as being editable.
	* CANDIDATE FOR PUBLIC API		* 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) {		public synchronized void addEditableKey(int key) {
	if (mApplied) {		if (mApplied) {
	@@ -651,8 +648,7 @@ public class RemoteControlClient
	}		}

	/**		/**
	* @hide		* Causes all metadata fields to be read-only.
	* CANDIDATE FOR PUBLIC API
	*/		*/
	public synchronized void clearEditableKeys() {		public synchronized void clearEditableKeys() {
	if (mApplied) {		if (mApplied) {
	@@ -869,7 +865,8 @@ public class RemoteControlClient
	* {@link #FLAG_KEY_MEDIA_STOP},		* {@link #FLAG_KEY_MEDIA_STOP},
	* {@link #FLAG_KEY_MEDIA_FAST_FORWARD},		* {@link #FLAG_KEY_MEDIA_FAST_FORWARD},
	* {@link #FLAG_KEY_MEDIA_NEXT},		* {@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) {		public void setTransportControlFlags(int transportControlFlags) {
	synchronized(mCacheLock) {		synchronized(mCacheLock) {
	@@ -882,36 +879,39 @@ public class RemoteControlClient
	}		}

	/**		/**
	* @hide		* Interface definition for a callback to be invoked when one of the metadata values has
	* CANDIDATE FOR PUBLIC API		* been updated.
	* TODO ADD DESCRIPTION
	*/		*/
	public interface OnMetadataUpdateListener {		public interface OnMetadataUpdateListener {
	/**		/**
	* TODO ADD DESCRIPTION		* Called on the implementer to notify that the metadata field for the given key has
	* @param key		* been updated to the new value of type <code>long</long>.
	* @param newValue		* @param key the identifier of the updated metadata field of type <code>long</long>.
			* @param newValue the new <code>long</long> value for the key
	*/		*/
	void onMetadataUpdateLong(int key, long newValue);		void onMetadataUpdateLong(int key, long newValue);
	/**		/**
	* TODO ADD DESCRIPTION		* Called on the implementer to notify that the metadata field for the given key has
	* @param key		* been updated to the new <code>String</long>.
	* @param newValue		* @param key the identifier of the updated metadata field of type <code>String</long>.
			* @param newValue the new <code>String</long> value for the key
	*/		*/
	void onMetadataUpdateString(int key, String newValue);		void onMetadataUpdateString(int key, String newValue);
	/**		/**
	* TODO ADD DESCRIPTION		* Called on the implementer to notify that the metadata field for the given key has
	* @param key		* been updated to the new {@link android.graphics.Bitmap}.
	* @param newValue		* @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);		void onMetadataUpdateBitmap(int key, Bitmap newValue);
	}		}

	/**		/**
	* @hide		* Sets the listener to be called whenever the metadata is updated.
	* CANDIDATE FOR PUBLIC API		* New metadata values will be received in the same thread as the one in which
	* TODO ADD DESCRIPTION		* RemoteControlClient was created.
	* @param l		* @param l the metadata update listener
	*/		*/
	public void setMetadataUpdateListener(OnMetadataUpdateListener l) {		public void setMetadataUpdateListener(OnMetadataUpdateListener l) {
	synchronized(mCacheLock) {		synchronized(mCacheLock) {