MediaControlIntent.java revision ba811896e3057cb48ad0f017efe1bf0c262430ec
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 * 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 playback, pause, resume, or manipulate queues of 111 * media items and receive status updates when the state of each item changes. 112 * This allows applications to queue several items to play one after another and 113 * provide feedback to the user as playback progresses. 114 * </p> 115 * 116 * <h4>Actions</h4> 117 * <p> 118 * The following actions are defined: 119 * </p><ul> 120 * <li>{@link #ACTION_PLAY Play}: Starts playing or enqueues content specified by a given Uri 121 * and returns a new media item id to describe the request. Implicitly creates a new 122 * queue of media items if none was specified. 123 * <li>{@link #ACTION_CANCEL Cancel}: Cancels playback of a media item and removes it 124 * from the queue of items to be played. 125 * <li>{@link #ACTION_SEEK Seek}: Sets the content playback position of a media item. 126 * <li>{@link #ACTION_GET_STATUS Get status}: Gets the status of a media item including 127 * the item's current playback position and progress. 128 * <li>{@link #ACTION_PAUSE_QUEUE Pause queue}: Pauses a queue of media items. 129 * <li>{@link #ACTION_RESUME_QUEUE Resume queue}: Resumes a queue of media items. 130 * <li>{@link #ACTION_CLEAR_QUEUE Clear queue}: Cancels and removes all items from a 131 * media queue. 132 * </ul> 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_CANCEL cancel}, {@link #ACTION_SEEK seek} 139 * or {@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> 142 * 143 * <h4>Queues</h4> 144 * <p> 145 * Each successful {@link #ACTION_PLAY play action} has the effect of adding a new media 146 * item to a queue of media items to be played. Queues are created implicitly as part 147 * of issuing playback requests and are identified by unique queue ids. 148 * </p><p> 149 * There is at most one valid queue in existence at any given time for a given route. 150 * If an application sends a request that has the effect of creating a new queue then 151 * the previously valid queue is cleared and all of its items are canceled before the 152 * new queue is created. In this way, one application can determine when another 153 * application has taken control of a route because its own items will all be canceled 154 * as soon as the other application begins playing something else. 155 * </p><p> 156 * Queues are intended to hold a small number of items to help media routes optimize 157 * the playback experience. As each item in the queue completes playback, the next item 158 * in the queue should begin playing immediately without delay. 159 * </p><p> 160 * It is usually sufficient for an application to enqueue no more than a few items at a time 161 * to ensure continuous playback. Typically the application will start by enqueuing two 162 * media items at once: one item to play now and one item to play next. When the first 163 * item finishes, the second item will begin playing immediately. The application will 164 * receive one status update broadcast indicating that the first item finished playing 165 * and another status update broadcast indicating that the second item has started playing. 166 * Upon receipt of such broadcasts, the application may choose to enqueue another media 167 * item to play once the second one finishes. 168 * </p><p> 169 * Media route providers are required to support queues of at least 3 items. 170 * </p> 171 */ 172public final class MediaControlIntent { 173 /** 174 * Media control category: Live audio. 175 * <p> 176 * A route that supports live audio routing will allow the media audio stream 177 * to be sent to supported destinations. This can include internal speakers or 178 * audio jacks on the device itself, A2DP devices, and more. 179 * </p><p> 180 * When a live audio route is selected, audio routing is transparent to the application. 181 * All audio played on the media stream will be routed to the selected destination. 182 * </p> 183 */ 184 public static final String CATEGORY_LIVE_AUDIO = "android.media.intent.category.LIVE_AUDIO"; 185 186 /** 187 * Media control category: Live video. 188 * <p> 189 * A route that supports live video routing will allow a mirrored version 190 * of the device's primary display or a customized 191 * {@link android.app.Presentation Presentation} to be sent to supported 192 * destinations. 193 * </p><p> 194 * When a live video route is selected, audio and video routing is transparent 195 * to the application. By default, audio and video is routed to the selected 196 * destination. For certain live video routes, the application may also use a 197 * {@link android.app.Presentation Presentation} to replace the mirrored view 198 * on the external display with different content. 199 * </p> 200 * 201 * @see MediaRouter.RouteInfo#getPresentationDisplay() 202 * @see android.app.Presentation 203 */ 204 public static final String CATEGORY_LIVE_VIDEO = "android.media.intent.category.LIVE_VIDEO"; 205 206 /** 207 * Media control category: Remote playback. 208 * <p> 209 * A route that supports remote playback routing will allow an application to send 210 * requests to play content remotely to supported destinations. 211 * </p><p> 212 * Remote playback routes destinations operate independently of the local device. 213 * When a remote playback route is selected, the application can control the content 214 * playing on the destination by sending media control actions to the route. 215 * The application may also receive status updates from the route regarding 216 * remote playback. 217 * </p> 218 * 219 * @see MediaRouter.RouteInfo#sendControlRequest 220 */ 221 public static final String CATEGORY_REMOTE_PLAYBACK = 222 "android.media.intent.category.REMOTE_PLAYBACK"; 223 224 /** 225 * Media control action: Play media item. 226 * <p> 227 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 228 * media control. 229 * </p><p> 230 * This action causes a remote playback route to start playing content with 231 * the {@link Uri} specified in the {@link Intent}'s {@link Intent#getData() data uri}. 232 * The action returns a media item id which can be used to control playback 233 * using other remote playback actions. 234 * </p><p> 235 * Once initiated, playback of the specified content will be queued and managed 236 * independently by the destination. The application will receive status updates 237 * as the content is played. 238 * </p><p> 239 * If the data uri specifies an HTTP or HTTPS scheme, then the destination is 240 * responsible for following HTTP redirects to a reasonable depth of at least 3 241 * levels as might typically be handled by a web browser. If an HTTP error 242 * occurs, then the destination should send a {@link MediaItemStatus status update} 243 * back to the client indicating the {@link MediaItemStatus#PLAYBACK_STATE_ERROR error} 244 * {@link MediaItemStatus#getPlaybackState() playback state} 245 * and include the {@link MediaItemStatus#getHttpStatusCode() HTTP status code}. 246 * </p> 247 * 248 * <h3>Queuing</h3> 249 * <p> 250 * This request has the effect of implicitly creating a media queue whenever the 251 * application does not specify the {@link #EXTRA_QUEUE_ID} parameter. Because there 252 * can only be one valid queue at a time, creating a new queue has the side-effect 253 * of invalidating any existing queues and canceling all of their items before 254 * enqueuing the new playback request media item onto the newly created queue. 255 * </p><p> 256 * If the application specifies an invalid queue id, then the request has no effect 257 * and an error is returned. The application may then ask that a new queue be 258 * created (and the current one invalidated) by issuing a new playback request without 259 * a queue id parameter. However, it should only do this at the user's request 260 * (say, by the user explicitly clicking a play button) since another application may 261 * be trying to take control of the route. 262 * </p><p> 263 * For more information on queuing, please refer to the class documentation. 264 * </p> 265 * 266 * <h3>Request parameters</h3> 267 * <ul> 268 * <li>{@link #EXTRA_QUEUE_ID} <i>(optional)</i>: specifies the queue id of the queue 269 * to which the new playback request should be appended. If omitted, a new queue 270 * is created. 271 * <li>{@link #EXTRA_ITEM_CONTENT_POSITION} <i>(optional)</i>: specifies the initial 272 * content playback position as a long integer number of milliseconds from 273 * the beginning of the content. 274 * <li>{@link #EXTRA_ITEM_METADATA} <i>(optional)</i>: specifies metadata associated 275 * with the content such as the title of a song. 276 * <li>{@link #EXTRA_ITEM_HTTP_HEADERS} <i>(optional)</i>: specifies HTTP headers to 277 * supply to the server when fetching the content. 278 * <li>{@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER} <i>(optional)</i>: specifies a 279 * {@link PendingIntent} for a broadcast receiver that will receive status updates 280 * about the media item. 281 * </ul> 282 * 283 * <h3>Result data</h3> 284 * <ul> 285 * <li>{@link #EXTRA_QUEUE_ID} <i>(required)</i>: specifies the queue id of the queue 286 * to which the new media item was appended. This will be a new queue in 287 * the case where no queue id was supplied as a parameter. 288 * <li>{@link #EXTRA_ITEM_ID} <i>(required)</i>: specifies an opaque string identifier 289 * to use to refer to the media item in subsequent requests such as {@link #ACTION_CANCEL}. 290 * <li>{@link #EXTRA_ITEM_STATUS} <i>(required)</i>: specifies the initial status of 291 * the item that has been enqueued. 292 * </ul> 293 * 294 * <h3>Status updates</h3> 295 * <p> 296 * If the client supplies a {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER status update receiver} 297 * then the media route provider is responsible for sending status updates to the receiver 298 * when significant media item state changes occur such as when playback starts or 299 * stops. The receiver will not be invoked for content playback position changes. 300 * The application may retrieve the current playback position when necessary 301 * using the {@link #ACTION_GET_STATUS} request. 302 * </p><p> 303 * Refer to {@link MediaItemStatus} for details. 304 * </p> 305 * 306 * <h3>Example</h3> 307 * <pre> 308 * MediaRouter mediaRouter = MediaRouter.getInstance(context); 309 * MediaRouter.RouteInfo route = mediaRouter.getSelectedRoute(); 310 * Intent intent = new Intent(MediaControlIntent.ACTION_PLAY); 311 * intent.addCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK); 312 * intent.setDataAndType("http://example.com/videos/movie.mp4", "video/mp4"); 313 * if (route.supportsControlRequest(intent)) { 314 * MediaRouter.ControlRequestCallback callback = new MediaRouter.ControlRequestCallback() { 315 * public void onResult(Bundle data) { 316 * // The request succeeded. 317 * // Playback may be controlled using the returned queue and item id. 318 * String queueId = data.getString(MediaControlIntent.EXTRA_QUEUE_ID); 319 * String itemId = data.getString(MediaControlIntent.EXTRA_ITEM_ID); 320 * MediaItemStatus status = MediaItemStatus.fromBundle(data.getBundle( 321 * MediaControlIntent.EXTRA_ITEM_STATUS)); 322 * // ... 323 * } 324 * 325 * public void onError(String message, Bundle data) { 326 * // An error occurred! 327 * } 328 * }; 329 * route.sendControlRequest(intent, callback); 330 * }</pre> 331 * 332 * @see MediaRouter.RouteInfo#sendControlRequest 333 * @see #CATEGORY_REMOTE_PLAYBACK 334 * @see #ACTION_CANCEL 335 * @see #ACTION_SEEK 336 * @see #ACTION_GET_STATUS 337 */ 338 public static final String ACTION_PLAY = "android.media.intent.action.PLAY"; 339 340 /** 341 * Media control action: Cancel media item playback. 342 * <p> 343 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 344 * media control. 345 * </p><p> 346 * This action causes a remote playback route to cancel playback of the 347 * specified media item and remove it from the queue. 348 * </p><p> 349 * This action has no effect if the media item's status is 350 * {@link MediaItemStatus#PLAYBACK_STATE_CANCELED} or 351 * {@link MediaItemStatus#PLAYBACK_STATE_ERROR}. 352 * Otherwise the media item's status is set to 353 * {@link MediaItemStatus#PLAYBACK_STATE_CANCELED}, playback of this media item is 354 * stopped if it had been playing and the item is removed from the queue (skipped). 355 * </p><p> 356 * A status update is sent to the status update receiver indicating the new status 357 * of the item. 358 * </p> 359 * 360 * <h3>Request parameters</h3> 361 * <ul> 362 * <li>{@link #EXTRA_QUEUE_ID} <i>(required)</i>: specifies the queue id of the queue 363 * to which the media item belongs. 364 * <li>{@link #EXTRA_ITEM_ID} (required): specifies the media item id of media item 365 * to cancel. 366 * </ul> 367 * 368 * <h3>Result data</h3> 369 * <ul> 370 * <li>{@link #EXTRA_ITEM_STATUS} <i>(required)</i>: specifies the new status of the item. 371 * </ul> 372 * 373 * @see MediaRouter.RouteInfo#sendControlRequest 374 * @see #CATEGORY_REMOTE_PLAYBACK 375 */ 376 public static final String ACTION_CANCEL = "android.media.intent.action.CANCEL"; 377 378 /** 379 * Media control action: Seek media item to a new playback position. 380 * <p> 381 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 382 * media control. 383 * </p><p> 384 * This action causes a remote playback route to modify the current playback 385 * position of the specified media item. 386 * </p><p> 387 * This action only affects the playback position of the media item; not its playback state. 388 * If the item is paused, then seeking sets the position but the item remains paused. 389 * Likewise if the item is playing, then seeking will cause playback to jump to the 390 * new position and continue playing from that point. If the item has not yet started 391 * playing, then the new playback position is be remembered and used as the item's 392 * initial content position when playback eventually begins. 393 * </p> 394 * 395 * <h3>Request parameters</h3> 396 * <ul> 397 * <li>{@link #EXTRA_QUEUE_ID} <i>(required)</i>: specifies the queue id of the queue 398 * to which the media item belongs. 399 * <li>{@link #EXTRA_ITEM_ID} <i>(required)</i>: specifies the media item id of 400 * the media item to seek. 401 * <li>{@link #EXTRA_ITEM_CONTENT_POSITION} <i>(required)</i>: specifies the new 402 * content position for playback as a long integer number of milliseconds from 403 * the beginning of the content. 404 * </ul> 405 * 406 * <h3>Result data</h3> 407 * <ul> 408 * <li>{@link #EXTRA_ITEM_STATUS} <i>(required)</i>: specifies the new status of the item. 409 * </ul> 410 * 411 * @see MediaRouter.RouteInfo#sendControlRequest 412 * @see #CATEGORY_REMOTE_PLAYBACK 413 */ 414 public static final String ACTION_SEEK = "android.media.intent.action.SEEK"; 415 416 /** 417 * Media control action: Get media item playback status and progress information. 418 * <p> 419 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 420 * media control. 421 * </p><p> 422 * This action asks a remote playback route to provide updated playback status and progress 423 * information about the specified media item. 424 * </p> 425 * 426 * <h3>Request parameters</h3> 427 * <ul> 428 * <li>{@link #EXTRA_QUEUE_ID} <i>(required)</i>: specifies the queue id of the queue 429 * to which the media item belongs. 430 * <li>{@link #EXTRA_ITEM_ID} <i>(required)</i>: specifies the media item id of 431 * the media item to query. 432 * </ul> 433 * 434 * <h3>Result data</h3> 435 * <ul> 436 * <li>{@link #EXTRA_ITEM_STATUS} <i>(required)</i>: specifies the current status of the item. 437 * </ul> 438 * 439 * @see MediaRouter.RouteInfo#sendControlRequest 440 * @see #CATEGORY_REMOTE_PLAYBACK 441 * @see #EXTRA_ITEM_STATUS_UPDATE_RECEIVER 442 */ 443 public static final String ACTION_GET_STATUS = "android.media.intent.action.GET_STATUS"; 444 445 /** 446 * Media control action: Pause media queue playback. 447 * <p> 448 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 449 * media control. 450 * </p><p> 451 * This action causes playback on the specified media queue to be paused. 452 * </p> 453 * 454 * <h3>Request parameters</h3> 455 * <ul> 456 * <li>{@link #EXTRA_QUEUE_ID} <i>(required)</i>: specifies the queue id of the queue 457 * to be paused. 458 * </ul> 459 * 460 * <h3>Result data</h3> 461 * <ul> 462 * <li><i>None</i> 463 * </ul> 464 * 465 * @see MediaRouter.RouteInfo#sendControlRequest 466 * @see #CATEGORY_REMOTE_PLAYBACK 467 * @see #ACTION_RESUME_QUEUE 468 */ 469 public static final String ACTION_PAUSE_QUEUE = "android.media.intent.action.PAUSE_QUEUE"; 470 471 /** 472 * Media control action: Resume media queue playback (unpause). 473 * <p> 474 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 475 * media control. 476 * </p><p> 477 * This action causes playback on the specified media queue to be resumed. 478 * Reverses the effects of {@link #ACTION_PAUSE_QUEUE}. 479 * </p> 480 * 481 * <h3>Request parameters</h3> 482 * <ul> 483 * <li>{@link #EXTRA_QUEUE_ID} <i>(required)</i>: specifies the queue id of the queue 484 * to be resumed. 485 * </ul> 486 * 487 * <h3>Result data</h3> 488 * <ul> 489 * <li><i>None</i> 490 * </ul> 491 * 492 * @see MediaRouter.RouteInfo#sendControlRequest 493 * @see #CATEGORY_REMOTE_PLAYBACK 494 * @see #ACTION_PAUSE_QUEUE 495 */ 496 public static final String ACTION_RESUME_QUEUE = "android.media.intent.action.RESUME_QUEUE"; 497 498 /** 499 * Media control action: Clear media queue. 500 * <p> 501 * Used with routes that support {@link #CATEGORY_REMOTE_PLAYBACK remote playback} 502 * media control. 503 * </p><p> 504 * This action causes all media items in the specified media queue to be canceled 505 * and removed. The queue is left in an empty state. 506 * </p> 507 * 508 * <h3>Request parameters</h3> 509 * <ul> 510 * <li>{@link #EXTRA_QUEUE_ID} <i>(required)</i>: specifies the queue id of the queue 511 * to be cleared. 512 * </ul> 513 * 514 * <h3>Result data</h3> 515 * <ul> 516 * <li><i>None</i> 517 * </ul> 518 * 519 * @see MediaRouter.RouteInfo#sendControlRequest 520 * @see #CATEGORY_REMOTE_PLAYBACK 521 */ 522 public static final String ACTION_CLEAR_QUEUE = "android.media.intent.action.CLEAR_QUEUE"; 523 524 /** 525 * Bundle extra: Media queue id. 526 * <p> 527 * An opaque unique identifier returned as a result from {@link #ACTION_PLAY} that 528 * represents the queue of media items to which an item was appended. Subsequent 529 * playback requests may specify the same queue id to enqueue addition items onto 530 * the same queue. 531 * </p><p> 532 * Used with various actions to specify the id of the media queue to be controlled. 533 * </p><p> 534 * Included in broadcast intents sent to 535 * {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER status update receivers} to identify 536 * the queue to which the item in question belongs. 537 * </p><p> 538 * The value is a unique string value generated by the media route provider 539 * to represent one particular media queue. 540 * </p> 541 * 542 * @see #ACTION_PLAY 543 * @see #ACTION_CANCEL 544 * @see #ACTION_SEEK 545 * @see #ACTION_GET_STATUS 546 * @see #ACTION_PAUSE_QUEUE 547 * @see #ACTION_RESUME_QUEUE 548 * @see #ACTION_CLEAR_QUEUE 549 */ 550 public static final String EXTRA_QUEUE_ID = 551 "android.media.intent.extra.QUEUE_ID"; 552 553 /** 554 * Bundle extra: Media item id. 555 * <p> 556 * An opaque unique identifier returned as a result from {@link #ACTION_PLAY} that 557 * represents the media item that was created by the playback request. 558 * </p><p> 559 * Used with various actions to specify the id of the media item to be controlled. 560 * </p><p> 561 * Included in broadcast intents sent to 562 * {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER status update receivers} to identify 563 * the item in question. 564 * </p><p> 565 * The value is a unique string value generated by the media route provider 566 * to represent one particular media item. 567 * </p> 568 * 569 * @see #ACTION_PLAY 570 * @see #ACTION_CANCEL 571 * @see #ACTION_SEEK 572 * @see #ACTION_GET_STATUS 573 */ 574 public static final String EXTRA_ITEM_ID = 575 "android.media.intent.extra.ITEM_ID"; 576 577 /** 578 * Bundle extra: Media item status. 579 * <p> 580 * Returned as a result from media item actions such as {@link #ACTION_PLAY}, 581 * {@link #ACTION_SEEK}, {@link #ACTION_CANCEL} and {@link #ACTION_GET_STATUS} 582 * to describe the status of the relevant media item. 583 * </p><p> 584 * Included in broadcast intents sent to 585 * {@link #EXTRA_ITEM_STATUS_UPDATE_RECEIVER status update receivers} to provide 586 * updated status information. 587 * </p><p> 588 * The value is a {@link android.os.Bundle} of data that can be converted into 589 * a {@link MediaItemStatus} object using 590 * {@link MediaItemStatus#fromBundle MediaItemStatus.fromBundle}. 591 * </p> 592 * 593 * @see #ACTION_PLAY 594 * @see #ACTION_CANCEL 595 * @see #ACTION_SEEK 596 * @see #ACTION_GET_STATUS 597 */ 598 public static final String EXTRA_ITEM_STATUS = 599 "android.media.intent.extra.ITEM_STATUS"; 600 601 /** 602 * Long extra: Media item content position. 603 * <p> 604 * Used with {@link #ACTION_PLAY} to specify the starting playback position. 605 * </p><p> 606 * Used with {@link #ACTION_SEEK} to set a new playback position. 607 * </p><p> 608 * The value is a long integer number of milliseconds from the beginning of the content. 609 * <p> 610 * 611 * @see #ACTION_PLAY 612 * @see #ACTION_SEEK 613 */ 614 public static final String EXTRA_ITEM_CONTENT_POSITION = 615 "android.media.intent.extra.ITEM_POSITION"; 616 617 /** 618 * Bundle extra: Media item metadata. 619 * <p> 620 * Used with {@link #ACTION_PLAY} to specify metadata associated with the content 621 * of a media item. 622 * </p><p> 623 * The value is a {@link android.os.Bundle} of metadata key-value pairs as defined 624 * in {@link MediaItemMetadata}. 625 * </p> 626 * 627 * @see #ACTION_PLAY 628 */ 629 public static final String EXTRA_ITEM_METADATA = 630 "android.media.intent.extra.ITEM_METADATA"; 631 632 /** 633 * Bundle extra: HTTP headers. 634 * <p> 635 * Used with {@link #ACTION_PLAY} to specify HTTP headers to be included when 636 * fetching to the content indicated by the media item's data Uri. 637 * </p><p> 638 * This extra may be used to provide authentication tokens and other 639 * parameters to the server separately from the media item's data Uri. 640 * </p><p> 641 * The value is a {@link android.os.Bundle} of string based key-value pairs 642 * that describe the HTTP headers. 643 * </p> 644 * 645 * @see #ACTION_PLAY 646 */ 647 public static final String EXTRA_ITEM_HTTP_HEADERS = 648 "android.media.intent.extra.HTTP_HEADERS"; 649 650 /** 651 * Bundle extra: Media item status update receiver. 652 * <p> 653 * Used with {@link #ACTION_PLAY} to specify a {@link PendingIntent} for a 654 * broadcast receiver that will receive status updates about a particular 655 * media item. 656 * </p><p> 657 * Whenever the status of the media item changes, the media route provider will 658 * send a broadcast to the pending intent with extras that identify the queue 659 * to which the item belongs, the item itself and the item's updated status. 660 * </p><p> 661 * The same pending intent and broadcast receiver may be shared by any number of 662 * media items since the broadcast intent includes the media queue id and media item id. 663 * </p><p> 664 * The value is a {@link PendingIntent}. 665 * </p> 666 * 667 * <h3>Broadcast extras</h3> 668 * <ul> 669 * <li>{@link #EXTRA_QUEUE_ID} <i>(required)</i>: specifies the media queue id of the 670 * queue to which the item in question belongs. 671 * <li>{@link #EXTRA_ITEM_ID} <i>(required)</i>: specifies the media item id of the 672 * media item in question. 673 * <li>{@link #EXTRA_ITEM_STATUS} <i>(required)</i>: specifies the status of the 674 * item as a bundle that can be decoded into a {@link MediaItemStatus} object. 675 * </ul> 676 * 677 * @see #ACTION_PLAY 678 */ 679 public static final String EXTRA_ITEM_STATUS_UPDATE_RECEIVER = 680 "android.media.intent.extra.ITEM_STATUS_UPDATE_RECEIVER"; 681 682 private MediaControlIntent() { 683 } 684} 685