Java tutorial
/* * Copyright (C) 2013 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.support.v7.media; import android.app.PendingIntent; import android.os.Bundle; import android.os.SystemClock; import android.support.v4.util.TimeUtils; /** * Describes the playback status of a media item. * <p> * This class is part of the remote playback protocol described by the * {@link MediaControlIntent MediaControlIntent} class. * </p><p> * As a media item is played, it transitions through a sequence of states including: * {@link #PLAYBACK_STATE_PENDING pending}, {@link #PLAYBACK_STATE_BUFFERING buffering}, * {@link #PLAYBACK_STATE_PLAYING playing}, {@link #PLAYBACK_STATE_PAUSED paused}, * {@link #PLAYBACK_STATE_FINISHED finished}, {@link #PLAYBACK_STATE_CANCELED canceled}, * {@link #PLAYBACK_STATE_INVALIDATED invalidated}, and * {@link #PLAYBACK_STATE_ERROR error}. Refer to the documentation of each state * for an explanation of its meaning. * </p><p> * While the item is playing, the playback status may also include progress information * about the {@link #getContentPosition content position} and * {@link #getContentDuration content duration} although not all route destinations * will report it. * </p><p> * To monitor playback status, the application should supply a {@link PendingIntent} to use as the * {@link MediaControlIntent#EXTRA_ITEM_STATUS_UPDATE_RECEIVER item status update receiver} * for a given {@link MediaControlIntent#ACTION_PLAY playback request}. Note that * the status update receiver will only be invoked for major status changes such as a * transition from playing to finished. * </p><p class="note"> * The status update receiver will not be invoked for minor progress updates such as * changes to playback position or duration. If the application wants to monitor * playback progress, then it must use the * {@link MediaControlIntent#ACTION_GET_STATUS get status request} to poll for changes * periodically and estimate the playback position while playing. Note that there may * be a significant power impact to polling so the application is advised only * to poll when the screen is on and never more than about once every 5 seconds or so. * </p><p> * This object is immutable once created using a {@link Builder} instance. * </p> */ public final class MediaItemStatus { private static final String KEY_TIMESTAMP = "timestamp"; private static final String KEY_PLAYBACK_STATE = "playbackState"; private static final String KEY_CONTENT_POSITION = "contentPosition"; private static final String KEY_CONTENT_DURATION = "contentDuration"; private static final String KEY_EXTRAS = "extras"; private final Bundle mBundle; /** * Playback state: Pending. * <p> * Indicates that the media item has not yet started playback but will be played eventually. * </p> */ public static final int PLAYBACK_STATE_PENDING = 0; /** * Playback state: Playing. * <p> * Indicates that the media item is currently playing. * </p> */ public static final int PLAYBACK_STATE_PLAYING = 1; /** * Playback state: Paused. * <p> * Indicates that playback of the media item has been paused. Playback can be * resumed using the {@link MediaControlIntent#ACTION_RESUME resume} action. * </p> */ public static final int PLAYBACK_STATE_PAUSED = 2; /** * Playback state: Buffering or seeking to a new position. * <p> * Indicates that the media item has been temporarily interrupted * to fetch more content. Playback will continue automatically * when enough content has been buffered. * </p> */ public static final int PLAYBACK_STATE_BUFFERING = 3; /** * Playback state: Finished. * <p> * Indicates that the media item played to the end of the content and finished normally. * </p><p> * A finished media item cannot be resumed. To play the content again, the application * must send a new {@link MediaControlIntent#ACTION_PLAY play} or * {@link MediaControlIntent#ACTION_ENQUEUE enqueue} action. * </p> */ public static final int PLAYBACK_STATE_FINISHED = 4; /** * Playback state: Canceled. * <p> * Indicates that the media item was explicitly removed from the queue by the * application. Items may be canceled and removed from the queue using * the {@link MediaControlIntent#ACTION_REMOVE remove} or * {@link MediaControlIntent#ACTION_STOP stop} action or by issuing * another {@link MediaControlIntent#ACTION_PLAY play} action that has the * side-effect of clearing the queue. * </p><p> * A canceled media item cannot be resumed. To play the content again, the * application must send a new {@link MediaControlIntent#ACTION_PLAY play} or * {@link MediaControlIntent#ACTION_ENQUEUE enqueue} action. * </p> */ public static final int PLAYBACK_STATE_CANCELED = 5; /** * Playback state: Invalidated. * <p> * Indicates that the media item was invalidated permanently and involuntarily. * This state is used to indicate that the media item was invalidated and removed * from the queue because the session to which it belongs was invalidated * (typically by another application taking control of the route). * </p><p> * When invalidation occurs, the application should generally wait for the user * to perform an explicit action, such as clicking on a play button in the UI, * before creating a new media session to avoid unnecessarily interrupting * another application that may have just started using the route. * </p><p> * An invalidated media item cannot be resumed. To play the content again, the application * must send a new {@link MediaControlIntent#ACTION_PLAY play} or * {@link MediaControlIntent#ACTION_ENQUEUE enqueue} action. * </p> */ public static final int PLAYBACK_STATE_INVALIDATED = 6; /** * Playback state: Playback halted or aborted due to an error. * <p> * Examples of errors are no network connectivity when attempting to retrieve content * from a server, or expired user credentials when trying to play subscription-based * content. * </p><p> * A media item in the error state cannot be resumed. To play the content again, * the application must send a new {@link MediaControlIntent#ACTION_PLAY play} or * {@link MediaControlIntent#ACTION_ENQUEUE enqueue} action. * </p> */ public static final int PLAYBACK_STATE_ERROR = 7; /** * Integer extra: HTTP status code. * <p> * Specifies the HTTP status code that was encountered when the content * was requested after all redirects were followed. This key only needs to * specified when the content uri uses the HTTP or HTTPS scheme and an error * occurred. This key may be omitted if the content was able to be played * successfully; there is no need to report a 200 (OK) status code. * </p><p> * The value is an integer HTTP status code, such as 401 (Unauthorized), * 404 (Not Found), or 500 (Server Error), or 0 if none. * </p> */ public static final String EXTRA_HTTP_STATUS_CODE = "android.media.status.extra.HTTP_STATUS_CODE"; /** * Bundle extra: HTTP response headers. * <p> * Specifies the HTTP response headers that were returned when the content was * requested from the network. The headers may include additional information * about the content or any errors conditions that were encountered while * trying to fetch the content. * </p><p> * The value is a {@link android.os.Bundle} of string based key-value pairs * that describe the HTTP response headers. * </p> */ public static final String EXTRA_HTTP_RESPONSE_HEADERS = "android.media.status.extra.HTTP_RESPONSE_HEADERS"; private MediaItemStatus(Bundle bundle) { mBundle = bundle; } /** * Gets the timestamp associated with the status information in * milliseconds since boot in the {@link SystemClock#elapsedRealtime} time base. * * @return The status timestamp in the {@link SystemClock#elapsedRealtime()} time base. */ public long getTimestamp() { return mBundle.getLong(KEY_TIMESTAMP); } /** * Gets the playback state of the media item. * * @return The playback state. One of {@link #PLAYBACK_STATE_PENDING}, * {@link #PLAYBACK_STATE_PLAYING}, {@link #PLAYBACK_STATE_PAUSED}, * {@link #PLAYBACK_STATE_BUFFERING}, {@link #PLAYBACK_STATE_FINISHED}, * {@link #PLAYBACK_STATE_CANCELED}, {@link #PLAYBACK_STATE_INVALIDATED}, * or {@link #PLAYBACK_STATE_ERROR}. */ public int getPlaybackState() { return mBundle.getInt(KEY_PLAYBACK_STATE, PLAYBACK_STATE_ERROR); } /** * Gets the content playback position as a long integer number of milliseconds * from the beginning of the content. * * @return The content playback position in milliseconds, or -1 if unknown. */ public long getContentPosition() { return mBundle.getLong(KEY_CONTENT_POSITION, -1); } /** * Gets the total duration of the content to be played as a long integer number of * milliseconds. * * @return The content duration in milliseconds, or -1 if unknown. */ public long getContentDuration() { return mBundle.getLong(KEY_CONTENT_DURATION, -1); } /** * Gets a bundle of extras for this status object. * The extras will be ignored by the media router but they may be used * by applications. */ public Bundle getExtras() { return mBundle.getBundle(KEY_EXTRAS); } @Override public String toString() { StringBuilder result = new StringBuilder(); result.append("MediaItemStatus{ "); result.append("timestamp="); TimeUtils.formatDuration(SystemClock.elapsedRealtime() - getTimestamp(), result); result.append(" ms ago"); result.append(", playbackState=").append(playbackStateToString(getPlaybackState())); result.append(", contentPosition=").append(getContentPosition()); result.append(", contentDuration=").append(getContentDuration()); result.append(", extras=").append(getExtras()); result.append(" }"); return result.toString(); } private static String playbackStateToString(int playbackState) { switch (playbackState) { case PLAYBACK_STATE_PENDING: return "pending"; case PLAYBACK_STATE_BUFFERING: return "buffering"; case PLAYBACK_STATE_PLAYING: return "playing"; case PLAYBACK_STATE_PAUSED: return "paused"; case PLAYBACK_STATE_FINISHED: return "finished"; case PLAYBACK_STATE_CANCELED: return "canceled"; case PLAYBACK_STATE_INVALIDATED: return "invalidated"; case PLAYBACK_STATE_ERROR: return "error"; } return Integer.toString(playbackState); } /** * Converts this object to a bundle for serialization. * * @return The contents of the object represented as a bundle. */ public Bundle asBundle() { return mBundle; } /** * Creates an instance from a bundle. * * @param bundle The bundle, or null if none. * @return The new instance, or null if the bundle was null. */ public static MediaItemStatus fromBundle(Bundle bundle) { return bundle != null ? new MediaItemStatus(bundle) : null; } /** * Builder for {@link MediaItemStatus media item status objects}. */ public static final class Builder { private final Bundle mBundle; /** * Creates a media item status builder using the current time as the * reference timestamp. * * @param playbackState The item playback state. */ public Builder(int playbackState) { mBundle = new Bundle(); setTimestamp(SystemClock.elapsedRealtime()); setPlaybackState(playbackState); } /** * Creates a media item status builder whose initial contents are * copied from an existing status. */ public Builder(MediaItemStatus status) { if (status == null) { throw new IllegalArgumentException("status must not be null"); } mBundle = new Bundle(status.mBundle); } /** * Sets the timestamp associated with the status information in * milliseconds since boot in the {@link SystemClock#elapsedRealtime} time base. */ public Builder setTimestamp(long elapsedRealtimeTimestamp) { mBundle.putLong(KEY_TIMESTAMP, elapsedRealtimeTimestamp); return this; } /** * Sets the playback state of the media item. */ public Builder setPlaybackState(int playbackState) { mBundle.putInt(KEY_PLAYBACK_STATE, playbackState); return this; } /** * Sets the content playback position as a long integer number of milliseconds * from the beginning of the content. */ public Builder setContentPosition(long positionMilliseconds) { mBundle.putLong(KEY_CONTENT_POSITION, positionMilliseconds); return this; } /** * Sets the total duration of the content to be played as a long integer number * of milliseconds. */ public Builder setContentDuration(long durationMilliseconds) { mBundle.putLong(KEY_CONTENT_DURATION, durationMilliseconds); return this; } /** * Sets a bundle of extras for this status object. * The extras will be ignored by the media router but they may be used * by applications. */ public Builder setExtras(Bundle extras) { mBundle.putBundle(KEY_EXTRAS, extras); return this; } /** * Builds the {@link MediaItemStatus media item status object}. */ public MediaItemStatus build() { return new MediaItemStatus(mBundle); } } }