Merge "Annotate Media section of framework/base" into nyc-dev (542221d6) · Commits · e / os / android_frameworks_base

media/java/android/media/MediaMetadata.java

+50 −13

Original line number	Diff line number	Diff line
		@@ -16,6 +16,7 @@
		package android.media;

		import android.annotation.NonNull;
		import android.annotation.StringDef;
		import android.content.ContentResolver;
		import android.graphics.Bitmap;
		import android.graphics.BitmapFactory;
		@@ -30,6 +31,8 @@ import android.util.ArrayMap;
		import android.util.Log;
		import android.util.SparseArray;

		import java.lang.annotation.Retention;
		import java.lang.annotation.RetentionPolicy;
		import java.util.Set;

		/**
		@@ -38,6 +41,40 @@ import java.util.Set;
		public final class MediaMetadata implements Parcelable {
		private static final String TAG = "MediaMetadata";

		/**
		* @hide
		*/
		@StringDef({METADATA_KEY_TITLE, METADATA_KEY_ARTIST, METADATA_KEY_ALBUM, METADATA_KEY_AUTHOR,
		METADATA_KEY_WRITER, METADATA_KEY_COMPOSER, METADATA_KEY_COMPILATION,
		METADATA_KEY_DATE, METADATA_KEY_GENRE, METADATA_KEY_ALBUM_ARTIST, METADATA_KEY_ART_URI,
		METADATA_KEY_ALBUM_ART_URI, METADATA_KEY_DISPLAY_TITLE, METADATA_KEY_DISPLAY_SUBTITLE,
		METADATA_KEY_DISPLAY_DESCRIPTION, METADATA_KEY_DISPLAY_ICON_URI,
		METADATA_KEY_MEDIA_ID})
		@Retention(RetentionPolicy.SOURCE)
		public @interface TextKey {}

		/**
		* @hide
		*/
		@StringDef({METADATA_KEY_DURATION, METADATA_KEY_YEAR, METADATA_KEY_TRACK_NUMBER,
		METADATA_KEY_NUM_TRACKS, METADATA_KEY_DISC_NUMBER})
		@Retention(RetentionPolicy.SOURCE)
		public @interface LongKey {}

		/**
		* @hide
		*/
		@StringDef({METADATA_KEY_ART, METADATA_KEY_ALBUM_ART, METADATA_KEY_DISPLAY_ICON})
		@Retention(RetentionPolicy.SOURCE)
		public @interface BitmapKey {}

		/**
		* @hide
		*/
		@StringDef({METADATA_KEY_USER_RATING, METADATA_KEY_RATING})
		@Retention(RetentionPolicy.SOURCE)
		public @interface RatingKey {}

		/**
		* The title of the media.
		*/
		@@ -232,7 +269,7 @@ public final class MediaMetadata implements Parcelable {
		*/
		public static final String METADATA_KEY_MEDIA_ID = "android.media.metadata.MEDIA_ID";

		private static final String[] PREFERRED_DESCRIPTION_ORDER = {
		private static final @TextKey String[] PREFERRED_DESCRIPTION_ORDER = {
		METADATA_KEY_TITLE,
		METADATA_KEY_ARTIST,
		METADATA_KEY_ALBUM,
		@@ -242,13 +279,13 @@ public final class MediaMetadata implements Parcelable {
		METADATA_KEY_COMPOSER
		};

		private static final String[] PREFERRED_BITMAP_ORDER = {
		private static final @BitmapKey String[] PREFERRED_BITMAP_ORDER = {
		METADATA_KEY_DISPLAY_ICON,
		METADATA_KEY_ART,
		METADATA_KEY_ALBUM_ART
		};

		private static final String[] PREFERRED_URI_ORDER = {
		private static final @TextKey String[] PREFERRED_URI_ORDER = {
		METADATA_KEY_DISPLAY_ICON_URI,
		METADATA_KEY_ART_URI,
		METADATA_KEY_ALBUM_ART_URI
		@@ -349,7 +386,7 @@ public final class MediaMetadata implements Parcelable {
		* @param key The key the value is stored under
		* @return a CharSequence value, or null
		*/
		public CharSequence getText(String key) {
		public CharSequence getText(@TextKey String key) {
		return mBundle.getCharSequence(key);
		}

		@@ -362,7 +399,7 @@ public final class MediaMetadata implements Parcelable {
		* @param key The key the value is stored under
		* @return a String value, or null
		*/
		public String getString(String key) {
		public String getString(@TextKey String key) {
		CharSequence text = getText(key);
		if (text != null) {
		return text.toString();
		@@ -377,7 +414,7 @@ public final class MediaMetadata implements Parcelable {
		* @param key The key the value is stored under
		* @return a long value
		*/
		public long getLong(String key) {
		public long getLong(@LongKey String key) {
		return mBundle.getLong(key, 0);
		}

		@@ -388,7 +425,7 @@ public final class MediaMetadata implements Parcelable {
		* @param key The key the value is stored under
		* @return A {@link Rating} or null
		*/
		public Rating getRating(String key) {
		public Rating getRating(@RatingKey String key) {
		Rating rating = null;
		try {
		rating = mBundle.getParcelable(key);
		@@ -406,7 +443,7 @@ public final class MediaMetadata implements Parcelable {
		* @param key The key the value is stored under
		* @return A {@link Bitmap} or null
		*/
		public Bitmap getBitmap(String key) {
		public Bitmap getBitmap(@BitmapKey String key) {
		Bitmap bmp = null;
		try {
		bmp = mBundle.getParcelable(key);
		@@ -612,7 +649,7 @@ public final class MediaMetadata implements Parcelable {
		* @param value The CharSequence value to store
		* @return The Builder to allow chaining
		*/
		public Builder putText(String key, CharSequence value) {
		public Builder putText(@TextKey String key, CharSequence value) {
		if (METADATA_KEYS_TYPE.containsKey(key)) {
		if (METADATA_KEYS_TYPE.get(key) != METADATA_TYPE_TEXT) {
		throw new IllegalArgumentException("The " + key
		@@ -654,7 +691,7 @@ public final class MediaMetadata implements Parcelable {
		* @param value The String value to store
		* @return The Builder to allow chaining
		*/
		public Builder putString(String key, String value) {
		public Builder putString(@TextKey String key, String value) {
		if (METADATA_KEYS_TYPE.containsKey(key)) {
		if (METADATA_KEYS_TYPE.get(key) != METADATA_TYPE_TEXT) {
		throw new IllegalArgumentException("The " + key
		@@ -681,7 +718,7 @@ public final class MediaMetadata implements Parcelable {
		* @param value The long value to store
		* @return The Builder to allow chaining
		*/
		public Builder putLong(String key, long value) {
		public Builder putLong(@LongKey String key, long value) {
		if (METADATA_KEYS_TYPE.containsKey(key)) {
		if (METADATA_KEYS_TYPE.get(key) != METADATA_TYPE_LONG) {
		throw new IllegalArgumentException("The " + key
		@@ -705,7 +742,7 @@ public final class MediaMetadata implements Parcelable {
		* @param value The Rating value to store
		* @return The Builder to allow chaining
		*/
		public Builder putRating(String key, Rating value) {
		public Builder putRating(@RatingKey String key, Rating value) {
		if (METADATA_KEYS_TYPE.containsKey(key)) {
		if (METADATA_KEYS_TYPE.get(key) != METADATA_TYPE_RATING) {
		throw new IllegalArgumentException("The " + key
		@@ -734,7 +771,7 @@ public final class MediaMetadata implements Parcelable {
		* @param value The Bitmap to store
		* @return The Builder to allow chaining
		*/
		public Builder putBitmap(String key, Bitmap value) {
		public Builder putBitmap(@BitmapKey String key, Bitmap value) {
		if (METADATA_KEYS_TYPE.containsKey(key)) {
		if (METADATA_KEYS_TYPE.get(key) != METADATA_TYPE_BITMAP) {
		throw new IllegalArgumentException("The " + key

media/java/android/media/MediaRouter.java

+20 −4

Original line number	Diff line number	Diff line
		@@ -1547,18 +1547,30 @@ public class MediaRouter {

		private Object mTag;

		/** @hide */
		@IntDef({PLAYBACK_TYPE_LOCAL, PLAYBACK_TYPE_REMOTE})
		@Retention(RetentionPolicy.SOURCE)
		public @interface PlaybackType {}

		/**
		* The default playback type, "local", indicating the presentation of the media is happening
		* on the same device (e.g. a phone, a tablet) as where it is controlled from.
		* @see #getPlaybackType()
		*/
		public final static int PLAYBACK_TYPE_LOCAL = 0;

		/**
		* A playback type indicating the presentation of the media is happening on
		* a different device (i.e. the remote device) than where it is controlled from.
		* @see #getPlaybackType()
		*/
		public final static int PLAYBACK_TYPE_REMOTE = 1;

		/** @hide */
		@IntDef({PLAYBACK_VOLUME_FIXED,PLAYBACK_VOLUME_VARIABLE})
		@Retention(RetentionPolicy.SOURCE)
		private @interface PlaybackVolume {}

		/**
		* Playback information indicating the playback volume is fixed, i.e. it cannot be
		* controlled from this object. An example of fixed playback volume is a remote player,
		@@ -1783,6 +1795,7 @@ public class MediaRouter {
		* @return the type of playback associated with this route
		* @see UserRouteInfo#setPlaybackType(int)
		*/
		@PlaybackType
		public int getPlaybackType() {
		return mPlaybackType;
		}
		@@ -1874,6 +1887,7 @@ public class MediaRouter {
		* @return how volume is handling on the route
		* @see UserRouteInfo#setVolumeHandling(int)
		*/
		@PlaybackVolume
		public int getVolumeHandling() {
		return mVolumeHandling;
		}
		@@ -2164,7 +2178,7 @@ public class MediaRouter {
		* ({@link RouteInfo#PLAYBACK_TYPE_REMOTE}).
		* @param type
		*/
		public void setPlaybackType(int type) {
		public void setPlaybackType(@RouteInfo.PlaybackType int type) {
		if (mPlaybackType != type) {
		mPlaybackType = type;
		configureSessionVolume();
		@@ -2177,7 +2191,7 @@ public class MediaRouter {
		* ({@link RouteInfo#PLAYBACK_VOLUME_VARIABLE}).
		* @param volumeHandling
		*/
		public void setVolumeHandling(int volumeHandling) {
		public void setVolumeHandling(@RouteInfo.PlaybackVolume int volumeHandling) {
		if (mVolumeHandling != volumeHandling) {
		mVolumeHandling = volumeHandling;
		configureSessionVolume();
		@@ -2268,7 +2282,8 @@ public class MediaRouter {
		return;
		}
		if (mPlaybackType == RemoteControlClient.PLAYBACK_TYPE_REMOTE) {
		int volumeControl = VolumeProvider.VOLUME_CONTROL_FIXED;
		@VolumeProvider.ControlType int volumeControl =
		VolumeProvider.VOLUME_CONTROL_FIXED;
		switch (mVolumeHandling) {
		case RemoteControlClient.PLAYBACK_VOLUME_VARIABLE:
		volumeControl = VolumeProvider.VOLUME_CONTROL_ABSOLUTE;
		@@ -2294,7 +2309,8 @@ public class MediaRouter {

		class SessionVolumeProvider extends VolumeProvider {

		public SessionVolumeProvider(int volumeControl, int maxVolume, int currentVolume) {
		public SessionVolumeProvider(@VolumeProvider.ControlType int volumeControl,
		int maxVolume, int currentVolume) {
		super(volumeControl, maxVolume, currentVolume);
		}

media/java/android/media/Rating.java

+24 −4

Original line number	Diff line number	Diff line
		@@ -16,10 +16,14 @@

		package android.media;

		import android.annotation.IntDef;
		import android.os.Parcel;
		import android.os.Parcelable;
		import android.util.Log;

		import java.lang.annotation.Retention;
		import java.lang.annotation.RetentionPolicy;

		/**
		* A class to encapsulate rating information used as content metadata.
		* A rating is defined by its rating style (see {@link #RATING_HEART},
		@@ -31,6 +35,21 @@ import android.util.Log;
		public final class Rating implements Parcelable {
		private final static String TAG = "Rating";

		/**
		* @hide
		*/
		@IntDef({RATING_NONE, RATING_HEART, RATING_THUMB_UP_DOWN, RATING_3_STARS, RATING_4_STARS,
		RATING_5_STARS, RATING_PERCENTAGE})
		@Retention(RetentionPolicy.SOURCE)
		public @interface Style {}

		/**
		* @hide
		*/
		@IntDef({RATING_3_STARS, RATING_4_STARS, RATING_5_STARS})
		@Retention(RetentionPolicy.SOURCE)
		public @interface StarStyle {}

		/**
		* Indicates a rating style is not supported. A Rating will never have this
		* type, but can be used by other classes to indicate they do not support
		@@ -75,7 +94,7 @@ public final class Rating implements Parcelable {

		private final float mRatingValue;

		private Rating(int ratingStyle, float rating) {
		private Rating(@Style int ratingStyle, float rating) {
		mRatingStyle = ratingStyle;
		mRatingValue = rating;
		}
		@@ -124,7 +143,7 @@ public final class Rating implements Parcelable {
		* or {@link #RATING_PERCENTAGE}.
		* @return null if an invalid rating style is passed, a new Rating instance otherwise.
		*/
		public static Rating newUnratedRating(int ratingStyle) {
		public static Rating newUnratedRating(@Style int ratingStyle) {
		switch(ratingStyle) {
		case RATING_HEART:
		case RATING_THUMB_UP_DOWN:
		@@ -172,7 +191,7 @@ public final class Rating implements Parcelable {
		* @return null if the rating style is invalid, or the rating is out of range,
		* a new Rating instance otherwise.
		*/
		public static Rating newStarRating(int starRatingStyle, float starRating) {
		public static Rating newStarRating(@StarStyle int starRatingStyle, float starRating) {
		float maxRating = -1.0f;
		switch(starRatingStyle) {
		case RATING_3_STARS:
		@@ -225,6 +244,7 @@ public final class Rating implements Parcelable {
		* {@link #RATING_3_STARS}, {@link #RATING_4_STARS}, {@link #RATING_5_STARS},
		* or {@link #RATING_PERCENTAGE}.
		*/
		@Style
		public int getRatingStyle() {
		return mRatingStyle;
		}

media/java/android/media/VolumeProvider.java

+15 −2

Original line number	Diff line number	Diff line
		@@ -15,8 +15,12 @@
		*/
		package android.media;

		import android.annotation.IntDef;
		import android.media.session.MediaSession;

		import java.lang.annotation.Retention;
		import java.lang.annotation.RetentionPolicy;

		/**
		* Handles requests to adjust or set the volume on a session. This is also used
		* to push volume updates back to the session. The provider must call
		@@ -26,6 +30,14 @@ import android.media.session.MediaSession;
		* {@link MediaSession#setPlaybackToRemote}.
		*/
		public abstract class VolumeProvider {

		/**
		* @hide
		*/
		@IntDef({VOLUME_CONTROL_FIXED, VOLUME_CONTROL_RELATIVE, VOLUME_CONTROL_ABSOLUTE})
		@Retention(RetentionPolicy.SOURCE)
		public @interface ControlType {}

		/**
		* The volume is fixed and can not be modified. Requests to change volume
		* should be ignored.
		@@ -61,7 +73,7 @@ public abstract class VolumeProvider {
		* @param maxVolume The maximum allowed volume.
		* @param currentVolume The current volume on the output.
		*/
		public VolumeProvider(int volumeControl, int maxVolume, int currentVolume) {
		public VolumeProvider(@ControlType int volumeControl, int maxVolume, int currentVolume) {
		mControlType = volumeControl;
		mMaxVolume = maxVolume;
		mCurrentVolume = currentVolume;
		@@ -72,6 +84,7 @@ public abstract class VolumeProvider {
		*
		* @return The volume control type for this volume provider
		*/
		@ControlType
		public final int getVolumeControl() {
		return mControlType;
		}

media/java/android/media/session/MediaSession.java

+1 −1

Original line number	Diff line number	Diff line
		@@ -469,7 +469,7 @@ public final class MediaSession {
		* <li>{@link Rating#RATING_THUMB_UP_DOWN}</li>
		* </ul>
		*/
		public void setRatingType(int type) {
		public void setRatingType(@Rating.Style int type) {
		try {
		mBinder.setRatingType(type);
		} catch (RemoteException e) {