/* * 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. *

* 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. *

* *

Media control intent categories

*

* 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. *

* 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} or {@link #ACTION_ENQUEUE enqueue} 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. *

* The following standard route categories are defined. *

* 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. *

* 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. *

* *

Media control intent actions

*

* 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. *

* 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. *

* 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. *

* *

Live audio and live video routes

*

* {@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. *

* 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. *

* *

Remote playback routes

*

* {@link #CATEGORY_REMOTE_PLAYBACK 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. *

* *

Sessions

*

* 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. *

* A session can be created using the {@link #ACTION_START_SESSION start session action} * and terminated using the {@link #ACTION_END_SESSION end session action} when the * route provides explicit session management features. *

* Explicit session management was added in a later revision of the protocol so not * all routes support it. If the route does not support explicit session management * then implicit session management may still be used. Implicit session management * relies on the use of the {@link #ACTION_PLAY play} and {@link #ACTION_ENQUEUE enqueue} * actions which have the side-effect of creating a new session if none is provided * as argument. *

* When a new session is created, 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 information associated with invalidated sessions * since it is no longer of use.) *

* Each session is identified by a unique session id that may be used to control * the session using actions such as pause, resume, stop and end session. *

* *

Media items

*

* Each successful {@link #ACTION_PLAY play} or {@link #ACTION_ENQUEUE enqueue} 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. *

* 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. *

* *

The playback queue

*

* 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). *

* 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. *

* The application should determine whether the route supports queuing by checking * whether the {@link #ACTION_ENQUEUE} action is declared in the route's control filter * using {@link MediaRouter.RouteInfo#supportsControlRequest RouteInfo.supportsControlRequest}. *

* If the {@link #ACTION_ENQUEUE} action is supported by the route, then the route promises * to allow at least two items (possibly more) to be enqueued at a time. Enqueued items play * back to back one after the other as the previous item completes. Ideally there should * be no audible pause between items for standard audio content types. *

* If the {@link #ACTION_ENQUEUE} action is not supported by the route, then the queue * effectively contains at most one item at a time. Each play action has the effect of * clearing the queue and resetting its state before the next item is played. *

* *

Impact of pause, resume, stop and play actions on the playback queue

*

* 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. *

* 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. *

* 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. *

* *

Resolving conflicts between applications

*

* 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. *

* 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. *

* 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. *

* *

Basic actions

*

* The following basic actions must be supported (all or nothing) by all remote * playback routes. These actions form the basis of the remote playback protocol * and are required in all implementations. *

* *

Queue actions

*

* The following queue actions must be supported (all or nothing) by remote * playback routes that offer optional queuing capabilities. *

* *

Session actions

*

* The following session actions must be supported (all or nothing) by remote * playback routes that offer optional session management capabilities. *

* *

Implementation note

*

* Implementations of the remote playback protocol must implement all 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. *

*/ public final class MediaControlIntent { /* Route categories. */ /** * Media control category: Live audio. *

* 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. *

* 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. *

* Refer to the class documentation for details about live audio routes. *

*/ public static final String CATEGORY_LIVE_AUDIO = "android.media.intent.category.LIVE_AUDIO"; /** * Media control category: Live video. *

* 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. *

* 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. *

* Refer to the class documentation for details about live video routes. *

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

* A route that supports remote playback routing will allow an application to send * requests to play content remotely to supported destinations. *

* 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. *

* Refer to the class documentation for details about remote playback routes. *

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

* Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} * media control. *

* 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. *

* 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. *

* 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}. *

* *

One item at a time

*

* Each successful play action replaces 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). *

* Play is therefore equivalent to {@link #ACTION_STOP stop} followed by an action * to enqueue a new media item to be played immediately. *

* *

Sessions

*

* 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. *

* 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. *

* For more information on sessions, queues and media items, please refer to the * class documentation. *

* *

Request parameters

* * *

Result data

* * *

Status updates

*

* If the client supplies an * {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER item 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. *

* Refer to {@link MediaItemStatus} for details. *

* *

Errors

*

* 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. *

* *

Example

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

* Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} * media control. *

* 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. *

* 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. *

* 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. *

* * @see #ACTION_PLAY */ public static final String ACTION_ENQUEUE = "android.media.intent.action.ENQUEUE"; /** * Remote playback media control action: Seek media item to a new playback position. *

* Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} * media control. *

* This action causes a remote playback route to modify the current playback position * of the specified media item. *

* 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. *

* If successful, the media item's playback position is changed. *

* *

Request parameters

* * *

Result data

* * *

Errors

*

* 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. *

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

* Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} * media control. *

* This action asks a remote playback route to provide updated playback status and progress * information about the specified media item. *

* *

Request parameters

* * *

Result data

* * *

Errors

*

* This action returns an error if the session id or media item id are unknown * or no longer valid. *

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

* Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} * media control. *

* 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). *

* 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. *

* *

Request parameters

* * *

Result data

* * *

Errors

*

* 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). *

* * @see MediaRouter.RouteInfo#sendControlRequest * @see #CATEGORY_REMOTE_PLAYBACK */ 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. *

* Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} * media control. *

* This action causes the playback queue of the specified session to be paused. *

* *

Request parameters

* * *

Result data

* * *

Errors

*

* This action returns an error if the session id is unknown or no longer valid. *

* * @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). *

* Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} * media control. *

* This action causes the playback queue of the specified session to be resumed. * Reverses the effects of {@link #ACTION_PAUSE}. *

* *

Request parameters

* * *

Result data

* * *

Errors

*

* This action returns an error if the session id is unknown or no longer valid. *

* * @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). *

* Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} * media control. *

* 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. *

* 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. *

* *

Request parameters

* * *

Result data

* * *

Errors

*

* This action returns an error if the session id is unknown or no longer valid. *

* * @see MediaRouter.RouteInfo#sendControlRequest * @see #CATEGORY_REMOTE_PLAYBACK */ public static final String ACTION_STOP = "android.media.intent.action.STOP"; /** * Remote playback media control action: Start session. *

* Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} * media control. *

* This action causes a remote playback route to invalidate the current session * and start a new session. The new session initially has an empty queue. *

* If successful, the status of all media items in the previous session's queue is set to * {@link MediaItemStatus#PLAYBACK_STATE_INVALIDATED invalidated} and a status update * is sent to the appropriate status update receivers indicating the new status * of each item. The previous session becomes no longer valid and the new session * takes control of the route. *

* *

Request parameters

* * *

Result data

* * *

Status updates

*

* If the client supplies a * {@link #EXTRA_SESSION_STATUS_UPDATE_RECEIVER status update receiver} * then the media route provider is responsible for sending status updates to the receiver * when significant media session state changes occur such as when the session's * queue is paused or resumed or when the session is terminated or invalidated. *

* Refer to {@link MediaSessionStatus} for details. *

* *

Errors

*

* This action returns an error if the session could not be created. *

* * @see MediaRouter.RouteInfo#sendControlRequest * @see #CATEGORY_REMOTE_PLAYBACK */ public static final String ACTION_START_SESSION = "android.media.intent.action.START_SESSION"; /** * Remote playback media control action: Get media session status information. *

* Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} * media control. *

* This action asks a remote playback route to provide updated status information * about the specified media session. *

* *

Request parameters

* * *

Result data

* * *

Errors

*

* This action returns an error if the session id is unknown or no longer valid. *

* * @see MediaRouter.RouteInfo#sendControlRequest * @see #CATEGORY_REMOTE_PLAYBACK * @see #EXTRA_SESSION_STATUS_UPDATE_RECEIVER */ public static final String ACTION_GET_SESSION_STATUS = "android.media.intent.action.GET_SESSION_STATUS"; /** * Remote playback media control action: End session. *

* Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} * media control. *

* This action causes a remote playback route to end the specified session. * The session becomes no longer valid and the route ceases to be under control * of the session. *

* If successful, the status of the session is set to * {@link MediaSessionStatus#SESSION_STATE_ENDED} and a status update is sent to * the session's status update receiver. *

* Additionally, 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. *

* *

Request parameters

* * *

Result data

* * *

Errors

*

* This action returns an error if the session id is unknown or no longer valid. * In other words, it is an error to attempt to end a session other than the * current session. *

* * @see MediaRouter.RouteInfo#sendControlRequest * @see #CATEGORY_REMOTE_PLAYBACK */ public static final String ACTION_END_SESSION = "android.media.intent.action.END_SESSION"; /* Extras and related constants. */ /** * Bundle extra: Media session id. *

* An opaque unique identifier that identifies the remote playback media session. *

* Used with various actions to specify the id of the media session to be controlled. *

* Included in broadcast intents sent to * {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER item status update receivers} to identify * the session to which the item in question belongs. *

* Included in broadcast intents sent to * {@link #EXTRA_SESSION_STATUS_UPDATE_RECEIVER session status update receivers} to identify * the session. *

* The value is a unique string value generated by the media route provider * to represent one particular media session. *

* * @see #ACTION_PLAY * @see #ACTION_SEEK * @see #ACTION_GET_STATUS * @see #ACTION_PAUSE * @see #ACTION_RESUME * @see #ACTION_STOP * @see #ACTION_START_SESSION * @see #ACTION_GET_SESSION_STATUS * @see #ACTION_END_SESSION */ public static final String EXTRA_SESSION_ID = "android.media.intent.extra.SESSION_ID"; /** * Bundle extra: Media session status. *

* Returned as a result from media session actions such as {@link #ACTION_START_SESSION}, * {@link #ACTION_PAUSE}, and {@link #ACTION_GET_SESSION_STATUS} * to describe the status of the specified media session. *

* Included in broadcast intents sent to * {@link #EXTRA_SESSION_STATUS_UPDATE_RECEIVER session status update receivers} to provide * updated status information. *

* The value is a {@link android.os.Bundle} of data that can be converted into * a {@link MediaSessionStatus} object using * {@link MediaSessionStatus#fromBundle MediaSessionStatus.fromBundle}. *

* * @see #ACTION_PLAY * @see #ACTION_SEEK * @see #ACTION_GET_STATUS * @see #ACTION_PAUSE * @see #ACTION_RESUME * @see #ACTION_STOP * @see #ACTION_START_SESSION * @see #ACTION_GET_SESSION_STATUS * @see #ACTION_END_SESSION */ public static final String EXTRA_SESSION_STATUS = "android.media.intent.extra.SESSION_STATUS"; /** * Bundle extra: Media item status update receiver. *

* Used with {@link #ACTION_START_SESSION} to specify a {@link PendingIntent} for a * broadcast receiver that will receive status updates about the media session. *

* Whenever the status of the media session changes, the media route provider will * send a broadcast to the pending intent with extras that identify the session * id and its updated status. *

* The value is a {@link PendingIntent}. *

* *

Broadcast extras

* * * @see #ACTION_START_SESSION */ public static final String EXTRA_SESSION_STATUS_UPDATE_RECEIVER = "android.media.intent.extra.SESSION_STATUS_UPDATE_RECEIVER"; /** * Bundle extra: Media item id. *

* An opaque unique identifier returned as a result from {@link #ACTION_PLAY} or * {@link #ACTION_ENQUEUE} that represents the media item that was created by the * playback request. *

* Used with various actions to specify the id of the media item to be controlled. *

* Included in broadcast intents sent to * {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER status update receivers} to identify * the item in question. *

* The value is a unique string value generated by the media route provider * to represent one particular media item. *

* * @see #ACTION_PLAY * @see #ACTION_ENQUEUE * @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. *

* Returned as a result from media item actions such as {@link #ACTION_PLAY}, * {@link #ACTION_ENQUEUE}, {@link #ACTION_SEEK}, and {@link #ACTION_GET_STATUS} * to describe the status of the specified media item. *

* Included in broadcast intents sent to * {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER item status update receivers} to provide * updated status information. *

* 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}. *

* * @see #ACTION_PLAY * @see #ACTION_ENQUEUE * @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. *

* Used with {@link #ACTION_PLAY} or {@link #ACTION_ENQUEUE} to specify the * starting playback position. *

* Used with {@link #ACTION_SEEK} to set a new playback position. *

* The value is a long integer number of milliseconds from the beginning of the content. *

* * @see #ACTION_PLAY * @see #ACTION_ENQUEUE * @see #ACTION_SEEK */ public static final String EXTRA_ITEM_CONTENT_POSITION = "android.media.intent.extra.ITEM_POSITION"; /** * Bundle extra: Media item metadata. *

* Used with {@link #ACTION_PLAY} or {@link #ACTION_ENQUEUE} to specify metadata * associated with the content of a media item. *

* The value is a {@link android.os.Bundle} of metadata key-value pairs as defined * in {@link MediaItemMetadata}. *

* * @see #ACTION_PLAY * @see #ACTION_ENQUEUE */ public static final String EXTRA_ITEM_METADATA = "android.media.intent.extra.ITEM_METADATA"; /** * Bundle extra: HTTP request headers. *

* Used with {@link #ACTION_PLAY} or {@link #ACTION_ENQUEUE} to specify HTTP request * headers to be included when fetching to the content indicated by the media * item's data Uri. *

* This extra may be used to provide authentication tokens and other * parameters to the server separately from the media item's data Uri. *

* The value is a {@link android.os.Bundle} of string based key-value pairs * that describe the HTTP request headers. *

* * @see #ACTION_PLAY * @see #ACTION_ENQUEUE */ public static final String EXTRA_ITEM_HTTP_HEADERS = "android.media.intent.extra.HTTP_HEADERS"; /** * Bundle extra: Media item status update receiver. *

* Used with {@link #ACTION_PLAY} or {@link #ACTION_ENQUEUE} to specify * a {@link PendingIntent} for a * broadcast receiver that will receive status updates about a particular * media item. *

* 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 session * to which the item belongs, the session status, the item's id * and the item's updated status. *

* 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. *

* The value is a {@link PendingIntent}. *

* *

Broadcast extras

* * * @see #ACTION_PLAY * @see #ACTION_ENQUEUE */ public static final String EXTRA_ITEM_STATUS_UPDATE_RECEIVER = "android.media.intent.extra.ITEM_STATUS_UPDATE_RECEIVER"; /** * Integer extra: Error code. *

* Used with all media control requests to describe the cause of an error. * This extra may be omitted when the error is unknown. *

* The value is one of: {@link #ERROR_UNKNOWN}, {@link #ERROR_UNSUPPORTED_OPERATION}, * {@link #ERROR_INVALID_SESSION_ID}, {@link #ERROR_INVALID_ITEM_ID}. *

*/ public static final String EXTRA_ERROR_CODE = "android.media.intent.extra.ERROR_CODE"; /** * Error code: An unknown error occurred. * * @see #EXTRA_ERROR_CODE */ public static final int ERROR_UNKNOWN = 0; /** * Error code: The operation is not supported. * * @see #EXTRA_ERROR_CODE */ public static final int ERROR_UNSUPPORTED_OPERATION = 1; /** * Error code: The session id specified in the request was invalid. * * @see #EXTRA_ERROR_CODE */ public static final int ERROR_INVALID_SESSION_ID = 2; /** * Error code: The item id specified in the request was invalid. * * @see #EXTRA_ERROR_CODE */ public static final int ERROR_INVALID_ITEM_ID = 3; private MediaControlIntent() { } }