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