| /* |
| * 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.content.Intent; |
| import android.net.Uri; |
| |
| /** |
| * Constants for media control intents. |
| * <p> |
| * This class declares a set of standard media control intent categories and actions that |
| * applications can use to identify the capabilities of media routes and control them. |
| * </p> |
| * |
| * <h3>Media control intent categories</h3> |
| * <p> |
| * Media control intent categories specify means by which applications can |
| * send media to the destination of a media route. Categories are sometimes referred |
| * to as describing "types" or "kinds" of routes. |
| * </p><p> |
| * For example, if a route supports the {@link #CATEGORY_REMOTE_PLAYBACK remote playback category}, |
| * then an application can ask it to play media remotely by sending a {@link #ACTION_PLAY play} |
| * intent with the Uri of the media content to play. Such a route may then be referred to as |
| * a "remote playback route" because it supports remote playback requests. It is common |
| * for a route to support multiple categories of requests at the same time, such as |
| * live audio and live video. |
| * </p><p> |
| * The following standard route categories are defined. |
| * </p><ul> |
| * <li>{@link #CATEGORY_LIVE_AUDIO Live audio}: The route supports streaming live audio |
| * from the device to the destination. Live audio routes include local speakers |
| * and Bluetooth headsets. |
| * <li>{@link #CATEGORY_LIVE_VIDEO Live video}: The route supports streaming live video |
| * from the device to the destination. Live video routes include local displays |
| * and wireless displays that support mirroring and |
| * {@link android.app.Presentation presentations}. Live video routes typically also |
| * support live audio capabilities. |
| * <li>{@link #CATEGORY_REMOTE_PLAYBACK Remote playback}: The route supports sending |
| * remote playback requests for media content to the destination. The content to be |
| * played is identified by a Uri and mime-type. |
| * </ul><p> |
| * Media route providers may define custom media control intent categories of their own in |
| * addition to the standard ones. Custom categories can be used to provide a variety |
| * of features to applications that recognize and know how to use them. For example, |
| * a media route provider might define a custom category to indicate that its routes |
| * support a special device-specific control interface in addition to other |
| * standard features. |
| * </p><p> |
| * Applications can determine which categories a route supports by using the |
| * {@link MediaRouter.RouteInfo#supportsControlCategory MediaRouter.RouteInfo.supportsControlCategory} |
| * or {@link MediaRouter.RouteInfo#getControlFilters MediaRouter.RouteInfo.getControlFilters} |
| * methods. Applications can also specify the types of routes that they want to use by |
| * creating {@link MediaRouteSelector media route selectors} that contain the desired |
| * categories and are used to filter routes in several parts of the media router API. |
| * </p> |
| * |
| * <h3>Media control intent actions</h3> |
| * <p> |
| * Media control intent actions specify particular functions that applications |
| * can ask the destination of a media route to perform. Media route control requests |
| * take the form of intents in a similar manner to other intents used to start activities |
| * or send broadcasts. The difference is that media control intents are directed to |
| * routes rather than activity or broadcast receiver components. |
| * </p><p> |
| * Each media route control intent specifies an action, a category and some number of parameters |
| * that are supplied as extras. Applications send media control requests to routes using the |
| * {@link MediaRouter.RouteInfo#sendControlRequest MediaRouter.RouteInfo.sendControlRequest} |
| * method and receive results via a callback. |
| * </p><p> |
| * All media control intent actions are associated with the media control intent categories |
| * that support them. Thus only remote playback routes may perform remote playback actions. |
| * The documentation of each action specifies the category to which the action belongs, |
| * the parameters it requires, and the results it returns. |
| * </p> |
| * |
| * <h3>Live audio and live video routes</h3> |
| * <p> |
| * {@link #CATEGORY_LIVE_AUDIO Live audio} and {@link #CATEGORY_LIVE_VIDEO live video} |
| * routes present media using standard system interfaces such as audio streams, |
| * {@link android.app.Presentation presentations} or display mirroring. These routes are |
| * the easiest to use because applications simply render content locally on the device |
| * and the system streams it to the route destination automatically. |
| * </p><p> |
| * In most cases, applications can stream content to live audio and live video routes in |
| * the same way they would play the content locally without any modification. However, |
| * applications may also be able to take advantage of more sophisticated features such |
| * as second-screen presentation APIs that are particular to these routes. |
| * </p> |
| * |
| * <h3>Remote playback routes</h3> |
| * <p> |
| * Remote playback routes present media remotely by playing content from a Uri. |
| * These routes destinations take responsibility for fetching and rendering content |
| * on their own. Applications do not render the content themselves; instead, applications |
| * send control requests to initiate play, pause, resume, or stop media items and receive |
| * status updates as they change state. |
| * </p> |
| * |
| * <h4>Sessions</h4> |
| * <p> |
| * Each remote media playback action is conducted within the scope of a session. |
| * Sessions are used to prevent applications from accidentally interfering with one |
| * another because at most one session can be valid at a time. |
| * </p><p> |
| * Some actions have the side-effect of creating new sessions. If an application |
| * performs an action that has the effect of creating a new session then |
| * the previous session is invalidated and any ongoing media playback is stopped |
| * before the requested action is performed. Any attempt to use an invalidated |
| * session will result in an error. (Protocol implementations are encouraged to |
| * aggressively discard any information associated with invalidated sessions.) |
| * </p><p> |
| * A session is implicitly created when an application issues a |
| * {@link #ACTION_PLAY play action} without specifying an existing session id as a parameter. |
| * When this happens, any previous session is invalidated and the play action |
| * returns a new session id that may be used to control the session with subsequent |
| * actions such as pause, resume, or stop. |
| * </p> |
| * |
| * <h4>Media items</h4> |
| * <p> |
| * Each successful {@link #ACTION_PLAY play action} returns a unique media item id that |
| * an application can use to monitor and control playback. The media item id may be passed |
| * to other actions such as {@link #ACTION_SEEK seek} or |
| * {@link #ACTION_GET_STATUS get status}. It will also appear as a parameter in |
| * status update broadcasts to identify the associated playback request. |
| * </p><p> |
| * Each media item is scoped to the session in which it was created. Therefore media item |
| * ids are only ever used together with session ids. Media item ids are meaningless |
| * on their own. When the session is invalidated, all of its media items are also |
| * invalidated. |
| * </p> |
| * |
| * <h4>The playback queue</h4> |
| * <p> |
| * Each session has its own playback queue that consists of the media items that |
| * are pending, playing, buffering or paused. Items are added to the queue when |
| * a playback request is issued. Items are removed from the queue when they are no |
| * longer eligible for playback (enter terminal states). |
| * </p><p> |
| * As described in the {@link MediaItemStatus} class, media items initially |
| * start in a pending state, transition to the playing (or buffering or paused) state |
| * during playback, and end in a finished, canceled, invalidated or error state. |
| * Once the current item enters a terminal state, playback proceeds on to the |
| * next item. |
| * </p><p> |
| * In the current version of the protocol, the queue may contain at most one item. |
| * Each play action has the effect of clearing the queue and resetting its state |
| * before the next item is played. |
| * </p> |
| * |
| * <h4>Impact of pause, resume, stop and play actions on the playback queue</h4> |
| * <p> |
| * The pause, resume and stop actions affect the session's whole queue. Pause causes |
| * the playback queue to be suspended no matter which item is currently playing. |
| * Resume reverses the effects of pause. Stop clears the queue and also resets |
| * the pause flag just like resume. |
| * </p><p> |
| * As described earlier, the play action has the effect of clearing the queue |
| * and completely resetting its state (like the stop action) then enqueuing a |
| * new media item to be played immediately. Play is therefore equivalent |
| * to stop followed by an action to enqueue an item. |
| * </p><p> |
| * The play action is also special in that it can be used to create new sessions. |
| * An application with simple needs may find that it only needs to use play |
| * (and occasionally stop) to control playback. |
| * </p> |
| * |
| * <h4>Resolving conflicts between applications</h4> |
| * <p> |
| * When an application has a valid session, it is essentially in control of remote playback |
| * on the route. No other application can view or modify the remote playback state |
| * of that applicaton's session without knowing its id. |
| * </p><p> |
| * However, other applications can perform actions that have the effect of stopping |
| * playback and invalidating the current session. When this occurs, the former application |
| * will be informed that it has lost control by way of individual media item status |
| * update broadcasts that indicate that its queued media items have become |
| * {@link MediaItemStatus#PLAYBACK_STATE_INVALIDATED invalidated}. This broadcast |
| * implies that playback was terminated abnormally by an external cause. |
| * </p><p> |
| * Applications should handle conflicts conservatively to allow other applications to |
| * smoothly assume control over the route. When a conflict occurs, the currently playing |
| * application should release its session and allow the new application to use the |
| * route until such time as the user intervenes to take over the route again and begin |
| * a new playback session. |
| * </p> |
| * |
| * <h4>Actions</h4> |
| * <p> |
| * The following remote playback actions are defined: |
| * </p><ul> |
| * <li>{@link #ACTION_PLAY Play}: Starts playing content specified by a given Uri |
| * and returns a new media item id to describe the request. Implicitly creates a new |
| * session if no session id was specified as a parameter. |
| * <li>{@link #ACTION_SEEK Seek}: Sets the content playback position of a specific media item. |
| * <li>{@link #ACTION_GET_STATUS Get status}: Gets the status of a media item |
| * including the item's current playback position and progress. |
| * <li>{@link #ACTION_PAUSE Pause}: Pauses playback of the queue. |
| * <li>{@link #ACTION_RESUME Resume}: Resumes playback of the queue. |
| * <li>{@link #ACTION_STOP Stop}: Stops playback, clears the queue, and resets the |
| * pause state. |
| * </ul> |
| * |
| * <h4>Implementation note</h4> |
| * <p> |
| * Implementations of the remote playback protocol must implement <em>all</em> of the |
| * documented actions, parameters and results. Note that the documentation is written from |
| * the perspective of a client of the protocol. In particular, whenever a parameter |
| * is described as being "optional", it is only from the perspective of the client. |
| * Compliant media route provider implementations of this protocol must support all |
| * of the features described herein. |
| * </p> |
| */ |
| public final class MediaControlIntent { |
| /** |
| * Media control category: Live audio. |
| * <p> |
| * A route that supports live audio routing will allow the media audio stream |
| * to be sent to supported destinations. This can include internal speakers or |
| * audio jacks on the device itself, A2DP devices, and more. |
| * </p><p> |
| * When a live audio route is selected, audio routing is transparent to the application. |
| * All audio played on the media stream will be routed to the selected destination. |
| * </p> |
| */ |
| public static final String CATEGORY_LIVE_AUDIO = "android.media.intent.category.LIVE_AUDIO"; |
| |
| /** |
| * Media control category: Live video. |
| * <p> |
| * A route that supports live video routing will allow a mirrored version |
| * of the device's primary display or a customized |
| * {@link android.app.Presentation Presentation} to be sent to supported |
| * destinations. |
| * </p><p> |
| * When a live video route is selected, audio and video routing is transparent |
| * to the application. By default, audio and video is routed to the selected |
| * destination. For certain live video routes, the application may also use a |
| * {@link android.app.Presentation Presentation} to replace the mirrored view |
| * on the external display with different content. |
| * </p> |
| * |
| * @see MediaRouter.RouteInfo#getPresentationDisplay() |
| * @see android.app.Presentation |
| */ |
| public static final String CATEGORY_LIVE_VIDEO = "android.media.intent.category.LIVE_VIDEO"; |
| |
| /** |
| * Media control category: Remote playback. |
| * <p> |
| * A route that supports remote playback routing will allow an application to send |
| * requests to play content remotely to supported destinations. |
| * </p><p> |
| * Remote playback routes destinations operate independently of the local device. |
| * When a remote playback route is selected, the application can control the content |
| * playing on the destination by sending media control actions to the route. |
| * The application may also receive status updates from the route regarding |
| * remote playback. |
| * </p> |
| * |
| * @see MediaRouter.RouteInfo#sendControlRequest |
| */ |
| public static final String CATEGORY_REMOTE_PLAYBACK = |
| "android.media.intent.category.REMOTE_PLAYBACK"; |
| |
| /* Remote playback actions that affect individual items. */ |
| |
| /** |
| * Remote playback media control action: Play media item. |
| * <p> |
| * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} |
| * media control. |
| * </p><p> |
| * This action causes a remote playback route to start playing content with |
| * the {@link Uri} specified in the {@link Intent}'s {@link Intent#getData() data uri}. |
| * The action returns a media session id and media item id which can be used |
| * to control playback using other remote playback actions. |
| * </p><p> |
| * Once initiated, playback of the specified content will be managed independently |
| * by the destination. The application will receive status updates as the state |
| * of the media item changes. |
| * </p><p> |
| * If the data uri specifies an HTTP or HTTPS scheme, then the destination is |
| * responsible for following HTTP redirects to a reasonable depth of at least 3 |
| * levels as might typically be handled by a web browser. If an HTTP error |
| * occurs, then the destination should send a {@link MediaItemStatus status update} |
| * back to the client indicating the {@link MediaItemStatus#PLAYBACK_STATE_ERROR error} |
| * {@link MediaItemStatus#getPlaybackState() playback state}. |
| * </p> |
| * |
| * <h3>One item at a time</h3> |
| * <p> |
| * Each successful play action <em>replaces</em> the previous play action. |
| * If an item is already playing, then it is canceled, the session's playback queue |
| * is cleared and the new item begins playing immediately (regardless of |
| * whether the previously playing item had been paused). |
| * </p><p> |
| * Play is therefore equivalent to {@link #ACTION_STOP stop} followed by an action |
| * to enqueue a new media item to be played immediately. |
| * </p> |
| * |
| * <h3>Sessions</h3> |
| * <p> |
| * This request has the effect of implicitly creating a media session whenever the |
| * application does not specify the {@link #EXTRA_SESSION_ID session id} parameter. |
| * Because there can only be at most one valid session at a time, creating a new session |
| * has the side-effect of invalidating any existing sessions and their media items, |
| * then handling the playback request with a new session. |
| * </p><p> |
| * If the application specifies an invalid session id, then an error is returned. |
| * When this happens, the application should assume that its session |
| * is no longer valid. To obtain a new session, the application may try again |
| * and omit the session id parameter. However, the application should |
| * only retry requests due to an explicit action performed by the user, |
| * such as the user clicking on a "play" button in the UI, since another |
| * application may be trying to take control of the route and the former |
| * application should try to stay out of its way. |
| * </p><p> |
| * For more information on sessions, queues and media items, please refer to the |
| * class documentation. |
| * </p> |
| * |
| * <h3>Request parameters</h3> |
| * <ul> |
| * <li>{@link #EXTRA_SESSION_ID} <em>(optional)</em>: Specifies the session id of the |
| * session to which the playback request belongs. If omitted, a new session |
| * is created implicitly. |
| * <li>{@link #EXTRA_ITEM_CONTENT_POSITION} <em>(optional)</em>: Specifies the initial |
| * content playback position as a long integer number of milliseconds from |
| * the beginning of the content. |
| * <li>{@link #EXTRA_ITEM_METADATA} <em>(optional)</em>: Specifies metadata associated |
| * with the content such as the title of a song. |
| * <li>{@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER} <em>(optional)</em>: Specifies a |
| * {@link PendingIntent} for a broadcast receiver that will receive status updates |
| * about the media item. |
| * </ul> |
| * |
| * <h3>Result data</h3> |
| * <ul> |
| * <li>{@link #EXTRA_SESSION_ID} <em>(always returned)</em>: Specifies the session id of the |
| * session that was affected by the request. This will be a new session in |
| * the case where no session id was supplied as a parameter. |
| * <li>{@link #EXTRA_ITEM_ID} <em>(always returned)</em>: Specifies an opaque string identifier |
| * to use to refer to the media item in subsequent requests such as |
| * {@link #ACTION_GET_STATUS}. |
| * <li>{@link #EXTRA_ITEM_STATUS} <em>(always returned)</em>: Specifies the initial status of |
| * the new media item. |
| * </ul> |
| * |
| * <h3>Status updates</h3> |
| * <p> |
| * If the client supplies a {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER status update receiver} |
| * then the media route provider is responsible for sending status updates to the receiver |
| * when significant media item state changes occur such as when playback starts or |
| * stops. The receiver will not be invoked for content playback position changes. |
| * The application may retrieve the current playback position when necessary |
| * using the {@link #ACTION_GET_STATUS} request. |
| * </p><p> |
| * Refer to {@link MediaItemStatus} for details. |
| * </p> |
| * |
| * <h3>Errors</h3> |
| * <p> |
| * This action returns an error if a session id was provided but is unknown or |
| * no longer valid, if the item Uri or content type is not supported, or if |
| * any other arguments are invalid. |
| * </p> |
| * |
| * <h3>Example</h3> |
| * <pre> |
| * MediaRouter mediaRouter = MediaRouter.getInstance(context); |
| * MediaRouter.RouteInfo route = mediaRouter.getSelectedRoute(); |
| * Intent intent = new Intent(MediaControlIntent.ACTION_PLAY); |
| * intent.addCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK); |
| * intent.setDataAndType("http://example.com/videos/movie.mp4", "video/mp4"); |
| * if (route.supportsControlRequest(intent)) { |
| * MediaRouter.ControlRequestCallback callback = new MediaRouter.ControlRequestCallback() { |
| * public void onResult(Bundle data) { |
| * // The request succeeded. |
| * // Playback may be controlled using the returned session and item id. |
| * String sessionId = data.getString(MediaControlIntent.EXTRA_SESSION_ID); |
| * String itemId = data.getString(MediaControlIntent.EXTRA_ITEM_ID); |
| * MediaItemStatus status = MediaItemStatus.fromBundle(data.getBundle( |
| * MediaControlIntent.EXTRA_ITEM_STATUS)); |
| * // ... |
| * } |
| * |
| * public void onError(String message, Bundle data) { |
| * // An error occurred! |
| * } |
| * }; |
| * route.sendControlRequest(intent, callback); |
| * }</pre> |
| * |
| * @see MediaRouter.RouteInfo#sendControlRequest |
| * @see #CATEGORY_REMOTE_PLAYBACK |
| * @see #ACTION_SEEK |
| * @see #ACTION_GET_STATUS |
| * @see #ACTION_PAUSE |
| * @see #ACTION_RESUME |
| * @see #ACTION_STOP |
| */ |
| public static final String ACTION_PLAY = "android.media.intent.action.PLAY"; |
| |
| /** |
| * Remote playback media control action: Enqueue media item. |
| * <p> |
| * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} |
| * media control. |
| * </p><p> |
| * This action works just like {@link #ACTION_PLAY play} except that it does |
| * not clear the queue or reset the pause state when it enqueues the |
| * new media item into the session's playback queue. This action only |
| * enqueues a media item with no other side-effects on the queue. |
| * </p><p> |
| * If the queue is currently empty and then the item will play immediately |
| * (assuming the queue is not paused). Otherwise, the item will play |
| * after all earlier items in the queue have finished or been removed. |
| * </p><p> |
| * The enqueue action can be used to create new sessions just like play. |
| * Its parameters and results are also the same. Only the queuing behavior |
| * is different. |
| * </p> |
| * |
| * @see #ACTION_PLAY |
| * |
| * @hide Pending API review. |
| */ |
| public static final String ACTION_ENQUEUE = "android.media.intent.action.ENQUEUE"; |
| |
| /** |
| * Remote playback media control action: Seek media item to a new playback position. |
| * <p> |
| * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} |
| * media control. |
| * </p><p> |
| * This action causes a remote playback route to modify the current playback position |
| * of the specified media item. |
| * </p><p> |
| * This action only affects the playback position of the media item; not its playback state. |
| * If the playback queue is paused, then seeking sets the position but the item |
| * remains paused. Likewise if the item is playing, then seeking will cause playback |
| * to jump to the new position and continue playing from that point. If the item has |
| * not yet started playing, then the new playback position is remembered by the |
| * queue and used as the item's initial content position when playback eventually begins. |
| * </p><p> |
| * If successful, the media item's playback position is changed. |
| * </p> |
| * |
| * <h3>Request parameters</h3> |
| * <ul> |
| * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of the session |
| * to which the media item belongs. |
| * <li>{@link #EXTRA_ITEM_ID} <em>(required)</em>: Specifies the media item id of |
| * the media item to seek. |
| * <li>{@link #EXTRA_ITEM_CONTENT_POSITION} <em>(required)</em>: Specifies the new |
| * content position for playback as a long integer number of milliseconds from |
| * the beginning of the content. |
| * </ul> |
| * |
| * <h3>Result data</h3> |
| * <ul> |
| * <li>{@link #EXTRA_ITEM_STATUS} <em>(always returned)</em>: Specifies the new status of |
| * the media item. |
| * </ul> |
| * |
| * <h3>Errors</h3> |
| * <p> |
| * This action returns an error if the session id or media item id are unknown |
| * or no longer valid, if the content position is invalid, or if the media item |
| * is in a terminal state. |
| * </p> |
| * |
| * @see MediaRouter.RouteInfo#sendControlRequest |
| * @see #CATEGORY_REMOTE_PLAYBACK |
| */ |
| public static final String ACTION_SEEK = "android.media.intent.action.SEEK"; |
| |
| /** |
| * Remote playback media control action: Get media item playback status |
| * and progress information. |
| * <p> |
| * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} |
| * media control. |
| * </p><p> |
| * This action asks a remote playback route to provide updated playback status and progress |
| * information about the specified media item. |
| * </p> |
| * |
| * <h3>Request parameters</h3> |
| * <ul> |
| * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of the session |
| * to which the media item belongs. |
| * <li>{@link #EXTRA_ITEM_ID} <em>(required)</em>: Specifies the media item id of |
| * the media item to query. |
| * </ul> |
| * |
| * <h3>Result data</h3> |
| * <ul> |
| * <li>{@link #EXTRA_ITEM_STATUS} <em>(always returned)</em>: Specifies the current status of |
| * the media item. |
| * </ul> |
| * |
| * <h3>Errors</h3> |
| * <p> |
| * This action returns an error if the session id or media item id are unknown |
| * or no longer valid. |
| * </p> |
| * |
| * @see MediaRouter.RouteInfo#sendControlRequest |
| * @see #CATEGORY_REMOTE_PLAYBACK |
| * @see #EXTRA_ITEM_STATUS_UPDATE_RECEIVER |
| */ |
| public static final String ACTION_GET_STATUS = "android.media.intent.action.GET_STATUS"; |
| |
| /** |
| * Remote playback media control action: Remove media item from session's queue. |
| * <p> |
| * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} |
| * media control. |
| * </p><p> |
| * This action asks a remote playback route to remove the specified media item |
| * from the session's playback queue. If the current item is removed, then |
| * playback will proceed to the next media item (assuming the queue has not been |
| * paused). |
| * </p><p> |
| * This action does not affect the pause state of the queue. If the queue was paused |
| * then it remains paused (even if it is now empty) until a resume, stop or play |
| * action is issued that causes the pause state to be cleared. |
| * </p> |
| * |
| * <h3>Request parameters</h3> |
| * <ul> |
| * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of the session |
| * to which the media item belongs. |
| * <li>{@link #EXTRA_ITEM_ID} <em>(required)</em>: Specifies the media item id of |
| * the media item to remove. |
| * </ul> |
| * |
| * <h3>Result data</h3> |
| * <ul> |
| * <li>{@link #EXTRA_ITEM_STATUS} <em>(always returned)</em>: Specifies the new status of |
| * the media item. |
| * </ul> |
| * |
| * <h3>Errors</h3> |
| * <p> |
| * This action returns an error if the session id or media item id are unknown |
| * or no longer valid, or if the media item is in a terminal state (and therefore |
| * no longer in the queue). |
| * </p> |
| * |
| * @see MediaRouter.RouteInfo#sendControlRequest |
| * @see #CATEGORY_REMOTE_PLAYBACK |
| * |
| * @hide Pending API review. |
| */ |
| public static final String ACTION_REMOVE = "android.media.intent.action.REMOVE"; |
| |
| /* Remote playback actions that affect the whole playback queue. */ |
| |
| /** |
| * Remote playback media control action: Pause media playback. |
| * <p> |
| * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} |
| * media control. |
| * </p><p> |
| * This action causes the playback queue of the specified session to be paused. |
| * </p> |
| * |
| * <h3>Request parameters</h3> |
| * <ul> |
| * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of the session |
| * whose playback queue is to be paused. |
| * </ul> |
| * |
| * <h3>Result data</h3> |
| * <ul> |
| * <li><em>None</em> |
| * </ul> |
| * |
| * <h3>Errors</h3> |
| * <p> |
| * This action returns an error if the session id is unknown or no longer valid. |
| * </p> |
| * |
| * @see MediaRouter.RouteInfo#sendControlRequest |
| * @see #CATEGORY_REMOTE_PLAYBACK |
| * @see #ACTION_RESUME |
| */ |
| public static final String ACTION_PAUSE = "android.media.intent.action.PAUSE"; |
| |
| /** |
| * Remote playback media control action: Resume media playback (unpause). |
| * <p> |
| * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} |
| * media control. |
| * </p><p> |
| * This action causes the playback queue of the specified session to be resumed. |
| * Reverses the effects of {@link #ACTION_PAUSE}. |
| * </p> |
| * |
| * <h3>Request parameters</h3> |
| * <ul> |
| * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of the session |
| * whose playback queue is to be resumed. |
| * </ul> |
| * |
| * <h3>Result data</h3> |
| * <ul> |
| * <li><em>None</em> |
| * </ul> |
| * |
| * <h3>Errors</h3> |
| * <p> |
| * This action returns an error if the session id is unknown or no longer valid. |
| * </p> |
| * |
| * @see MediaRouter.RouteInfo#sendControlRequest |
| * @see #CATEGORY_REMOTE_PLAYBACK |
| * @see #ACTION_PAUSE |
| */ |
| public static final String ACTION_RESUME = "android.media.intent.action.RESUME"; |
| |
| /** |
| * Remote playback media control action: Stop media playback (clear queue and unpause). |
| * <p> |
| * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} |
| * media control. |
| * </p><p> |
| * This action causes a remote playback route to stop playback, cancel and remove |
| * all media items from the session's media item queue and, reset the queue's |
| * pause state. |
| * </p><p> |
| * If successful, the status of all media items in the queue is set to |
| * {@link MediaItemStatus#PLAYBACK_STATE_CANCELED canceled} and a status update is sent |
| * to the appropriate status update receivers indicating the new status of each item. |
| * </p> |
| * |
| * <h3>Request parameters</h3> |
| * <ul> |
| * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of |
| * the session whose playback queue is to be stopped (cleared and unpaused). |
| * </ul> |
| * |
| * <h3>Result data</h3> |
| * <ul> |
| * <li><em>None</em> |
| * </ul> |
| * |
| * <h3>Errors</h3> |
| * <p> |
| * This action returns an error if the session id is unknown or no longer valid. |
| * </p> |
| * |
| * @see MediaRouter.RouteInfo#sendControlRequest |
| * @see #CATEGORY_REMOTE_PLAYBACK |
| */ |
| public static final String ACTION_STOP = "android.media.intent.action.STOP"; |
| |
| /** |
| * Bundle extra: Media session id. |
| * <p> |
| * An opaque unique identifier that identifies the remote playback media session. |
| * The session id is returned by {@link #ACTION_PLAY} along with the media item id |
| * of the requested content. |
| * </p><p> |
| * Used with various actions to specify the id of the media session to be controlled. |
| * </p><p> |
| * Included in broadcast intents sent to |
| * {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER status update receivers} to identify |
| * the session to which the item in question belongs. |
| * </p><p> |
| * The value is a unique string value generated by the media route provider |
| * to represent one particular media session. |
| * </p> |
| * |
| * @see #ACTION_PLAY |
| * @see #ACTION_SEEK |
| * @see #ACTION_GET_STATUS |
| * @see #ACTION_PAUSE |
| * @see #ACTION_RESUME |
| * @see #ACTION_STOP |
| */ |
| public static final String EXTRA_SESSION_ID = |
| "android.media.intent.extra.SESSION_ID"; |
| |
| /** |
| * Bundle extra: Media item id. |
| * <p> |
| * An opaque unique identifier returned as a result from {@link #ACTION_PLAY} that |
| * represents the media item that was created by the playback request. |
| * </p><p> |
| * Used with various actions to specify the id of the media item to be controlled. |
| * </p><p> |
| * Included in broadcast intents sent to |
| * {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER status update receivers} to identify |
| * the item in question. |
| * </p><p> |
| * The value is a unique string value generated by the media route provider |
| * to represent one particular media item. |
| * </p> |
| * |
| * @see #ACTION_PLAY |
| * @see #ACTION_SEEK |
| * @see #ACTION_GET_STATUS |
| */ |
| public static final String EXTRA_ITEM_ID = |
| "android.media.intent.extra.ITEM_ID"; |
| |
| /** |
| * Bundle extra: Media item status. |
| * <p> |
| * Returned as a result from media item actions such as {@link #ACTION_PLAY}, |
| * a{@link #ACTION_SEEK}, and {@link #ACTION_GET_STATUS} |
| * to describe the status of the specified media item. |
| * </p><p> |
| * Included in broadcast intents sent to |
| * {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER status update receivers} to provide |
| * updated status information. |
| * </p><p> |
| * The value is a {@link android.os.Bundle} of data that can be converted into |
| * a {@link MediaItemStatus} object using |
| * {@link MediaItemStatus#fromBundle MediaItemStatus.fromBundle}. |
| * </p> |
| * |
| * @see #ACTION_PLAY |
| * @see #ACTION_SEEK |
| * @see #ACTION_GET_STATUS |
| */ |
| public static final String EXTRA_ITEM_STATUS = |
| "android.media.intent.extra.ITEM_STATUS"; |
| |
| /** |
| * Long extra: Media item content position. |
| * <p> |
| * Used with {@link #ACTION_PLAY} to specify the starting playback position. |
| * </p><p> |
| * Used with {@link #ACTION_SEEK} to set a new playback position. |
| * </p><p> |
| * The value is a long integer number of milliseconds from the beginning of the content. |
| * <p> |
| * |
| * @see #ACTION_PLAY |
| * @see #ACTION_SEEK |
| */ |
| public static final String EXTRA_ITEM_CONTENT_POSITION = |
| "android.media.intent.extra.ITEM_POSITION"; |
| |
| /** |
| * Bundle extra: Media item metadata. |
| * <p> |
| * Used with {@link #ACTION_PLAY} to specify metadata associated with the content |
| * of a media item. |
| * </p><p> |
| * The value is a {@link android.os.Bundle} of metadata key-value pairs as defined |
| * in {@link MediaItemMetadata}. |
| * </p> |
| * |
| * @see #ACTION_PLAY |
| */ |
| public static final String EXTRA_ITEM_METADATA = |
| "android.media.intent.extra.ITEM_METADATA"; |
| |
| /** |
| * Bundle extra: HTTP request headers. |
| * <p> |
| * Used with {@link #ACTION_PLAY} to specify HTTP request headers to be |
| * included when fetching to the content indicated by the media item's data Uri. |
| * </p><p> |
| * This extra may be used to provide authentication tokens and other |
| * parameters to the server separately from the media item's data Uri. |
| * </p><p> |
| * The value is a {@link android.os.Bundle} of string based key-value pairs |
| * that describe the HTTP request headers. |
| * </p> |
| * |
| * @see #ACTION_PLAY |
| * |
| * @hide Pending API review. |
| */ |
| public static final String EXTRA_ITEM_HTTP_HEADERS = |
| "android.media.intent.extra.HTTP_HEADERS"; |
| |
| /** |
| * Bundle extra: Media item status update receiver. |
| * <p> |
| * Used with {@link #ACTION_PLAY} to specify a {@link PendingIntent} for a |
| * broadcast receiver that will receive status updates about a particular |
| * media item. |
| * </p><p> |
| * Whenever the status of the media item changes, the media route provider will |
| * send a broadcast to the pending intent with extras that identify the queue |
| * to which the item belongs, the item itself and the item's updated status. |
| * </p><p> |
| * The same pending intent and broadcast receiver may be shared by any number of |
| * media items since the broadcast intent includes the media session id |
| * and media item id. |
| * </p><p> |
| * The value is a {@link PendingIntent}. |
| * </p> |
| * |
| * <h3>Broadcast extras</h3> |
| * <ul> |
| * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of |
| * the session to which the item in question belongs. |
| * <li>{@link #EXTRA_ITEM_ID} <em>(required)</em>: Specifies the media item id of the |
| * media item in question. |
| * <li>{@link #EXTRA_ITEM_STATUS} <em>(required)</em>: Specifies the status of the |
| * item as a bundle that can be decoded into a {@link MediaItemStatus} object. |
| * </ul> |
| * |
| * @see #ACTION_PLAY |
| */ |
| public static final String EXTRA_ITEM_STATUS_UPDATE_RECEIVER = |
| "android.media.intent.extra.ITEM_STATUS_UPDATE_RECEIVER"; |
| |
| private MediaControlIntent() { |
| } |
| } |
