MediaControlIntent.java revision be0f7708a9d53b5bb90a83d551290ebaa01ad32a
1/* 2 * Copyright (C) 2013 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.support.v7.media; 18 19import android.app.PendingIntent; 20import android.content.Intent; 21import android.net.Uri; 22 23/** 24 * Constants for media control intents. 25 * <p> 26 * This class declares a set of standard media control intent categories and actions that 27 * applications can use to identify the capabilities of media routes and control them. 28 * </p> 29 * 30 * <h3>Media control intent categories</h3> 31 * <p> 32 * Media control intent categories specify means by which applications can 33 * send media to the destination of a media route. Categories are sometimes referred 34 * to as describing "types" or "kinds" of routes. 35 * </p><p> 36 * For example, if a route supports the {@link #CATEGORY_REMOTE_PLAYBACK remote playback category}, 37 * then an application can ask it to play media remotely by sending a 38 * {@link #ACTION_PLAY play} or {@link #ACTION_ENQUEUE enqueue} intent with the Uri of the 39 * media content to play. Such a route may then be referred to as 40 * a "remote playback route" because it supports remote playback requests. It is common 41 * for a route to support multiple categories of requests at the same time, such as 42 * live audio and live video. 43 * </p><p> 44 * The following standard route categories are defined. 45 * </p><ul> 46 * <li>{@link #CATEGORY_LIVE_AUDIO Live audio}: The route supports streaming live audio 47 * from the device to the destination. Live audio routes include local speakers 48 * and Bluetooth headsets. 49 * <li>{@link #CATEGORY_LIVE_VIDEO Live video}: The route supports streaming live video 50 * from the device to the destination. Live video routes include local displays 51 * and wireless displays that support mirroring and 52 * {@link android.app.Presentation presentations}. Live video routes typically also 53 * support live audio capabilities. 54 * <li>{@link #CATEGORY_REMOTE_PLAYBACK Remote playback}: The route supports sending 55 * remote playback requests for media content to the destination. The content to be 56 * played is identified by a Uri and mime-type. 57 * </ul><p> 58 * Media route providers may define custom media control intent categories of their own in 59 * addition to the standard ones. Custom categories can be used to provide a variety 60 * of features to applications that recognize and know how to use them. For example, 61 * a media route provider might define a custom category to indicate that its routes 62 * support a special device-specific control interface in addition to other 63 * standard features. 64 * </p><p> 65 * Applications can determine which categories a route supports by using the 66 * {@link MediaRouter.RouteInfo#supportsControlCategory MediaRouter.RouteInfo.supportsControlCategory} 67 * or {@link MediaRouter.RouteInfo#getControlFilters MediaRouter.RouteInfo.getControlFilters} 68 * methods. Applications can also specify the types of routes that they want to use by 69 * creating {@link MediaRouteSelector media route selectors} that contain the desired 70 * categories and are used to filter routes in several parts of the media router API. 71 * </p> 72 * 73 * <h3>Media control intent actions</h3> 74 * <p> 75 * Media control intent actions specify particular functions that applications 76 * can ask the destination of a media route to perform. Media route control requests 77 * take the form of intents in a similar manner to other intents used to start activities 78 * or send broadcasts. The difference is that media control intents are directed to 79 * routes rather than activity or broadcast receiver components. 80 * </p><p> 81 * Each media route control intent specifies an action, a category and some number of parameters 82 * that are supplied as extras. Applications send media control requests to routes using the 83 * {@link MediaRouter.RouteInfo#sendControlRequest MediaRouter.RouteInfo.sendControlRequest} 84 * method and receive results via a callback. 85 * </p><p> 86 * All media control intent actions are associated with the media control intent categories 87 * that support them. Thus only remote playback routes may perform remote playback actions. 88 * The documentation of each action specifies the category to which the action belongs, 89 * the parameters it requires, and the results it returns. 90 * </p> 91 * 92 * <h3>Live audio and live video routes</h3> 93 * <p> 94 * {@link #CATEGORY_LIVE_AUDIO Live audio} and {@link #CATEGORY_LIVE_VIDEO live video} 95 * routes present media using standard system interfaces such as audio streams, 96 * {@link android.app.Presentation presentations} or display mirroring. These routes are 97 * the easiest to use because applications simply render content locally on the device 98 * and the system streams it to the route destination automatically. 99 * </p><p> 100 * In most cases, applications can stream content to live audio and live video routes in 101 * the same way they would play the content locally without any modification. However, 102 * applications may also be able to take advantage of more sophisticated features such 103 * as second-screen presentation APIs that are particular to these routes. 104 * </p> 105 * 106 * <h3>Remote playback routes</h3> 107 * <p> 108 * Remote playback routes present media remotely by playing content from a Uri. 109 * These routes destinations take responsibility for fetching and rendering content 110 * on their own. Applications do not render the content themselves; instead, applications 111 * send control requests to initiate play, pause, resume, or stop media items and receive 112 * status updates as they change state. 113 * </p> 114 * 115 * <h4>Sessions</h4> 116 * <p> 117 * Each remote media playback action is conducted within the scope of a session. 118 * Sessions are used to prevent applications from accidentally interfering with one 119 * another because at most one session can be valid at a time. 120 * </p><p> 121 * A session can be created using the {@link #ACTION_START_SESSION start session action} 122 * and terminated using the {@link #ACTION_END_SESSION end session action} when the 123 * route provides explicit session management features. 124 * </p><p> 125 * Explicit session management was added in a later revision of the protocol so not 126 * all routes support it. If the route does not support explicit session management 127 * then implicit session management may still be used. Implicit session management 128 * relies on the use of the {@link #ACTION_PLAY play} and {@link #ACTION_ENQUEUE enqueue} 129 * actions which have the side-effect of creating a new session if none is provided 130 * as argument. 131 * </p><p> 132 * When a new session is created, the previous session is invalidated and any ongoing 133 * media playback is stopped before the requested action is performed. Any attempt 134 * to use an invalidated session will result in an error. (Protocol implementations 135 * are encouraged to aggressively discard information associated with invalidated sessions 136 * since it is no longer of use.) 137 * </p><p> 138 * Each session is identified by a unique session id that may be used to control 139 * the session using actions such as pause, resume, stop and end session. 140 * </p> 141 * 142 * <h4>Media items</h4> 143 * <p> 144 * Each successful {@link #ACTION_PLAY play} or {@link #ACTION_ENQUEUE enqueue} action 145 * returns a unique media item id that an application can use to monitor and control 146 * playback. The media item id may be passed to other actions such as 147 * {@link #ACTION_SEEK seek} or {@link #ACTION_GET_STATUS get status}. It will also appear 148 * as a parameter in status update broadcasts to identify the associated playback request. 149 * </p><p> 150 * Each media item is scoped to the session in which it was created. Therefore media item 151 * ids are only ever used together with session ids. Media item ids are meaningless 152 * on their own. When the session is invalidated, all of its media items are also 153 * invalidated. 154 * </p> 155 * 156 * <h4>The playback queue</h4> 157 * <p> 158 * Each session has its own playback queue that consists of the media items that 159 * are pending, playing, buffering or paused. Items are added to the queue when 160 * a playback request is issued. Items are removed from the queue when they are no 161 * longer eligible for playback (enter terminal states). 162 * </p><p> 163 * As described in the {@link MediaItemStatus} class, media items initially 164 * start in a pending state, transition to the playing (or buffering or paused) state 165 * during playback, and end in a finished, canceled, invalidated or error state. 166 * Once the current item enters a terminal state, playback proceeds on to the 167 * next item. 168 * </p><p> 169 * The application should determine whether the route supports queuing by checking 170 * whether the {@link #ACTION_ENQUEUE} action is declared in the route's control filter 171 * using {@link MediaRouter.RouteInfo#supportsControlRequest RouteInfo.supportsControlRequest}. 172 * </p><p> 173 * If the {@link #ACTION_ENQUEUE} action is supported by the route, then the route promises 174 * to allow at least two items (possibly more) to be enqueued at a time. Enqueued items play 175 * back to back one after the other as the previous item completes. Ideally there should 176 * be no audible pause between items for standard audio content types. 177 * </p><p> 178 * If the {@link #ACTION_ENQUEUE} action is not supported by the route, then the queue 179 * effectively contains at most one item at a time. Each play action has the effect of 180 * clearing the queue and resetting its state before the next item is played. 181 * </p> 182 * 183 * <h4>Impact of pause, resume, stop and play actions on the playback queue</h4> 184 * <p> 185 * The pause, resume and stop actions affect the session's whole queue. Pause causes 186 * the playback queue to be suspended no matter which item is currently playing. 187 * Resume reverses the effects of pause. Stop clears the queue and also resets 188 * the pause flag just like resume. 189 * </p><p> 190 * As described earlier, the play action has the effect of clearing the queue 191 * and completely resetting its state (like the stop action) then enqueuing a 192 * new media item to be played immediately. Play is therefore equivalent 193 * to stop followed by an action to enqueue an item. 194 * </p><p> 195 * The play action is also special in that it can be used to create new sessions. 196 * An application with simple needs may find that it only needs to use play 197 * (and occasionally stop) to control playback. 198 * </p> 199 * 200 * <h4>Resolving conflicts between applications</h4> 201 * <p> 202 * When an application has a valid session, it is essentially in control of remote playback 203 * on the route. No other application can view or modify the remote playback state 204 * of that applicaton's session without knowing its id. 205 * </p><p> 206 * However, other applications can perform actions that have the effect of stopping 207 * playback and invalidating the current session. When this occurs, the former application 208 * will be informed that it has lost control by way of individual media item status 209 * update broadcasts that indicate that its queued media items have become 210 * {@link MediaItemStatus#PLAYBACK_STATE_INVALIDATED invalidated}. This broadcast 211 * implies that playback was terminated abnormally by an external cause. 212 * </p><p> 213 * Applications should handle conflicts conservatively to allow other applications to 214 * smoothly assume control over the route. When a conflict occurs, the currently playing 215 * application should release its session and allow the new application to use the 216 * route until such time as the user intervenes to take over the route again and begin 217 * a new playback session. 218 * </p> 219 * 220 * <h4>Basic actions</h4> 221 * <p> 222 * The following basic actions must be supported (all or nothing) by all remote 223 * playback routes. These actions form the basis of the remote playback protocol 224 * and are required in all implementations. 225 * </p><ul> 226 * <li>{@link #ACTION_PLAY Play}: Starts playing content specified by a given Uri 227 * and returns a new media item id to describe the request. Implicitly creates a new 228 * session if no session id was specified as a parameter. 229 * <li>{@link #ACTION_SEEK Seek}: Sets the content playback position of a specific media item. 230 * <li>{@link #ACTION_GET_STATUS Get status}: Gets the status of a media item 231 * including the item's current playback position and progress. 232 * <li>{@link #ACTION_PAUSE Pause}: Pauses playback of the queue. 233 * <li>{@link #ACTION_RESUME Resume}: Resumes playback of the queue. 234 * <li>{@link #ACTION_STOP Stop}: Stops playback, clears the queue, and resets the 235 * pause state. 236 * </ul> 237 * 238 * <h4>Queue actions</h4> 239 * <p> 240 * The following queue actions must be supported (all or nothing) by remote 241 * playback routes that offer optional queuing capabilities. 242 * </p><ul> 243 * <li>{@link #ACTION_ENQUEUE Enqueue}: Enqueues content specified by a given Uri 244 * and returns a new media item id to describe the request. Implicitly creates a new 245 * session if no session id was specified as a parameter. 246 * <li>{@link #ACTION_REMOVE Remove}: Removes a specified media item from the queue. 247 * </ul> 248 * 249 * <h4>Session actions</h4> 250 * <p> 251 * The following session actions must be supported (all or nothing) by remote 252 * playback routes that offer optional session management capabilities. 253 * </p><ul> 254 * <li>{@link #ACTION_START_SESSION Start session}: Starts a new session explicitly. 255 * <li>{@link #ACTION_GET_SESSION_STATUS Get session status}: Gets the status of a session. 256 * <li>{@link #ACTION_END_SESSION End session}: Ends a session explicitly. 257 * </ul> 258 * 259 * <h4>Implementation note</h4> 260 * <p> 261 * Implementations of the remote playback protocol must implement <em>all</em> of the 262 * documented actions, parameters and results. Note that the documentation is written from 263 * the perspective of a client of the protocol. In particular, whenever a parameter 264 * is described as being "optional", it is only from the perspective of the client. 265 * Compliant media route provider implementations of this protocol must support all 266 * of the features described herein. 267 * </p> 268 */ 269public final class MediaControlIntent { 270 /** 271 * Media control category: Live audio. 272 * <p> 273 * A route that supports live audio routing will allow the media audio stream 274 * to be sent to supported destinations. This can include internal speakers or 275 * audio jacks on the device itself, A2DP devices, and more. 276 * </p><p> 277 * When a live audio route is selected, audio routing is transparent to the application. 278 * All audio played on the media stream will be routed to the selected destination. 279 * </p> 280 */ 281 public static final String CATEGORY_LIVE_AUDIO = "android.media.intent.category.LIVE_AUDIO"; 282 283 /** 284 * Media control category: Live video. 285 * <p> 286 * A route that supports live video routing will allow a mirrored version 287 * of the device's primary display or a customized 288 * {@link android.app.Presentation Presentation} to be sent to supported 289 * destinations. 290 * </p><p> 291 * When a live video route is selected, audio and video routing is transparent 292 * to the application. By default, audio and video is routed to the selected 293 * destination. For certain live video routes, the application may also use a 294 * {@link android.app.Presentation Presentation} to replace the mirrored view 295 * on the external display with different content. 296 * </p> 297 * 298 * @see MediaRouter.RouteInfo#getPresentationDisplay() 299 * @see android.app.Presentation 300 */ 301 public static final String CATEGORY_LIVE_VIDEO = "android.media.intent.category.LIVE_VIDEO"; 302 303 /** 304 * Media control category: Remote playback. 305 * <p> 306 * A route that supports remote playback routing will allow an application to send 307 * requests to play content remotely to supported destinations. 308 * </p><p> 309 * Remote playback routes destinations operate independently of the local device. 310 * When a remote playback route is selected, the application can control the content 311 * playing on the destination by sending media control actions to the route. 312 * The application may also receive status updates from the route regarding 313 * remote playback. 314 * </p> 315 * 316 * @see MediaRouter.RouteInfo#sendControlRequest 317 */ 318 public static final String CATEGORY_REMOTE_PLAYBACK = 319 "android.media.intent.category.REMOTE_PLAYBACK"; 320 321 /* Remote playback actions that affect individual items. */ 322 323 /** 324 * Remote playback media control action: Play media item. 325 * <p> 326 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 327 * media control. 328 * </p><p> 329 * This action causes a remote playback route to start playing content with 330 * the {@link Uri} specified in the {@link Intent}'s {@link Intent#getData() data uri}. 331 * The action returns a media session id and media item id which can be used 332 * to control playback using other remote playback actions. 333 * </p><p> 334 * Once initiated, playback of the specified content will be managed independently 335 * by the destination. The application will receive status updates as the state 336 * of the media item changes. 337 * </p><p> 338 * If the data uri specifies an HTTP or HTTPS scheme, then the destination is 339 * responsible for following HTTP redirects to a reasonable depth of at least 3 340 * levels as might typically be handled by a web browser. If an HTTP error 341 * occurs, then the destination should send a {@link MediaItemStatus status update} 342 * back to the client indicating the {@link MediaItemStatus#PLAYBACK_STATE_ERROR error} 343 * {@link MediaItemStatus#getPlaybackState() playback state}. 344 * </p> 345 * 346 * <h3>One item at a time</h3> 347 * <p> 348 * Each successful play action <em>replaces</em> the previous play action. 349 * If an item is already playing, then it is canceled, the session's playback queue 350 * is cleared and the new item begins playing immediately (regardless of 351 * whether the previously playing item had been paused). 352 * </p><p> 353 * Play is therefore equivalent to {@link #ACTION_STOP stop} followed by an action 354 * to enqueue a new media item to be played immediately. 355 * </p> 356 * 357 * <h3>Sessions</h3> 358 * <p> 359 * This request has the effect of implicitly creating a media session whenever the 360 * application does not specify the {@link #EXTRA_SESSION_ID session id} parameter. 361 * Because there can only be at most one valid session at a time, creating a new session 362 * has the side-effect of invalidating any existing sessions and their media items, 363 * then handling the playback request with a new session. 364 * </p><p> 365 * If the application specifies an invalid session id, then an error is returned. 366 * When this happens, the application should assume that its session 367 * is no longer valid. To obtain a new session, the application may try again 368 * and omit the session id parameter. However, the application should 369 * only retry requests due to an explicit action performed by the user, 370 * such as the user clicking on a "play" button in the UI, since another 371 * application may be trying to take control of the route and the former 372 * application should try to stay out of its way. 373 * </p><p> 374 * For more information on sessions, queues and media items, please refer to the 375 * class documentation. 376 * </p> 377 * 378 * <h3>Request parameters</h3> 379 * <ul> 380 * <li>{@link #EXTRA_SESSION_ID} <em>(optional)</em>: Specifies the session id of the 381 * session to which the playback request belongs. If omitted, a new session 382 * is created implicitly. 383 * <li>{@link #EXTRA_ITEM_CONTENT_POSITION} <em>(optional)</em>: Specifies the initial 384 * content playback position as a long integer number of milliseconds from 385 * the beginning of the content. 386 * <li>{@link #EXTRA_ITEM_METADATA} <em>(optional)</em>: Specifies metadata associated 387 * with the content such as the title of a song. 388 * <li>{@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER} <em>(optional)</em>: Specifies a 389 * {@link PendingIntent} for a broadcast receiver that will receive status updates 390 * about the media item. 391 * </ul> 392 * 393 * <h3>Result data</h3> 394 * <ul> 395 * <li>{@link #EXTRA_SESSION_ID} <em>(always returned)</em>: Specifies the session id of the 396 * session that was affected by the request. This will be a new session in 397 * the case where no session id was supplied as a parameter. 398 * <li>{@link #EXTRA_SESSION_STATUS} <em>(optional, old implementations may 399 * omit this key)</em>: Specifies the status of the media session. 400 * <li>{@link #EXTRA_ITEM_ID} <em>(always returned)</em>: Specifies an opaque string identifier 401 * to use to refer to the media item in subsequent requests such as 402 * {@link #ACTION_GET_STATUS}. 403 * <li>{@link #EXTRA_ITEM_STATUS} <em>(always returned)</em>: Specifies the initial status of 404 * the new media item. 405 * </ul> 406 * 407 * <h3>Status updates</h3> 408 * <p> 409 * If the client supplies an 410 * {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER item status update receiver} 411 * then the media route provider is responsible for sending status updates to the receiver 412 * when significant media item state changes occur such as when playback starts or 413 * stops. The receiver will not be invoked for content playback position changes. 414 * The application may retrieve the current playback position when necessary 415 * using the {@link #ACTION_GET_STATUS} request. 416 * </p><p> 417 * Refer to {@link MediaItemStatus} for details. 418 * </p> 419 * 420 * <h3>Errors</h3> 421 * <p> 422 * This action returns an error if a session id was provided but is unknown or 423 * no longer valid, if the item Uri or content type is not supported, or if 424 * any other arguments are invalid. 425 * </p> 426 * 427 * <h3>Example</h3> 428 * <pre> 429 * MediaRouter mediaRouter = MediaRouter.getInstance(context); 430 * MediaRouter.RouteInfo route = mediaRouter.getSelectedRoute(); 431 * Intent intent = new Intent(MediaControlIntent.ACTION_PLAY); 432 * intent.addCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK); 433 * intent.setDataAndType("http://example.com/videos/movie.mp4", "video/mp4"); 434 * if (route.supportsControlRequest(intent)) { 435 * MediaRouter.ControlRequestCallback callback = new MediaRouter.ControlRequestCallback() { 436 * public void onResult(Bundle data) { 437 * // The request succeeded. 438 * // Playback may be controlled using the returned session and item id. 439 * String sessionId = data.getString(MediaControlIntent.EXTRA_SESSION_ID); 440 * String itemId = data.getString(MediaControlIntent.EXTRA_ITEM_ID); 441 * MediaItemStatus status = MediaItemStatus.fromBundle(data.getBundle( 442 * MediaControlIntent.EXTRA_ITEM_STATUS)); 443 * // ... 444 * } 445 * 446 * public void onError(String message, Bundle data) { 447 * // An error occurred! 448 * } 449 * }; 450 * route.sendControlRequest(intent, callback); 451 * }</pre> 452 * 453 * @see MediaRouter.RouteInfo#sendControlRequest 454 * @see #CATEGORY_REMOTE_PLAYBACK 455 * @see #ACTION_SEEK 456 * @see #ACTION_GET_STATUS 457 * @see #ACTION_PAUSE 458 * @see #ACTION_RESUME 459 * @see #ACTION_STOP 460 */ 461 public static final String ACTION_PLAY = "android.media.intent.action.PLAY"; 462 463 /** 464 * Remote playback media control action: Enqueue media item. 465 * <p> 466 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 467 * media control. 468 * </p><p> 469 * This action works just like {@link #ACTION_PLAY play} except that it does 470 * not clear the queue or reset the pause state when it enqueues the 471 * new media item into the session's playback queue. This action only 472 * enqueues a media item with no other side-effects on the queue. 473 * </p><p> 474 * If the queue is currently empty and then the item will play immediately 475 * (assuming the queue is not paused). Otherwise, the item will play 476 * after all earlier items in the queue have finished or been removed. 477 * </p><p> 478 * The enqueue action can be used to create new sessions just like play. 479 * Its parameters and results are also the same. Only the queuing behavior 480 * is different. 481 * </p> 482 * 483 * @see #ACTION_PLAY 484 */ 485 public static final String ACTION_ENQUEUE = "android.media.intent.action.ENQUEUE"; 486 487 /** 488 * Remote playback media control action: Seek media item to a new playback position. 489 * <p> 490 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 491 * media control. 492 * </p><p> 493 * This action causes a remote playback route to modify the current playback position 494 * of the specified media item. 495 * </p><p> 496 * This action only affects the playback position of the media item; not its playback state. 497 * If the playback queue is paused, then seeking sets the position but the item 498 * remains paused. Likewise if the item is playing, then seeking will cause playback 499 * to jump to the new position and continue playing from that point. If the item has 500 * not yet started playing, then the new playback position is remembered by the 501 * queue and used as the item's initial content position when playback eventually begins. 502 * </p><p> 503 * If successful, the media item's playback position is changed. 504 * </p> 505 * 506 * <h3>Request parameters</h3> 507 * <ul> 508 * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of the session 509 * to which the media item belongs. 510 * <li>{@link #EXTRA_ITEM_ID} <em>(required)</em>: Specifies the media item id of 511 * the media item to seek. 512 * <li>{@link #EXTRA_ITEM_CONTENT_POSITION} <em>(required)</em>: Specifies the new 513 * content position for playback as a long integer number of milliseconds from 514 * the beginning of the content. 515 * </ul> 516 * 517 * <h3>Result data</h3> 518 * <ul> 519 * <li>{@link #EXTRA_SESSION_STATUS} <em>(optional, old implementations may 520 * omit this key)</em>: Specifies the status of the media session. 521 * <li>{@link #EXTRA_ITEM_STATUS} <em>(always returned)</em>: Specifies the new status of 522 * the media item. 523 * </ul> 524 * 525 * <h3>Errors</h3> 526 * <p> 527 * This action returns an error if the session id or media item id are unknown 528 * or no longer valid, if the content position is invalid, or if the media item 529 * is in a terminal state. 530 * </p> 531 * 532 * @see MediaRouter.RouteInfo#sendControlRequest 533 * @see #CATEGORY_REMOTE_PLAYBACK 534 */ 535 public static final String ACTION_SEEK = "android.media.intent.action.SEEK"; 536 537 /** 538 * Remote playback media control action: Get media item playback status 539 * and progress information. 540 * <p> 541 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 542 * media control. 543 * </p><p> 544 * This action asks a remote playback route to provide updated playback status and progress 545 * information about the specified media item. 546 * </p> 547 * 548 * <h3>Request parameters</h3> 549 * <ul> 550 * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of the session 551 * to which the media item belongs. 552 * <li>{@link #EXTRA_ITEM_ID} <em>(required)</em>: Specifies the media item id of 553 * the media item to query. 554 * </ul> 555 * 556 * <h3>Result data</h3> 557 * <ul> 558 * <li>{@link #EXTRA_SESSION_STATUS} <em>(optional, old implementations may 559 * omit this key)</em>: Specifies the status of the media session. 560 * <li>{@link #EXTRA_ITEM_STATUS} <em>(always returned)</em>: Specifies the current status of 561 * the media item. 562 * </ul> 563 * 564 * <h3>Errors</h3> 565 * <p> 566 * This action returns an error if the session id or media item id are unknown 567 * or no longer valid. 568 * </p> 569 * 570 * @see MediaRouter.RouteInfo#sendControlRequest 571 * @see #CATEGORY_REMOTE_PLAYBACK 572 * @see #EXTRA_ITEM_STATUS_UPDATE_RECEIVER 573 */ 574 public static final String ACTION_GET_STATUS = "android.media.intent.action.GET_STATUS"; 575 576 /** 577 * Remote playback media control action: Remove media item from session's queue. 578 * <p> 579 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 580 * media control. 581 * </p><p> 582 * This action asks a remote playback route to remove the specified media item 583 * from the session's playback queue. If the current item is removed, then 584 * playback will proceed to the next media item (assuming the queue has not been 585 * paused). 586 * </p><p> 587 * This action does not affect the pause state of the queue. If the queue was paused 588 * then it remains paused (even if it is now empty) until a resume, stop or play 589 * action is issued that causes the pause state to be cleared. 590 * </p> 591 * 592 * <h3>Request parameters</h3> 593 * <ul> 594 * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of the session 595 * to which the media item belongs. 596 * <li>{@link #EXTRA_ITEM_ID} <em>(required)</em>: Specifies the media item id of 597 * the media item to remove. 598 * </ul> 599 * 600 * <h3>Result data</h3> 601 * <ul> 602 * <li>{@link #EXTRA_SESSION_STATUS} <em>(optional, old implementations may 603 * omit this key)</em>: Specifies the status of the media session. 604 * <li>{@link #EXTRA_ITEM_STATUS} <em>(always returned)</em>: Specifies the new status of 605 * the media item. 606 * </ul> 607 * 608 * <h3>Errors</h3> 609 * <p> 610 * This action returns an error if the session id or media item id are unknown 611 * or no longer valid, or if the media item is in a terminal state (and therefore 612 * no longer in the queue). 613 * </p> 614 * 615 * @see MediaRouter.RouteInfo#sendControlRequest 616 * @see #CATEGORY_REMOTE_PLAYBACK 617 */ 618 public static final String ACTION_REMOVE = "android.media.intent.action.REMOVE"; 619 620 /* Remote playback actions that affect the whole playback queue. */ 621 622 /** 623 * Remote playback media control action: Pause media playback. 624 * <p> 625 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 626 * media control. 627 * </p><p> 628 * This action causes the playback queue of the specified session to be paused. 629 * </p> 630 * 631 * <h3>Request parameters</h3> 632 * <ul> 633 * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of the session 634 * whose playback queue is to be paused. 635 * </ul> 636 * 637 * <h3>Result data</h3> 638 * <ul> 639 * <li>{@link #EXTRA_SESSION_STATUS} <em>(optional, old implementations may 640 * omit this key)</em>: Specifies the status of the media session. 641 * </ul> 642 * 643 * <h3>Errors</h3> 644 * <p> 645 * This action returns an error if the session id is unknown or no longer valid. 646 * </p> 647 * 648 * @see MediaRouter.RouteInfo#sendControlRequest 649 * @see #CATEGORY_REMOTE_PLAYBACK 650 * @see #ACTION_RESUME 651 */ 652 public static final String ACTION_PAUSE = "android.media.intent.action.PAUSE"; 653 654 /** 655 * Remote playback media control action: Resume media playback (unpause). 656 * <p> 657 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 658 * media control. 659 * </p><p> 660 * This action causes the playback queue of the specified session to be resumed. 661 * Reverses the effects of {@link #ACTION_PAUSE}. 662 * </p> 663 * 664 * <h3>Request parameters</h3> 665 * <ul> 666 * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of the session 667 * whose playback queue is to be resumed. 668 * </ul> 669 * 670 * <h3>Result data</h3> 671 * <ul> 672 * <li>{@link #EXTRA_SESSION_STATUS} <em>(optional, old implementations may 673 * omit this key)</em>: Specifies the status of the media session. 674 * </ul> 675 * 676 * <h3>Errors</h3> 677 * <p> 678 * This action returns an error if the session id is unknown or no longer valid. 679 * </p> 680 * 681 * @see MediaRouter.RouteInfo#sendControlRequest 682 * @see #CATEGORY_REMOTE_PLAYBACK 683 * @see #ACTION_PAUSE 684 */ 685 public static final String ACTION_RESUME = "android.media.intent.action.RESUME"; 686 687 /** 688 * Remote playback media control action: Stop media playback (clear queue and unpause). 689 * <p> 690 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 691 * media control. 692 * </p><p> 693 * This action causes a remote playback route to stop playback, cancel and remove 694 * all media items from the session's media item queue and, reset the queue's 695 * pause state. 696 * </p><p> 697 * If successful, the status of all media items in the queue is set to 698 * {@link MediaItemStatus#PLAYBACK_STATE_CANCELED canceled} and a status update is sent 699 * to the appropriate status update receivers indicating the new status of each item. 700 * </p> 701 * 702 * <h3>Request parameters</h3> 703 * <ul> 704 * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of 705 * the session whose playback queue is to be stopped (cleared and unpaused). 706 * </ul> 707 * 708 * <h3>Result data</h3> 709 * <ul> 710 * <li>{@link #EXTRA_SESSION_STATUS} <em>(optional, old implementations may 711 * omit this key)</em>: Specifies the status of the media session. 712 * </ul> 713 * 714 * <h3>Errors</h3> 715 * <p> 716 * This action returns an error if the session id is unknown or no longer valid. 717 * </p> 718 * 719 * @see MediaRouter.RouteInfo#sendControlRequest 720 * @see #CATEGORY_REMOTE_PLAYBACK 721 */ 722 public static final String ACTION_STOP = "android.media.intent.action.STOP"; 723 724 /** 725 * Remote playback media control action: Start session. 726 * <p> 727 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 728 * media control. 729 * </p><p> 730 * This action causes a remote playback route to invalidate the current session 731 * and start a new session. The new session initially has an empty queue. 732 * </p><p> 733 * If successful, the status of all media items in the previous session's queue is set to 734 * {@link MediaItemStatus#PLAYBACK_STATE_INVALIDATED invalidated} and a status update 735 * is sent to the appropriate status update receivers indicating the new status 736 * of each item. The previous session becomes no longer valid and the new session 737 * takes control of the route. 738 * </p> 739 * 740 * <h3>Request parameters</h3> 741 * <ul> 742 * <li>{@link #EXTRA_SESSION_STATUS_UPDATE_RECEIVER} <em>(optional)</em>: Specifies a 743 * {@link PendingIntent} for a broadcast receiver that will receive status updates 744 * about the media session. 745 * </ul> 746 * 747 * <h3>Result data</h3> 748 * <ul> 749 * <li>{@link #EXTRA_SESSION_ID} <em>(always returned)</em>: Specifies the session id of the 750 * session that was started by the request. This will always be a brand new session 751 * distinct from any other previously created sessions. 752 * <li>{@link #EXTRA_SESSION_STATUS} <em>(always returned)</em>: Specifies the 753 * status of the media session. 754 * </ul> 755 * 756 * <h3>Status updates</h3> 757 * <p> 758 * If the client supplies a 759 * {@link #EXTRA_SESSION_STATUS_UPDATE_RECEIVER status update receiver} 760 * then the media route provider is responsible for sending status updates to the receiver 761 * when significant media session state changes occur such as when the session's 762 * queue is paused or resumed or when the session is terminated or invalidated. 763 * </p><p> 764 * Refer to {@link MediaSessionStatus} for details. 765 * </p> 766 * 767 * <h3>Errors</h3> 768 * <p> 769 * This action returns an error if the session could not be created. 770 * </p> 771 * 772 * @see MediaRouter.RouteInfo#sendControlRequest 773 * @see #CATEGORY_REMOTE_PLAYBACK 774 */ 775 public static final String ACTION_START_SESSION = "android.media.intent.action.START_SESSION"; 776 777 /** 778 * Remote playback media control action: Get media session status information. 779 * <p> 780 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 781 * media control. 782 * </p><p> 783 * This action asks a remote playback route to provide updated status information 784 * about the specified media session. 785 * </p> 786 * 787 * <h3>Request parameters</h3> 788 * <ul> 789 * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of the 790 * session whose status is to be retrieved. 791 * </ul> 792 * 793 * <h3>Result data</h3> 794 * <ul> 795 * <li>{@link #EXTRA_SESSION_STATUS} <em>(always returned)</em>: Specifies the 796 * current status of the media session. 797 * </ul> 798 * 799 * <h3>Errors</h3> 800 * <p> 801 * This action returns an error if the session id is unknown or no longer valid. 802 * </p> 803 * 804 * @see MediaRouter.RouteInfo#sendControlRequest 805 * @see #CATEGORY_REMOTE_PLAYBACK 806 * @see #EXTRA_SESSION_STATUS_UPDATE_RECEIVER 807 */ 808 public static final String ACTION_GET_SESSION_STATUS = 809 "android.media.intent.action.GET_SESSION_STATUS"; 810 811 /** 812 * Remote playback media control action: End session. 813 * <p> 814 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 815 * media control. 816 * </p><p> 817 * This action causes a remote playback route to end the specified session. 818 * The session becomes no longer valid and the route ceases to be under control 819 * of the session. 820 * </p><p> 821 * If successful, the status of the session is set to 822 * {@link MediaSessionStatus#SESSION_STATE_ENDED} and a status update is sent to 823 * the session's status update receiver. 824 * </p><p> 825 * Additionally, the status of all media items in the queue is set to 826 * {@link MediaItemStatus#PLAYBACK_STATE_CANCELED canceled} and a status update is sent 827 * to the appropriate status update receivers indicating the new status of each item. 828 * </p> 829 * 830 * <h3>Request parameters</h3> 831 * <ul> 832 * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of 833 * the session to end. 834 * </ul> 835 * 836 * <h3>Result data</h3> 837 * <ul> 838 * <li>{@link #EXTRA_SESSION_STATUS} <em>(always returned)</em>: Specifies the 839 * status of the media session. 840 * </ul> 841 * 842 * <h3>Errors</h3> 843 * <p> 844 * This action returns an error if the session id is unknown or no longer valid. 845 * In other words, it is an error to attempt to end a session other than the 846 * current session. 847 * </p> 848 * 849 * @see MediaRouter.RouteInfo#sendControlRequest 850 * @see #CATEGORY_REMOTE_PLAYBACK 851 */ 852 public static final String ACTION_END_SESSION = "android.media.intent.action.END_SESSION"; 853 854 /** 855 * Bundle extra: Media session id. 856 * <p> 857 * An opaque unique identifier that identifies the remote playback media session. 858 * </p><p> 859 * Used with various actions to specify the id of the media session to be controlled. 860 * </p><p> 861 * Included in broadcast intents sent to 862 * {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER item status update receivers} to identify 863 * the session to which the item in question belongs. 864 * </p><p> 865 * Included in broadcast intents sent to 866 * {@link #EXTRA_SESSION_STATUS_UPDATE_RECEIVER session status update receivers} to identify 867 * the session. 868 * </p><p> 869 * The value is a unique string value generated by the media route provider 870 * to represent one particular media session. 871 * </p> 872 * 873 * @see #ACTION_PLAY 874 * @see #ACTION_SEEK 875 * @see #ACTION_GET_STATUS 876 * @see #ACTION_PAUSE 877 * @see #ACTION_RESUME 878 * @see #ACTION_STOP 879 * @see #ACTION_START_SESSION 880 * @see #ACTION_GET_SESSION_STATUS 881 * @see #ACTION_END_SESSION 882 */ 883 public static final String EXTRA_SESSION_ID = 884 "android.media.intent.extra.SESSION_ID"; 885 886 /** 887 * Bundle extra: Media session status. 888 * <p> 889 * Returned as a result from media session actions such as {@link #ACTION_START_SESSION}, 890 * {@link #ACTION_PAUSE}, and {@link #ACTION_GET_SESSION_STATUS} 891 * to describe the status of the specified media session. 892 * </p><p> 893 * Included in broadcast intents sent to 894 * {@link #EXTRA_SESSION_STATUS_UPDATE_RECEIVER session status update receivers} to provide 895 * updated status information. 896 * </p><p> 897 * The value is a {@link android.os.Bundle} of data that can be converted into 898 * a {@link MediaSessionStatus} object using 899 * {@link MediaSessionStatus#fromBundle MediaSessionStatus.fromBundle}. 900 * </p> 901 * 902 * @see #ACTION_PLAY 903 * @see #ACTION_SEEK 904 * @see #ACTION_GET_STATUS 905 * @see #ACTION_PAUSE 906 * @see #ACTION_RESUME 907 * @see #ACTION_STOP 908 * @see #ACTION_START_SESSION 909 * @see #ACTION_GET_SESSION_STATUS 910 * @see #ACTION_END_SESSION 911 */ 912 public static final String EXTRA_SESSION_STATUS = 913 "android.media.intent.extra.SESSION_STATUS"; 914 915 /** 916 * Bundle extra: Media item status update receiver. 917 * <p> 918 * Used with {@link #ACTION_START_SESSION} to specify a {@link PendingIntent} for a 919 * broadcast receiver that will receive status updates about the media session. 920 * </p><p> 921 * Whenever the status of the media session changes, the media route provider will 922 * send a broadcast to the pending intent with extras that identify the session 923 * id and its updated status. 924 * </p><p> 925 * The value is a {@link PendingIntent}. 926 * </p> 927 * 928 * <h3>Broadcast extras</h3> 929 * <ul> 930 * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of 931 * the session. 932 * <li>{@link #EXTRA_SESSION_STATUS} <em>(required)</em>: Specifies the status of the 933 * session as a bundle that can be decoded into a {@link MediaSessionStatus} object. 934 * </ul> 935 * 936 * @see #ACTION_START_SESSION 937 */ 938 public static final String EXTRA_SESSION_STATUS_UPDATE_RECEIVER = 939 "android.media.intent.extra.SESSION_STATUS_UPDATE_RECEIVER"; 940 941 /** 942 * Bundle extra: Media item id. 943 * <p> 944 * An opaque unique identifier returned as a result from {@link #ACTION_PLAY} or 945 * {@link #ACTION_ENQUEUE} that represents the media item that was created by the 946 * playback request. 947 * </p><p> 948 * Used with various actions to specify the id of the media item to be controlled. 949 * </p><p> 950 * Included in broadcast intents sent to 951 * {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER status update receivers} to identify 952 * the item in question. 953 * </p><p> 954 * The value is a unique string value generated by the media route provider 955 * to represent one particular media item. 956 * </p> 957 * 958 * @see #ACTION_PLAY 959 * @see #ACTION_ENQUEUE 960 * @see #ACTION_SEEK 961 * @see #ACTION_GET_STATUS 962 */ 963 public static final String EXTRA_ITEM_ID = 964 "android.media.intent.extra.ITEM_ID"; 965 966 /** 967 * Bundle extra: Media item status. 968 * <p> 969 * Returned as a result from media item actions such as {@link #ACTION_PLAY}, 970 * {@link #ACTION_ENQUEUE}, {@link #ACTION_SEEK}, and {@link #ACTION_GET_STATUS} 971 * to describe the status of the specified media item. 972 * </p><p> 973 * Included in broadcast intents sent to 974 * {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER item status update receivers} to provide 975 * updated status information. 976 * </p><p> 977 * The value is a {@link android.os.Bundle} of data that can be converted into 978 * a {@link MediaItemStatus} object using 979 * {@link MediaItemStatus#fromBundle MediaItemStatus.fromBundle}. 980 * </p> 981 * 982 * @see #ACTION_PLAY 983 * @see #ACTION_ENQUEUE 984 * @see #ACTION_SEEK 985 * @see #ACTION_GET_STATUS 986 */ 987 public static final String EXTRA_ITEM_STATUS = 988 "android.media.intent.extra.ITEM_STATUS"; 989 990 /** 991 * Long extra: Media item content position. 992 * <p> 993 * Used with {@link #ACTION_PLAY} or {@link #ACTION_ENQUEUE} to specify the 994 * starting playback position. 995 * </p><p> 996 * Used with {@link #ACTION_SEEK} to set a new playback position. 997 * </p><p> 998 * The value is a long integer number of milliseconds from the beginning of the content. 999 * <p> 1000 * 1001 * @see #ACTION_PLAY 1002 * @see #ACTION_ENQUEUE 1003 * @see #ACTION_SEEK 1004 */ 1005 public static final String EXTRA_ITEM_CONTENT_POSITION = 1006 "android.media.intent.extra.ITEM_POSITION"; 1007 1008 /** 1009 * Bundle extra: Media item metadata. 1010 * <p> 1011 * Used with {@link #ACTION_PLAY} or {@link #ACTION_ENQUEUE} to specify metadata 1012 * associated with the content of a media item. 1013 * </p><p> 1014 * The value is a {@link android.os.Bundle} of metadata key-value pairs as defined 1015 * in {@link MediaItemMetadata}. 1016 * </p> 1017 * 1018 * @see #ACTION_PLAY 1019 * @see #ACTION_ENQUEUE 1020 */ 1021 public static final String EXTRA_ITEM_METADATA = 1022 "android.media.intent.extra.ITEM_METADATA"; 1023 1024 /** 1025 * Bundle extra: HTTP request headers. 1026 * <p> 1027 * Used with {@link #ACTION_PLAY} or {@link #ACTION_ENQUEUE} to specify HTTP request 1028 * headers to be included when fetching to the content indicated by the media 1029 * item's data Uri. 1030 * </p><p> 1031 * This extra may be used to provide authentication tokens and other 1032 * parameters to the server separately from the media item's data Uri. 1033 * </p><p> 1034 * The value is a {@link android.os.Bundle} of string based key-value pairs 1035 * that describe the HTTP request headers. 1036 * </p> 1037 * 1038 * @see #ACTION_PLAY 1039 * @see #ACTION_ENQUEUE 1040 */ 1041 public static final String EXTRA_ITEM_HTTP_HEADERS = 1042 "android.media.intent.extra.HTTP_HEADERS"; 1043 1044 /** 1045 * Bundle extra: Media item status update receiver. 1046 * <p> 1047 * Used with {@link #ACTION_PLAY} or {@link #ACTION_ENQUEUE} to specify 1048 * a {@link PendingIntent} for a 1049 * broadcast receiver that will receive status updates about a particular 1050 * media item. 1051 * </p><p> 1052 * Whenever the status of the media item changes, the media route provider will 1053 * send a broadcast to the pending intent with extras that identify the session 1054 * to which the item belongs, the session status, the item's id 1055 * and the item's updated status. 1056 * </p><p> 1057 * The same pending intent and broadcast receiver may be shared by any number of 1058 * media items since the broadcast intent includes the media session id 1059 * and media item id. 1060 * </p><p> 1061 * The value is a {@link PendingIntent}. 1062 * </p> 1063 * 1064 * <h3>Broadcast extras</h3> 1065 * <ul> 1066 * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of 1067 * the session to which the item in question belongs. 1068 * <li>{@link #EXTRA_SESSION_STATUS} <em>(optional, old implementations may 1069 * omit this key)</em>: Specifies the status of the media session. 1070 * <li>{@link #EXTRA_ITEM_ID} <em>(required)</em>: Specifies the media item id of the 1071 * media item in question. 1072 * <li>{@link #EXTRA_ITEM_STATUS} <em>(required)</em>: Specifies the status of the 1073 * item as a bundle that can be decoded into a {@link MediaItemStatus} object. 1074 * </ul> 1075 * 1076 * @see #ACTION_PLAY 1077 * @see #ACTION_ENQUEUE 1078 */ 1079 public static final String EXTRA_ITEM_STATUS_UPDATE_RECEIVER = 1080 "android.media.intent.extra.ITEM_STATUS_UPDATE_RECEIVER"; 1081 1082 private MediaControlIntent() { 1083 } 1084} 1085