Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "Annotate Media section of framework/base" into nyc-dev

Browse Source
This commit is contained in:
Insun Kang
2016-03-02 01:36:09 +00:00
committed by Android (Google) Code Review
parent de5ec832b1 7c090d54e2
commit 542221d68a
6 changed files with 141 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
media/java/android/media/MediaMetadata.java
View File

@@ -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

24
media/java/android/media/MediaRouter.java
View File

@@ -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);
}

28
media/java/android/media/Rating.java
View File

@@ -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;
}
@@ -285,4 +305,4 @@ public final class Rating implements Parcelable {
return mRatingValue;
}
}
}
}

17
media/java/android/media/VolumeProvider.java
View File

@@ -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;
}
@@ -145,4 +158,4 @@ public abstract class VolumeProvider {
public static abstract class Callback {
public abstract void onVolumeChanged(VolumeProvider volumeProvider);
}
}
}

2
media/java/android/media/session/MediaSession.java
View File

@@ -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) {

34
media/java/android/media/session/PlaybackState.java
View File

@@ -16,6 +16,7 @@
package android.media.session;
import android.annotation.DrawableRes;
import android.annotation.IntDef;
import android.annotation.Nullable;
import android.media.RemoteControlClient;
import android.os.Bundle;
@@ -26,6 +27,9 @@ import android.text.TextUtils;
import java.util.ArrayList;
import java.util.List;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
/**
* Playback state for a {@link MediaSession}. This includes a state like
* {@link PlaybackState#STATE_PLAYING}, the current playback position,
@@ -34,6 +38,17 @@ import java.util.List;
public final class PlaybackState implements Parcelable {
private static final String TAG = "PlaybackState";
/**
* @hide
*/
@IntDef(flag=true, value={ACTION_STOP, ACTION_PAUSE, ACTION_PLAY, ACTION_REWIND,
ACTION_SKIP_TO_PREVIOUS, ACTION_SKIP_TO_NEXT, ACTION_FAST_FORWARD, ACTION_SET_RATING,
ACTION_SEEK_TO, ACTION_PLAY_PAUSE, ACTION_PLAY_FROM_MEDIA_ID, ACTION_PLAY_FROM_SEARCH,
ACTION_SKIP_TO_QUEUE_ITEM, ACTION_PLAY_FROM_URI, ACTION_PREPARE,
ACTION_PREPARE_FROM_MEDIA_ID, ACTION_PREPARE_FROM_SEARCH, ACTION_PREPARE_FROM_URI})
@Retention(RetentionPolicy.SOURCE)
public @interface Actions {}
/**
* Indicates this session supports the stop command.
*
@@ -160,6 +175,15 @@ public final class PlaybackState implements Parcelable {
*/
public static final long ACTION_PREPARE_FROM_URI = 1 << 17;
/**
* @hide
*/
@IntDef({STATE_NONE, STATE_STOPPED, STATE_PAUSED, STATE_PLAYING, STATE_FAST_FORWARDING,
STATE_REWINDING, STATE_BUFFERING, STATE_ERROR, STATE_CONNECTING,
STATE_SKIPPING_TO_PREVIOUS, STATE_SKIPPING_TO_NEXT, STATE_SKIPPING_TO_QUEUE_ITEM})
@Retention(RetentionPolicy.SOURCE)
public @interface State {}
/**
* This is the default playback state and indicates that no media has been
* added yet, or the performer has been reset and has no content to play.
@@ -349,9 +373,11 @@ public final class PlaybackState implements Parcelable {
* <li> {@link PlaybackState#STATE_SKIPPING_TO_QUEUE_ITEM}</li>
* </ul>
*/
@State
public int getState() {
return mState;
}
/**
* Get the current playback position in ms.
*/
@@ -403,6 +429,7 @@ public final class PlaybackState implements Parcelable {
* <li> {@link PlaybackState#ACTION_PREPARE_FROM_URI}</li>
* </ul>
*/
@Actions
public long getActions() {
return mActions;
}
@@ -866,7 +893,8 @@ public final class PlaybackState implements Parcelable {
* timebase that the position was updated at.
* @return this
*/
public Builder setState(int state, long position, float playbackSpeed, long updateTime) {
public Builder setState(@State int state, long position, float playbackSpeed,
long updateTime) {
mState = state;
mPosition = position;
mUpdateTime = updateTime;
@@ -907,7 +935,7 @@ public final class PlaybackState implements Parcelable {
* normal playback.
* @return this
*/
public Builder setState(int state, long position, float playbackSpeed) {
public Builder setState(@State int state, long position, float playbackSpeed) {
return setState(state, position, playbackSpeed, SystemClock.elapsedRealtime());
}
@@ -938,7 +966,7 @@ public final class PlaybackState implements Parcelable {
* @param actions The set of actions allowed.
* @return this
*/
public Builder setActions(long actions) {
public Builder setActions(@Actions long actions) {
mActions = actions;
return this;
}