MediaControlIntent.java revision eff7719415542ba819054863b0995f07742a7a8a
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 {@link #ACTION_PLAY play} 38 * intent with the Uri of the media content to play. Such a route may then be referred to as 39 * a "remote playback route" because it supports remote playback requests. It is common 40 * for a route to support multiple categories of requests at the same time, such as 41 * live audio and live video. 42 * </p><p> 43 * The following standard route categories are defined. 44 * </p><ul> 45 * <li>{@link #CATEGORY_LIVE_AUDIO Live audio}: The route supports streaming live audio 46 * from the device to the destination. Live audio routes include local speakers 47 * and Bluetooth headsets. 48 * <li>{@link #CATEGORY_LIVE_VIDEO Live video}: The route supports streaming live video 49 * from the device to the destination. Live video routes include local displays 50 * and wireless displays that support mirroring and 51 * {@link android.app.Presentation presentations}. Live video routes typically also 52 * support live audio capabilities. 53 * <li>{@link #CATEGORY_REMOTE_PLAYBACK Remote playback}: The route supports sending 54 * remote playback requests for media content to the destination. The content to be 55 * played is identified by a Uri and mime-type. 56 * </ul><p> 57 * Media route providers may define custom media control intent categories of their own in 58 * addition to the standard ones. Custom categories can be used to provide a variety 59 * of features to applications that recognize and know how to use them. For example, 60 * a media route provider might define a custom category to indicate that its routes 61 * support a special device-specific control interface in addition to other 62 * standard features. 63 * </p><p> 64 * Applications can determine which categories a route supports by using the 65 * {@link MediaRouter.RouteInfo#supportsControlCategory MediaRouter.RouteInfo.supportsControlCategory} 66 * or {@link MediaRouter.RouteInfo#getControlFilters MediaRouter.RouteInfo.getControlFilters} 67 * methods. Applications can also specify the types of routes that they want to use by 68 * creating {@link MediaRouteSelector media route selectors} that contain the desired 69 * categories and are used to filter routes in several parts of the media router API. 70 * </p> 71 * 72 * <h3>Media control intent actions</h3> 73 * <p> 74 * Media control intent actions specify particular functions that applications 75 * can ask the destination of a media route to perform. Media route control requests 76 * take the form of intents in a similar manner to other intents used to start activities 77 * or send broadcasts. The difference is that media control intents are directed to 78 * routes rather than activity or broadcast receiver components. 79 * </p><p> 80 * Each media route control intent specifies an action, a category and some number of parameters 81 * that are supplied as extras. Applications send media control requests to routes using the 82 * {@link MediaRouter.RouteInfo#sendControlRequest MediaRouter.RouteInfo.sendControlRequest} 83 * method and receive results via a callback. 84 * </p><p> 85 * All media control intent actions are associated with the media control intent categories 86 * that support them. Thus only remote playback routes may perform remote playback actions. 87 * The documentation of each action specifies the category to which the action belongs, 88 * the parameters it requires, and the results it returns. 89 * </p> 90 * 91 * <h3>Live audio and live video routes</h3> 92 * <p> 93 * {@link #CATEGORY_LIVE_AUDIO Live audio} and {@link #CATEGORY_LIVE_VIDEO live video} 94 * routes present media using standard system interfaces such as audio streams, 95 * {@link android.app.Presentation presentations} or display mirroring. These routes are 96 * the easiest to use because applications simply render content locally on the device 97 * and the system streams it to the route destination automatically. 98 * </p><p> 99 * In most cases, applications can stream content to live audio and live video routes in 100 * the same way they would play the content locally without any modification. However, 101 * applications may also be able to take advantage of more sophisticated features such 102 * as second-screen presentation APIs that are particular to these routes. 103 * </p> 104 * 105 * <h3>Remote playback routes</h3> 106 * <p> 107 * Remote playback routes present media remotely by playing content from a Uri. 108 * These routes destinations take responsibility for fetching and rendering content 109 * on their own. Applications do not render the content themselves; instead, applications 110 * send control requests to initiate play, pause, resume, or stop media items and receive 111 * status updates as they change state. 112 * </p> 113 * 114 * <h4>Sessions</h4> 115 * <p> 116 * Each remote media playback action is conducted within the scope of a session. 117 * Sessions are used to prevent applications from accidentally interfering with one 118 * another because at most one session can be valid at a time. 119 * </p><p> 120 * Some actions have the side-effect of creating new sessions. If an application 121 * performs an action that has the effect of creating a new session then 122 * the previous session is invalidated and any ongoing media playback is stopped 123 * before the requested action is performed. Any attempt to use an invalidated 124 * session will result in an error. (Protocol implementations are encouraged to 125 * aggressively discard any information associated with invalidated sessions.) 126 * </p><p> 127 * A session is implicitly created when an application issues a 128 * {@link #ACTION_PLAY play action} without specifying an existing session id as a parameter. 129 * When this happens, any previous session is invalidated and the play action 130 * returns a new session id that may be used to control the session with subsequent 131 * actions such as pause, resume, or stop. 132 * </p> 133 * 134 * <h4>Media items</h4> 135 * <p> 136 * Each successful {@link #ACTION_PLAY play action} returns a unique media item id that 137 * an application can use to monitor and control playback. The media item id may be passed 138 * to other actions such as {@link #ACTION_SEEK seek} or 139 * {@link #ACTION_GET_STATUS get status}. It will also appear as a parameter in 140 * status update broadcasts to identify the associated playback request. 141 * </p><p> 142 * Each media item is scoped to the session in which it was created. Therefore media item 143 * ids are only ever used together with session ids. Media item ids are meaningless 144 * on their own. When the session is invalidated, all of its media items are also 145 * invalidated. 146 * </p> 147 * 148 * <h4>The playback queue</h4> 149 * <p> 150 * Each session has its own playback queue that consists of the media items that 151 * are pending, playing, buffering or paused. Items are added to the queue when 152 * a playback request is issued. Items are removed from the queue when they are no 153 * longer eligible for playback (enter terminal states). 154 * </p><p> 155 * As described in the {@link MediaItemStatus} class, media items initially 156 * start in a pending state, transition to the playing (or buffering or paused) state 157 * during playback, and end in a finished, canceled, invalidated or error state. 158 * Once the current item enters a terminal state, playback proceeds on to the 159 * next item. 160 * </p><p> 161 * In the current version of the protocol, the queue may contain at most one item. 162 * Each play action has the effect of clearing the queue and resetting its state 163 * before the next item is played. 164 * </p> 165 * 166 * <h4>Impact of pause, resume, stop and play actions on the playback queue</h4> 167 * <p> 168 * The pause, resume and stop actions affect the session's whole queue. Pause causes 169 * the playback queue to be suspended no matter which item is currently playing. 170 * Resume reverses the effects of pause. Stop clears the queue and also resets 171 * the pause flag just like resume. 172 * </p><p> 173 * As described earlier, the play action has the effect of clearing the queue 174 * and completely resetting its state (like the stop action) then enqueuing a 175 * new media item to be played immediately. Play is therefore equivalent 176 * to stop followed by an action to enqueue an item. 177 * </p><p> 178 * The play action is also special in that it can be used to create new sessions. 179 * An application with simple needs may find that it only needs to use play 180 * (and occasionally stop) to control playback. 181 * </p> 182 * 183 * <h4>Resolving conflicts between applications</h4> 184 * <p> 185 * When an application has a valid session, it is essentially in control of remote playback 186 * on the route. No other application can view or modify the remote playback state 187 * of that applicaton's session without knowing its id. 188 * </p><p> 189 * However, other applications can perform actions that have the effect of stopping 190 * playback and invalidating the current session. When this occurs, the former application 191 * will be informed that it has lost control by way of individual media item status 192 * update broadcasts that indicate that its queued media items have become 193 * {@link MediaItemStatus#PLAYBACK_STATE_INVALIDATED invalidated}. This broadcast 194 * implies that playback was terminated abnormally by an external cause. 195 * </p><p> 196 * Applications should handle conflicts conservatively to allow other applications to 197 * smoothly assume control over the route. When a conflict occurs, the currently playing 198 * application should release its session and allow the new application to use the 199 * route until such time as the user intervenes to take over the route again and begin 200 * a new playback session. 201 * </p> 202 * 203 * <h4>Actions</h4> 204 * <p> 205 * The following remote playback actions are defined: 206 * </p><ul> 207 * <li>{@link #ACTION_PLAY Play}: Starts playing content specified by a given Uri 208 * and returns a new media item id to describe the request. Implicitly creates a new 209 * session if no session id was specified as a parameter. 210 * <li>{@link #ACTION_SEEK Seek}: Sets the content playback position of a specific media item. 211 * <li>{@link #ACTION_GET_STATUS Get status}: Gets the status of a media item 212 * including the item's current playback position and progress. 213 * <li>{@link #ACTION_PAUSE Pause}: Pauses playback of the queue. 214 * <li>{@link #ACTION_RESUME Resume}: Resumes playback of the queue. 215 * <li>{@link #ACTION_STOP Stop}: Stops playback, clears the queue, and resets the 216 * pause state. 217 * </ul> 218 * 219 * <h4>Implementation note</h4> 220 * <p> 221 * Implementations of the remote playback protocol must implement <em>all</em> of the 222 * documented actions, parameters and results. Note that the documentation is written from 223 * the perspective of a client of the protocol. In particular, whenever a parameter 224 * is described as being "optional", it is only from the perspective of the client. 225 * Compliant media route provider implementations of this protocol must support all 226 * of the features described herein. 227 * </p> 228 */ 229public final class MediaControlIntent { 230 /** 231 * Media control category: Live audio. 232 * <p> 233 * A route that supports live audio routing will allow the media audio stream 234 * to be sent to supported destinations. This can include internal speakers or 235 * audio jacks on the device itself, A2DP devices, and more. 236 * </p><p> 237 * When a live audio route is selected, audio routing is transparent to the application. 238 * All audio played on the media stream will be routed to the selected destination. 239 * </p> 240 */ 241 public static final String CATEGORY_LIVE_AUDIO = "android.media.intent.category.LIVE_AUDIO"; 242 243 /** 244 * Media control category: Live video. 245 * <p> 246 * A route that supports live video routing will allow a mirrored version 247 * of the device's primary display or a customized 248 * {@link android.app.Presentation Presentation} to be sent to supported 249 * destinations. 250 * </p><p> 251 * When a live video route is selected, audio and video routing is transparent 252 * to the application. By default, audio and video is routed to the selected 253 * destination. For certain live video routes, the application may also use a 254 * {@link android.app.Presentation Presentation} to replace the mirrored view 255 * on the external display with different content. 256 * </p> 257 * 258 * @see MediaRouter.RouteInfo#getPresentationDisplay() 259 * @see android.app.Presentation 260 */ 261 public static final String CATEGORY_LIVE_VIDEO = "android.media.intent.category.LIVE_VIDEO"; 262 263 /** 264 * Media control category: Remote playback. 265 * <p> 266 * A route that supports remote playback routing will allow an application to send 267 * requests to play content remotely to supported destinations. 268 * </p><p> 269 * Remote playback routes destinations operate independently of the local device. 270 * When a remote playback route is selected, the application can control the content 271 * playing on the destination by sending media control actions to the route. 272 * The application may also receive status updates from the route regarding 273 * remote playback. 274 * </p> 275 * 276 * @see MediaRouter.RouteInfo#sendControlRequest 277 */ 278 public static final String CATEGORY_REMOTE_PLAYBACK = 279 "android.media.intent.category.REMOTE_PLAYBACK"; 280 281 /* Remote playback actions that affect individual items. */ 282 283 /** 284 * Remote playback media control action: Play media item. 285 * <p> 286 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 287 * media control. 288 * </p><p> 289 * This action causes a remote playback route to start playing content with 290 * the {@link Uri} specified in the {@link Intent}'s {@link Intent#getData() data uri}. 291 * The action returns a media session id and media item id which can be used 292 * to control playback using other remote playback actions. 293 * </p><p> 294 * Once initiated, playback of the specified content will be managed independently 295 * by the destination. The application will receive status updates as the state 296 * of the media item changes. 297 * </p><p> 298 * If the data uri specifies an HTTP or HTTPS scheme, then the destination is 299 * responsible for following HTTP redirects to a reasonable depth of at least 3 300 * levels as might typically be handled by a web browser. If an HTTP error 301 * occurs, then the destination should send a {@link MediaItemStatus status update} 302 * back to the client indicating the {@link MediaItemStatus#PLAYBACK_STATE_ERROR error} 303 * {@link MediaItemStatus#getPlaybackState() playback state}. 304 * </p> 305 * 306 * <h3>One item at a time</h3> 307 * <p> 308 * Each successful play action <em>replaces</em> the previous play action. 309 * If an item is already playing, then it is canceled, the session's playback queue 310 * is cleared and the new item begins playing immediately (regardless of 311 * whether the previously playing item had been paused). 312 * </p><p> 313 * Play is therefore equivalent to {@link #ACTION_STOP stop} followed by an action 314 * to enqueue a new media item to be played immediately. 315 * </p> 316 * 317 * <h3>Sessions</h3> 318 * <p> 319 * This request has the effect of implicitly creating a media session whenever the 320 * application does not specify the {@link #EXTRA_SESSION_ID session id} parameter. 321 * Because there can only be at most one valid session at a time, creating a new session 322 * has the side-effect of invalidating any existing sessions and their media items, 323 * then handling the playback request with a new session. 324 * </p><p> 325 * If the application specifies an invalid session id, then an error is returned. 326 * When this happens, the application should assume that its session 327 * is no longer valid. To obtain a new session, the application may try again 328 * and omit the session id parameter. However, the application should 329 * only retry requests due to an explicit action performed by the user, 330 * such as the user clicking on a "play" button in the UI, since another 331 * application may be trying to take control of the route and the former 332 * application should try to stay out of its way. 333 * </p><p> 334 * For more information on sessions, queues and media items, please refer to the 335 * class documentation. 336 * </p> 337 * 338 * <h3>Request parameters</h3> 339 * <ul> 340 * <li>{@link #EXTRA_SESSION_ID} <em>(optional)</em>: Specifies the session id of the 341 * session to which the playback request belongs. If omitted, a new session 342 * is created implicitly. 343 * <li>{@link #EXTRA_ITEM_CONTENT_POSITION} <em>(optional)</em>: Specifies the initial 344 * content playback position as a long integer number of milliseconds from 345 * the beginning of the content. 346 * <li>{@link #EXTRA_ITEM_METADATA} <em>(optional)</em>: Specifies metadata associated 347 * with the content such as the title of a song. 348 * <li>{@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER} <em>(optional)</em>: Specifies a 349 * {@link PendingIntent} for a broadcast receiver that will receive status updates 350 * about the media item. 351 * </ul> 352 * 353 * <h3>Result data</h3> 354 * <ul> 355 * <li>{@link #EXTRA_SESSION_ID} <em>(always returned)</em>: Specifies the session id of the 356 * session that was affected by the request. This will be a new session in 357 * the case where no session id was supplied as a parameter. 358 * <li>{@link #EXTRA_ITEM_ID} <em>(always returned)</em>: Specifies an opaque string identifier 359 * to use to refer to the media item in subsequent requests such as 360 * {@link #ACTION_GET_STATUS}. 361 * <li>{@link #EXTRA_ITEM_STATUS} <em>(always returned)</em>: Specifies the initial status of 362 * the new media item. 363 * </ul> 364 * 365 * <h3>Status updates</h3> 366 * <p> 367 * If the client supplies a {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER status update receiver} 368 * then the media route provider is responsible for sending status updates to the receiver 369 * when significant media item state changes occur such as when playback starts or 370 * stops. The receiver will not be invoked for content playback position changes. 371 * The application may retrieve the current playback position when necessary 372 * using the {@link #ACTION_GET_STATUS} request. 373 * </p><p> 374 * Refer to {@link MediaItemStatus} for details. 375 * </p> 376 * 377 * <h3>Errors</h3> 378 * <p> 379 * This action returns an error if a session id was provided but is unknown or 380 * no longer valid, if the item Uri or content type is not supported, or if 381 * any other arguments are invalid. 382 * </p> 383 * 384 * <h3>Example</h3> 385 * <pre> 386 * MediaRouter mediaRouter = MediaRouter.getInstance(context); 387 * MediaRouter.RouteInfo route = mediaRouter.getSelectedRoute(); 388 * Intent intent = new Intent(MediaControlIntent.ACTION_PLAY); 389 * intent.addCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK); 390 * intent.setDataAndType("http://example.com/videos/movie.mp4", "video/mp4"); 391 * if (route.supportsControlRequest(intent)) { 392 * MediaRouter.ControlRequestCallback callback = new MediaRouter.ControlRequestCallback() { 393 * public void onResult(Bundle data) { 394 * // The request succeeded. 395 * // Playback may be controlled using the returned session and item id. 396 * String sessionId = data.getString(MediaControlIntent.EXTRA_SESSION_ID); 397 * String itemId = data.getString(MediaControlIntent.EXTRA_ITEM_ID); 398 * MediaItemStatus status = MediaItemStatus.fromBundle(data.getBundle( 399 * MediaControlIntent.EXTRA_ITEM_STATUS)); 400 * // ... 401 * } 402 * 403 * public void onError(String message, Bundle data) { 404 * // An error occurred! 405 * } 406 * }; 407 * route.sendControlRequest(intent, callback); 408 * }</pre> 409 * 410 * @see MediaRouter.RouteInfo#sendControlRequest 411 * @see #CATEGORY_REMOTE_PLAYBACK 412 * @see #ACTION_SEEK 413 * @see #ACTION_GET_STATUS 414 * @see #ACTION_PAUSE 415 * @see #ACTION_RESUME 416 * @see #ACTION_STOP 417 */ 418 public static final String ACTION_PLAY = "android.media.intent.action.PLAY"; 419 420 /** 421 * Remote playback media control action: Enqueue media item. 422 * <p> 423 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 424 * media control. 425 * </p><p> 426 * This action works just like {@link #ACTION_PLAY play} except that it does 427 * not clear the queue or reset the pause state when it enqueues the 428 * new media item into the session's playback queue. This action only 429 * enqueues a media item with no other side-effects on the queue. 430 * </p><p> 431 * If the queue is currently empty and then the item will play immediately 432 * (assuming the queue is not paused). Otherwise, the item will play 433 * after all earlier items in the queue have finished or been removed. 434 * </p><p> 435 * The enqueue action can be used to create new sessions just like play. 436 * Its parameters and results are also the same. Only the queuing behavior 437 * is different. 438 * </p> 439 * 440 * @see #ACTION_PLAY 441 * 442 * @hide Pending API review. 443 */ 444 public static final String ACTION_ENQUEUE = "android.media.intent.action.ENQUEUE"; 445 446 /** 447 * Remote playback media control action: Seek media item to a new playback position. 448 * <p> 449 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 450 * media control. 451 * </p><p> 452 * This action causes a remote playback route to modify the current playback position 453 * of the specified media item. 454 * </p><p> 455 * This action only affects the playback position of the media item; not its playback state. 456 * If the playback queue is paused, then seeking sets the position but the item 457 * remains paused. Likewise if the item is playing, then seeking will cause playback 458 * to jump to the new position and continue playing from that point. If the item has 459 * not yet started playing, then the new playback position is remembered by the 460 * queue and used as the item's initial content position when playback eventually begins. 461 * </p><p> 462 * If successful, the media item's playback position is changed. 463 * </p> 464 * 465 * <h3>Request parameters</h3> 466 * <ul> 467 * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of the session 468 * to which the media item belongs. 469 * <li>{@link #EXTRA_ITEM_ID} <em>(required)</em>: Specifies the media item id of 470 * the media item to seek. 471 * <li>{@link #EXTRA_ITEM_CONTENT_POSITION} <em>(required)</em>: Specifies the new 472 * content position for playback as a long integer number of milliseconds from 473 * the beginning of the content. 474 * </ul> 475 * 476 * <h3>Result data</h3> 477 * <ul> 478 * <li>{@link #EXTRA_ITEM_STATUS} <em>(always returned)</em>: Specifies the new status of 479 * the media item. 480 * </ul> 481 * 482 * <h3>Errors</h3> 483 * <p> 484 * This action returns an error if the session id or media item id are unknown 485 * or no longer valid, if the content position is invalid, or if the media item 486 * is in a terminal state. 487 * </p> 488 * 489 * @see MediaRouter.RouteInfo#sendControlRequest 490 * @see #CATEGORY_REMOTE_PLAYBACK 491 */ 492 public static final String ACTION_SEEK = "android.media.intent.action.SEEK"; 493 494 /** 495 * Remote playback media control action: Get media item playback status 496 * and progress information. 497 * <p> 498 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 499 * media control. 500 * </p><p> 501 * This action asks a remote playback route to provide updated playback status and progress 502 * information about the specified media item. 503 * </p> 504 * 505 * <h3>Request parameters</h3> 506 * <ul> 507 * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of the session 508 * to which the media item belongs. 509 * <li>{@link #EXTRA_ITEM_ID} <em>(required)</em>: Specifies the media item id of 510 * the media item to query. 511 * </ul> 512 * 513 * <h3>Result data</h3> 514 * <ul> 515 * <li>{@link #EXTRA_ITEM_STATUS} <em>(always returned)</em>: Specifies the current status of 516 * the media item. 517 * </ul> 518 * 519 * <h3>Errors</h3> 520 * <p> 521 * This action returns an error if the session id or media item id are unknown 522 * or no longer valid. 523 * </p> 524 * 525 * @see MediaRouter.RouteInfo#sendControlRequest 526 * @see #CATEGORY_REMOTE_PLAYBACK 527 * @see #EXTRA_ITEM_STATUS_UPDATE_RECEIVER 528 */ 529 public static final String ACTION_GET_STATUS = "android.media.intent.action.GET_STATUS"; 530 531 /** 532 * Remote playback media control action: Remove media item from session's queue. 533 * <p> 534 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 535 * media control. 536 * </p><p> 537 * This action asks a remote playback route to remove the specified media item 538 * from the session's playback queue. If the current item is removed, then 539 * playback will proceed to the next media item (assuming the queue has not been 540 * paused). 541 * </p><p> 542 * This action does not affect the pause state of the queue. If the queue was paused 543 * then it remains paused (even if it is now empty) until a resume, stop or play 544 * action is issued that causes the pause state to be cleared. 545 * </p> 546 * 547 * <h3>Request parameters</h3> 548 * <ul> 549 * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of the session 550 * to which the media item belongs. 551 * <li>{@link #EXTRA_ITEM_ID} <em>(required)</em>: Specifies the media item id of 552 * the media item to remove. 553 * </ul> 554 * 555 * <h3>Result data</h3> 556 * <ul> 557 * <li>{@link #EXTRA_ITEM_STATUS} <em>(always returned)</em>: Specifies the new status of 558 * the media item. 559 * </ul> 560 * 561 * <h3>Errors</h3> 562 * <p> 563 * This action returns an error if the session id or media item id are unknown 564 * or no longer valid, or if the media item is in a terminal state (and therefore 565 * no longer in the queue). 566 * </p> 567 * 568 * @see MediaRouter.RouteInfo#sendControlRequest 569 * @see #CATEGORY_REMOTE_PLAYBACK 570 * 571 * @hide Pending API review. 572 */ 573 public static final String ACTION_REMOVE = "android.media.intent.action.REMOVE"; 574 575 /* Remote playback actions that affect the whole playback queue. */ 576 577 /** 578 * Remote playback media control action: Pause media playback. 579 * <p> 580 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 581 * media control. 582 * </p><p> 583 * This action causes the playback queue of the specified session to be paused. 584 * </p> 585 * 586 * <h3>Request parameters</h3> 587 * <ul> 588 * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of the session 589 * whose playback queue is to be paused. 590 * </ul> 591 * 592 * <h3>Result data</h3> 593 * <ul> 594 * <li><em>None</em> 595 * </ul> 596 * 597 * <h3>Errors</h3> 598 * <p> 599 * This action returns an error if the session id is unknown or no longer valid. 600 * </p> 601 * 602 * @see MediaRouter.RouteInfo#sendControlRequest 603 * @see #CATEGORY_REMOTE_PLAYBACK 604 * @see #ACTION_RESUME 605 */ 606 public static final String ACTION_PAUSE = "android.media.intent.action.PAUSE"; 607 608 /** 609 * Remote playback media control action: Resume media playback (unpause). 610 * <p> 611 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 612 * media control. 613 * </p><p> 614 * This action causes the playback queue of the specified session to be resumed. 615 * Reverses the effects of {@link #ACTION_PAUSE}. 616 * </p> 617 * 618 * <h3>Request parameters</h3> 619 * <ul> 620 * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of the session 621 * whose playback queue is to be resumed. 622 * </ul> 623 * 624 * <h3>Result data</h3> 625 * <ul> 626 * <li><em>None</em> 627 * </ul> 628 * 629 * <h3>Errors</h3> 630 * <p> 631 * This action returns an error if the session id is unknown or no longer valid. 632 * </p> 633 * 634 * @see MediaRouter.RouteInfo#sendControlRequest 635 * @see #CATEGORY_REMOTE_PLAYBACK 636 * @see #ACTION_PAUSE 637 */ 638 public static final String ACTION_RESUME = "android.media.intent.action.RESUME"; 639 640 /** 641 * Remote playback media control action: Stop media playback (clear queue and unpause). 642 * <p> 643 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 644 * media control. 645 * </p><p> 646 * This action causes a remote playback route to stop playback, cancel and remove 647 * all media items from the session's media item queue and, reset the queue's 648 * pause state. 649 * </p><p> 650 * If successful, the status of all media items in the queue is set to 651 * {@link MediaItemStatus#PLAYBACK_STATE_CANCELED canceled} and a status update is sent 652 * to the appropriate status update receivers indicating the new status of each item. 653 * </p> 654 * 655 * <h3>Request parameters</h3> 656 * <ul> 657 * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of 658 * the session whose playback queue is to be stopped (cleared and unpaused). 659 * </ul> 660 * 661 * <h3>Result data</h3> 662 * <ul> 663 * <li><em>None</em> 664 * </ul> 665 * 666 * <h3>Errors</h3> 667 * <p> 668 * This action returns an error if the session id is unknown or no longer valid. 669 * </p> 670 * 671 * @see MediaRouter.RouteInfo#sendControlRequest 672 * @see #CATEGORY_REMOTE_PLAYBACK 673 */ 674 public static final String ACTION_STOP = "android.media.intent.action.STOP"; 675 676 /** 677 * Bundle extra: Media session id. 678 * <p> 679 * An opaque unique identifier that identifies the remote playback media session. 680 * The session id is returned by {@link #ACTION_PLAY} along with the media item id 681 * of the requested content. 682 * </p><p> 683 * Used with various actions to specify the id of the media session to be controlled. 684 * </p><p> 685 * Included in broadcast intents sent to 686 * {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER status update receivers} to identify 687 * the session to which the item in question belongs. 688 * </p><p> 689 * The value is a unique string value generated by the media route provider 690 * to represent one particular media session. 691 * </p> 692 * 693 * @see #ACTION_PLAY 694 * @see #ACTION_SEEK 695 * @see #ACTION_GET_STATUS 696 * @see #ACTION_PAUSE 697 * @see #ACTION_RESUME 698 * @see #ACTION_STOP 699 */ 700 public static final String EXTRA_SESSION_ID = 701 "android.media.intent.extra.SESSION_ID"; 702 703 /** 704 * Bundle extra: Media item id. 705 * <p> 706 * An opaque unique identifier returned as a result from {@link #ACTION_PLAY} that 707 * represents the media item that was created by the playback request. 708 * </p><p> 709 * Used with various actions to specify the id of the media item to be controlled. 710 * </p><p> 711 * Included in broadcast intents sent to 712 * {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER status update receivers} to identify 713 * the item in question. 714 * </p><p> 715 * The value is a unique string value generated by the media route provider 716 * to represent one particular media item. 717 * </p> 718 * 719 * @see #ACTION_PLAY 720 * @see #ACTION_SEEK 721 * @see #ACTION_GET_STATUS 722 */ 723 public static final String EXTRA_ITEM_ID = 724 "android.media.intent.extra.ITEM_ID"; 725 726 /** 727 * Bundle extra: Media item status. 728 * <p> 729 * Returned as a result from media item actions such as {@link #ACTION_PLAY}, 730 * a{@link #ACTION_SEEK}, and {@link #ACTION_GET_STATUS} 731 * to describe the status of the specified media item. 732 * </p><p> 733 * Included in broadcast intents sent to 734 * {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER status update receivers} to provide 735 * updated status information. 736 * </p><p> 737 * The value is a {@link android.os.Bundle} of data that can be converted into 738 * a {@link MediaItemStatus} object using 739 * {@link MediaItemStatus#fromBundle MediaItemStatus.fromBundle}. 740 * </p> 741 * 742 * @see #ACTION_PLAY 743 * @see #ACTION_SEEK 744 * @see #ACTION_GET_STATUS 745 */ 746 public static final String EXTRA_ITEM_STATUS = 747 "android.media.intent.extra.ITEM_STATUS"; 748 749 /** 750 * Long extra: Media item content position. 751 * <p> 752 * Used with {@link #ACTION_PLAY} to specify the starting playback position. 753 * </p><p> 754 * Used with {@link #ACTION_SEEK} to set a new playback position. 755 * </p><p> 756 * The value is a long integer number of milliseconds from the beginning of the content. 757 * <p> 758 * 759 * @see #ACTION_PLAY 760 * @see #ACTION_SEEK 761 */ 762 public static final String EXTRA_ITEM_CONTENT_POSITION = 763 "android.media.intent.extra.ITEM_POSITION"; 764 765 /** 766 * Bundle extra: Media item metadata. 767 * <p> 768 * Used with {@link #ACTION_PLAY} to specify metadata associated with the content 769 * of a media item. 770 * </p><p> 771 * The value is a {@link android.os.Bundle} of metadata key-value pairs as defined 772 * in {@link MediaItemMetadata}. 773 * </p> 774 * 775 * @see #ACTION_PLAY 776 */ 777 public static final String EXTRA_ITEM_METADATA = 778 "android.media.intent.extra.ITEM_METADATA"; 779 780 /** 781 * Bundle extra: HTTP request headers. 782 * <p> 783 * Used with {@link #ACTION_PLAY} to specify HTTP request headers to be 784 * included when fetching to the content indicated by the media item's data Uri. 785 * </p><p> 786 * This extra may be used to provide authentication tokens and other 787 * parameters to the server separately from the media item's data Uri. 788 * </p><p> 789 * The value is a {@link android.os.Bundle} of string based key-value pairs 790 * that describe the HTTP request headers. 791 * </p> 792 * 793 * @see #ACTION_PLAY 794 * 795 * @hide Pending API review. 796 */ 797 public static final String EXTRA_ITEM_HTTP_HEADERS = 798 "android.media.intent.extra.HTTP_HEADERS"; 799 800 /** 801 * Bundle extra: Media item status update receiver. 802 * <p> 803 * Used with {@link #ACTION_PLAY} to specify a {@link PendingIntent} for a 804 * broadcast receiver that will receive status updates about a particular 805 * media item. 806 * </p><p> 807 * Whenever the status of the media item changes, the media route provider will 808 * send a broadcast to the pending intent with extras that identify the queue 809 * to which the item belongs, the item itself and the item's updated status. 810 * </p><p> 811 * The same pending intent and broadcast receiver may be shared by any number of 812 * media items since the broadcast intent includes the media session id 813 * and media item id. 814 * </p><p> 815 * The value is a {@link PendingIntent}. 816 * </p> 817 * 818 * <h3>Broadcast extras</h3> 819 * <ul> 820 * <li>{@link #EXTRA_SESSION_ID} <em>(required)</em>: Specifies the session id of 821 * the session to which the item in question belongs. 822 * <li>{@link #EXTRA_ITEM_ID} <em>(required)</em>: Specifies the media item id of the 823 * media item in question. 824 * <li>{@link #EXTRA_ITEM_STATUS} <em>(required)</em>: Specifies the status of the 825 * item as a bundle that can be decoded into a {@link MediaItemStatus} object. 826 * </ul> 827 * 828 * @see #ACTION_PLAY 829 */ 830 public static final String EXTRA_ITEM_STATUS_UPDATE_RECEIVER = 831 "android.media.intent.extra.ITEM_STATUS_UPDATE_RECEIVER"; 832 833 private MediaControlIntent() { 834 } 835} 836