1 /* 2 * Copyright (c) 2019 - 2021 Nordic Semiconductor ASA 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_MEDIA_PROXY_H_ 8 #define ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_MEDIA_PROXY_H_ 9 10 /** @brief Media proxy module 11 * 12 * @defgroup bt_media_proxy Media Proxy 13 * 14 * @ingroup bluetooth 15 * @{ 16 * 17 * The media proxy module is the connection point between media players 18 * and media controllers. 19 * 20 * A media player has (access to) media content and knows how to 21 * navigate and play this content. A media controller reads or gets 22 * information from a player and controls the player by setting player 23 * parameters and giving the player commands. 24 * 25 * The media proxy module allows media player implementations to make 26 * themselves available to media controllers. And it allows 27 * controllers to access, and get updates from, any player. 28 * 29 * The media proxy module allows both local and remote control of 30 * local player instances: A media controller may be a local 31 * application, or it may be a Media Control Service relaying requests 32 * from a remote Media Control Client. There may be either local or 33 * remote control, or both, or even multiple instances of each. 34 * 35 * [Experimental] Users should note that the APIs can change 36 * as a part of ongoing development. 37 */ 38 39 #include <stdint.h> 40 #include <stdbool.h> 41 42 #include <zephyr/bluetooth/bluetooth.h> 43 44 /* TODO: Remove dependency on mcs.h */ 45 #include "mcs.h" 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 51 52 /** 53 * @brief Media player command 54 */ 55 struct mpl_cmd { 56 uint8_t opcode; 57 bool use_param; 58 int32_t param; 59 }; 60 61 /** 62 * @brief Media command notification 63 */ 64 struct mpl_cmd_ntf { 65 uint8_t requested_opcode; 66 uint8_t result_code; 67 }; 68 69 /** 70 * @brief Search control item 71 */ 72 struct mpl_sci { 73 uint8_t len; /**< Length of type and parameter */ 74 uint8_t type; /**< MEDIA_PROXY_SEARCH_TYPE_<...> */ 75 char param[SEARCH_PARAM_MAX]; /**< Search parameter */ 76 }; 77 78 /** 79 * @brief Search 80 */ 81 struct mpl_search { 82 uint8_t len; 83 char search[SEARCH_LEN_MAX]; /* Concatenated search control items */ 84 }; /* - (type, length, param) */ 85 86 /** 87 * @brief Playback speed parameters 88 * 89 * All values from -128 to 127 allowed, only some defined 90 */ 91 #define MEDIA_PROXY_PLAYBACK_SPEED_MIN -128 92 #define MEDIA_PROXY_PLAYBACK_SPEED_QUARTER -128 93 #define MEDIA_PROXY_PLAYBACK_SPEED_HALF -64 94 #define MEDIA_PROXY_PLAYBACK_SPEED_UNITY 0 95 #define MEDIA_PROXY_PLAYBACK_SPEED_DOUBLE 64 96 #define MEDIA_PROXY_PLAYBACK_SPEED_MAX 127 97 98 /** 99 * @brief Seeking speed factors 100 * 101 * The allowed values for seeking speed are the range -64 to -4 102 * (endpoints included), the value 0, and the range 4 to 64 103 * (endpoints included). 104 */ 105 #define MEDIA_PROXY_SEEKING_SPEED_FACTOR_MAX 64 106 #define MEDIA_PROXY_SEEKING_SPEED_FACTOR_MIN 4 107 #define MEDIA_PROXY_SEEKING_SPEED_FACTOR_ZERO 0 108 109 /** 110 * @brief Playing orders 111 */ 112 #define MEDIA_PROXY_PLAYING_ORDER_SINGLE_ONCE 0x01 113 #define MEDIA_PROXY_PLAYING_ORDER_SINGLE_REPEAT 0x02 114 #define MEDIA_PROXY_PLAYING_ORDER_INORDER_ONCE 0x03 115 #define MEDIA_PROXY_PLAYING_ORDER_INORDER_REPEAT 0x04 116 #define MEDIA_PROXY_PLAYING_ORDER_OLDEST_ONCE 0x05 117 #define MEDIA_PROXY_PLAYING_ORDER_OLDEST_REPEAT 0x06 118 #define MEDIA_PROXY_PLAYING_ORDER_NEWEST_ONCE 0x07 119 #define MEDIA_PROXY_PLAYING_ORDER_NEWEST_REPEAT 0x08 120 #define MEDIA_PROXY_PLAYING_ORDER_SHUFFLE_ONCE 0x09 121 #define MEDIA_PROXY_PLAYING_ORDER_SHUFFLE_REPEAT 0x0a 122 123 /** 124 * @brief Playing orders supported 125 * 126 * A bitmap, in the same order as the playing orders above. 127 * Note that playing order 1 corresponds to bit 0, and so on. 128 */ 129 #define MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_SINGLE_ONCE BIT(0) 130 #define MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_SINGLE_REPEAT BIT(1) 131 #define MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_INORDER_ONCE BIT(2) 132 #define MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_INORDER_REPEAT BIT(3) 133 #define MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_OLDEST_ONCE BIT(4) 134 #define MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_OLDEST_REPEAT BIT(5) 135 #define MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_NEWEST_ONCE BIT(6) 136 #define MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_NEWEST_REPEAT BIT(7) 137 #define MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_SHUFFLE_ONCE BIT(8) 138 #define MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_SHUFFLE_REPEAT BIT(9) 139 140 /** 141 * @brief Media player states 142 */ 143 #define MEDIA_PROXY_STATE_INACTIVE 0x00 144 #define MEDIA_PROXY_STATE_PLAYING 0x01 145 #define MEDIA_PROXY_STATE_PAUSED 0x02 146 #define MEDIA_PROXY_STATE_SEEKING 0x03 147 #define MEDIA_PROXY_STATE_LAST 0x04 148 149 /** 150 * @brief Media player command opcodes 151 */ 152 #define MEDIA_PROXY_OP_PLAY 0x01 153 #define MEDIA_PROXY_OP_PAUSE 0x02 154 #define MEDIA_PROXY_OP_FAST_REWIND 0x03 155 #define MEDIA_PROXY_OP_FAST_FORWARD 0x04 156 #define MEDIA_PROXY_OP_STOP 0x05 157 158 #define MEDIA_PROXY_OP_MOVE_RELATIVE 0x10 159 160 #define MEDIA_PROXY_OP_PREV_SEGMENT 0x20 161 #define MEDIA_PROXY_OP_NEXT_SEGMENT 0x21 162 #define MEDIA_PROXY_OP_FIRST_SEGMENT 0x22 163 #define MEDIA_PROXY_OP_LAST_SEGMENT 0x23 164 #define MEDIA_PROXY_OP_GOTO_SEGMENT 0x24 165 166 #define MEDIA_PROXY_OP_PREV_TRACK 0x30 167 #define MEDIA_PROXY_OP_NEXT_TRACK 0x31 168 #define MEDIA_PROXY_OP_FIRST_TRACK 0x32 169 #define MEDIA_PROXY_OP_LAST_TRACK 0x33 170 #define MEDIA_PROXY_OP_GOTO_TRACK 0x34 171 172 #define MEDIA_PROXY_OP_PREV_GROUP 0x40 173 #define MEDIA_PROXY_OP_NEXT_GROUP 0x41 174 #define MEDIA_PROXY_OP_FIRST_GROUP 0x42 175 #define MEDIA_PROXY_OP_LAST_GROUP 0x43 176 #define MEDIA_PROXY_OP_GOTO_GROUP 0x44 177 178 /** 179 * @brief Media player supported opcodes length 180 */ 181 #define MEDIA_PROXY_OPCODES_SUPPORTED_LEN 4 182 183 /** 184 * @brief Media player supported command opcodes 185 */ 186 #define MEDIA_PROXY_OP_SUP_PLAY BIT(0) 187 #define MEDIA_PROXY_OP_SUP_PAUSE BIT(1) 188 #define MEDIA_PROXY_OP_SUP_FAST_REWIND BIT(2) 189 #define MEDIA_PROXY_OP_SUP_FAST_FORWARD BIT(3) 190 #define MEDIA_PROXY_OP_SUP_STOP BIT(4) 191 192 #define MEDIA_PROXY_OP_SUP_MOVE_RELATIVE BIT(5) 193 194 #define MEDIA_PROXY_OP_SUP_PREV_SEGMENT BIT(6) 195 #define MEDIA_PROXY_OP_SUP_NEXT_SEGMENT BIT(7) 196 #define MEDIA_PROXY_OP_SUP_FIRST_SEGMENT BIT(8) 197 #define MEDIA_PROXY_OP_SUP_LAST_SEGMENT BIT(9) 198 #define MEDIA_PROXY_OP_SUP_GOTO_SEGMENT BIT(10) 199 200 #define MEDIA_PROXY_OP_SUP_PREV_TRACK BIT(11) 201 #define MEDIA_PROXY_OP_SUP_NEXT_TRACK BIT(12) 202 #define MEDIA_PROXY_OP_SUP_FIRST_TRACK BIT(13) 203 #define MEDIA_PROXY_OP_SUP_LAST_TRACK BIT(14) 204 #define MEDIA_PROXY_OP_SUP_GOTO_TRACK BIT(15) 205 206 #define MEDIA_PROXY_OP_SUP_PREV_GROUP BIT(16) 207 #define MEDIA_PROXY_OP_SUP_NEXT_GROUP BIT(17) 208 #define MEDIA_PROXY_OP_SUP_FIRST_GROUP BIT(18) 209 #define MEDIA_PROXY_OP_SUP_LAST_GROUP BIT(19) 210 #define MEDIA_PROXY_OP_SUP_GOTO_GROUP BIT(20) 211 212 /** 213 * @brief Media player command result codes 214 */ 215 #define MEDIA_PROXY_CMD_SUCCESS 0x01 216 #define MEDIA_PROXY_CMD_NOT_SUPPORTED 0x02 217 #define MEDIA_PROXY_CMD_PLAYER_INACTIVE 0x03 218 #define MEDIA_PROXY_CMD_CANNOT_BE_COMPLETED 0x04 219 220 /** 221 * @brief Search operation type values 222 */ 223 #define MEDIA_PROXY_SEARCH_TYPE_TRACK_NAME 0x01 224 #define MEDIA_PROXY_SEARCH_TYPE_ARTIST_NAME 0x02 225 #define MEDIA_PROXY_SEARCH_TYPE_ALBUM_NAME 0x03 226 #define MEDIA_PROXY_SEARCH_TYPE_GROUP_NAME 0x04 227 #define MEDIA_PROXY_SEARCH_TYPE_EARLIEST_YEAR 0x05 228 #define MEDIA_PROXY_SEARCH_TYPE_LATEST_YEAR 0x06 229 #define MEDIA_PROXY_SEARCH_TYPE_GENRE 0x07 230 #define MEDIA_PROXY_SEARCH_TYPE_ONLY_TRACKS 0x08 231 #define MEDIA_PROXY_SEARCH_TYPE_ONLY_GROUPS 0x09 232 233 /** 234 * @brief Search operation result codes 235 */ 236 #define MEDIA_PROXY_SEARCH_SUCCESS 0x01 237 #define MEDIA_PROXY_SEARCH_FAILURE 0x02 238 239 /* Group object object types */ 240 #define MEDIA_PROXY_GROUP_OBJECT_TRACK_TYPE 0x00 241 #define MEDIA_PROXY_GROUP_OBJECT_GROUP_TYPE 0x01 242 243 244 /** 245 * @brief Opaque media player instance 246 */ 247 struct media_player; 248 249 /* PUBLIC API FOR CONTROLLERS */ 250 251 /** @brief Callbacks to a controller, from the media proxy 252 * 253 * Given by a controller when registering 254 */ 255 struct media_proxy_ctrl_cbs { 256 257 /** 258 * @brief Media Player Instance callback 259 * 260 * Called when the local Media Player instance is registered or read (TODO). 261 * Also called if the local player instance is already registered when 262 * the controller is registered. 263 * Provides the controller with the pointer to the local player instance. 264 * 265 * @param player Media player instance pointer 266 * @param err Error value. 0 on success, or errno on negative value. 267 */ 268 void (*local_player_instance)(struct media_player *player, int err); 269 270 #ifdef CONFIG_MCTL_REMOTE_PLAYER_CONTROL 271 /** 272 * @brief Discover Player Instance callback 273 * 274 * Called when a remote player instance has been discovered. 275 * The instance has been discovered, and will be accessed, using Bluetooth, 276 * via media control client and a remote media control service. 277 * 278 * @param player Instance pointer to the remote player 279 * @param err Error value. 0 on success, GATT error on positive value 280 * or errno on negative value. 281 */ 282 void (*discover_player)(struct media_player *player, int err); 283 #endif /* CONFIG_MCTL_REMOTE_PLAYER_CONTROL */ 284 285 /** 286 * @brief Media Player Name receive callback 287 * 288 * Called when the Media Player Name is read or changed 289 * See also media_proxy_ctrl_name_get() 290 * 291 * @param player Media player instance pointer 292 * @param err Error value. 0 on success, GATT error on positive value 293 * or errno on negative value. 294 * @param name The name of the media player 295 */ 296 void (*player_name_recv)(struct media_player *player, int err, const char *name); 297 298 /** 299 * @brief Media Player Icon Object ID receive callback 300 * 301 * Called when the Media Player Icon Object ID is read 302 * See also media_proxy_ctrl_get_icon_id() 303 * 304 * @param player Media player instance pointer 305 * @param err Error value. 0 on success, GATT error on positive value 306 * or errno on negative value. 307 * @param id The ID of the Icon object in the Object Transfer Service (48 bits) 308 */ 309 void (*icon_id_recv)(struct media_player *player, int err, uint64_t id); 310 311 /** 312 * @brief Media Player Icon URL receive callback 313 * 314 * Called when the Media Player Icon URL is read 315 * See also media_proxy_ctrl_get_icon_url() 316 * 317 * @param player Media player instance pointer 318 * @param err Error value. 0 on success, GATT error on positive value 319 * or errno on negative value. 320 * @param url The URL of the icon 321 */ 322 void (*icon_url_recv)(struct media_player *player, int err, const char *url); 323 324 /** 325 * @brief Track changed receive callback 326 * 327 * Called when the Current Track is changed 328 * 329 * @param player Media player instance pointer 330 * @param err Error value. 0 on success, GATT error on positive value 331 * or errno on negative value. 332 */ 333 void (*track_changed_recv)(struct media_player *player, int err); 334 335 /** 336 * @brief Track Title receive callback 337 * 338 * Called when the Track Title is read or changed 339 * See also media_proxy_ctrl_get_track_title() 340 * 341 * @param player Media player instance pointer 342 * @param err Error value. 0 on success, GATT error on positive value 343 * or errno on negative value. 344 * @param title The title of the current track 345 */ 346 void (*track_title_recv)(struct media_player *player, int err, const char *title); 347 348 /** 349 * @brief Track Duration receive callback 350 * 351 * Called when the Track Duration is read or changed 352 * See also media_proxy_ctrl_get_track_duration() 353 * 354 * @param player Media player instance pointer 355 * @param err Error value. 0 on success, GATT error on positive value 356 * or errno on negative value. 357 * @param duration The duration of the current track 358 */ 359 void (*track_duration_recv)(struct media_player *player, int err, int32_t duration); 360 361 /** 362 * @brief Track Position receive callback 363 * 364 * Called when the Track Position is read or changed 365 * See also media_proxy_ctrl_get_track_position() and 366 * media_proxy_ctrl_set_track_position() 367 * 368 * @param player Media player instance pointer 369 * @param err Error value. 0 on success, GATT error on positive value 370 * or errno on negative value. 371 * @param position The player's position in the track 372 */ 373 void (*track_position_recv)(struct media_player *player, int err, int32_t position); 374 375 /** 376 * @brief Track Position write callback 377 * 378 * Called when the Track Position is written 379 * See also media_proxy_ctrl_set_track_position(). 380 * 381 * @param player Media player instance pointer 382 * @param err Error value. 0 on success, GATT error on positive value 383 * or errno on negative value. 384 * @param position The position given attempted to write 385 */ 386 void (*track_position_write)(struct media_player *player, int err, int32_t position); 387 388 /** 389 * @brief Playback Speed receive callback 390 * 391 * Called when the Playback Speed is read or changed 392 * See also media_proxy_ctrl_get_playback_speed() and 393 * media_proxy_ctrl_set_playback_speed() 394 * 395 * @param player Media player instance pointer 396 * @param err Error value. 0 on success, GATT error on positive value 397 * or errno on negative value. 398 * @param speed The playback speed parameter 399 */ 400 void (*playback_speed_recv)(struct media_player *player, int err, int8_t speed); 401 402 /** 403 * @brief Playback Speed write callback 404 * 405 * Called when the Playback Speed is written 406 * See also media_proxy_ctrl_set_playback_speed() 407 * 408 * @param player Media player instance pointer 409 * @param err Error value. 0 on success, GATT error on positive value 410 * or errno on negative value. 411 * @param speed The playback speed parameter attempted to write 412 */ 413 void (*playback_speed_write)(struct media_player *player, int err, int8_t speed); 414 415 /** 416 * @brief Seeking Speed receive callback 417 * 418 * Called when the Seeking Speed is read or changed 419 * See also media_proxy_ctrl_get_seeking_speed() 420 * 421 * @param player Media player instance pointer 422 * @param err Error value. 0 on success, GATT error on positive value 423 * or errno on negative value. 424 * @param speed The seeking speed factor 425 */ 426 void (*seeking_speed_recv)(struct media_player *player, int err, int8_t speed); 427 428 /** 429 * @brief Track Segments Object ID receive callback 430 * 431 * Called when the Track Segments Object ID is read 432 * See also media_proxy_ctrl_get_track_segments_id() 433 * 434 * @param player Media player instance pointer 435 * @param err Error value. 0 on success, GATT error on positive value 436 * or errno on negative value. 437 * @param id The ID of the track segments object in Object Transfer Service (48 bits) 438 */ 439 void (*track_segments_id_recv)(struct media_player *player, int err, uint64_t id); 440 441 /** 442 * @brief Current Track Object ID receive callback 443 * 444 * Called when the Current Track Object ID is read or changed 445 * See also media_proxy_ctrl_get_current_track_id() and 446 * media_proxy_ctrl_set_current_track_id() 447 * 448 * @param player Media player instance pointer 449 * @param err Error value. 0 on success, GATT error on positive value 450 * or errno on negative value. 451 * @param id The ID of the current track object in Object Transfer Service (48 bits) 452 */ 453 void (*current_track_id_recv)(struct media_player *player, int err, uint64_t id); 454 455 /** 456 * @brief Current Track Object ID write callback 457 * 458 * Called when the Current Track Object ID is written 459 * See also media_proxy_ctrl_set_current_track_id() 460 * 461 * @param player Media player instance pointer 462 * @param err Error value. 0 on success, GATT error on positive value 463 * or errno on negative value. 464 * @param id The ID (48 bits) attempted to write 465 */ 466 void (*current_track_id_write)(struct media_player *player, int err, uint64_t id); 467 468 /** 469 * @brief Next Track Object ID receive callback 470 * 471 * Called when the Next Track Object ID is read or changed 472 * See also media_proxy_ctrl_get_next_track_id() and 473 * media_proxy_ctrl_set_next_track_id() 474 * 475 * @param player Media player instance pointer 476 * @param err Error value. 0 on success, GATT error on positive value 477 * or errno on negative value. 478 * @param id The ID of the next track object in Object Transfer Service (48 bits) 479 */ 480 void (*next_track_id_recv)(struct media_player *player, int err, uint64_t id); 481 482 /** 483 * @brief Next Track Object ID write callback 484 * 485 * Called when the Next Track Object ID is written 486 * See also media_proxy_ctrl_set_next_track_id() 487 * 488 * @param player Media player instance pointer 489 * @param err Error value. 0 on success, GATT error on positive value 490 * or errno on negative value. 491 * @param id The ID (48 bits) attempted to write 492 */ 493 void (*next_track_id_write)(struct media_player *player, int err, uint64_t id); 494 495 /** 496 * @brief Parent Group Object ID receive callback 497 * 498 * Called when the Parent Group Object ID is read or changed 499 * See also media_proxy_ctrl_get_parent_group_id() 500 * 501 * @param player Media player instance pointer 502 * @param err Error value. 0 on success, GATT error on positive value 503 * or errno on negative value. 504 * @param id The ID of the parent group object in Object Transfer Service (48 bits) 505 */ 506 void (*parent_group_id_recv)(struct media_player *player, int err, uint64_t id); 507 508 /** 509 * @brief Current Group Object ID receive callback 510 * 511 * Called when the Current Group Object ID is read or changed 512 * See also media_proxy_ctrl_get_current_group_id() and 513 * media_proxy_ctrl_set_current_group_id() 514 * 515 * @param player Media player instance pointer 516 * @param err Error value. 0 on success, GATT error on positive value 517 * or errno on negative value. 518 * @param id The ID of the current group object in Object Transfer Service (48 bits) 519 */ 520 void (*current_group_id_recv)(struct media_player *player, int err, uint64_t id); 521 522 /** 523 * @brief Current Group Object ID write callback 524 * 525 * Called when the Current Group Object ID is written 526 * See also media_proxy_ctrl_set_current_group_id() 527 * 528 * @param player Media player instance pointer 529 * @param err Error value. 0 on success, GATT error on positive value 530 * or errno on negative value. 531 * @param id The ID (48 bits) attempted to write 532 */ 533 void (*current_group_id_write)(struct media_player *player, int err, uint64_t id); 534 535 /** 536 * @brief Playing Order receive callback 537 * 538 * Called when the Playing Order is read or changed 539 * See also media_proxy_ctrl_get_playing_order() and 540 * media_proxy_ctrl_set_playing_order() 541 * 542 * @param player Media player instance pointer 543 * @param err Error value. 0 on success, GATT error on positive value 544 * or errno on negative value. 545 * @param order The playing order 546 */ 547 void (*playing_order_recv)(struct media_player *player, int err, uint8_t order); 548 549 /** 550 * @brief Playing Order write callback 551 * 552 * Called when the Playing Order is written 553 * See also media_proxy_ctrl_set_playing_order() 554 * 555 * @param player Media player instance pointer 556 * @param err Error value. 0 on success, GATT error on positive value 557 * or errno on negative value. 558 * @param order The playing order attempted to write 559 */ 560 void (*playing_order_write)(struct media_player *player, int err, uint8_t order); 561 562 /** 563 * @brief Playing Orders Supported receive callback 564 * 565 * Called when the Playing Orders Supported is read 566 * See also media_proxy_ctrl_get_playing_orders_supported() 567 * 568 * @param player Media player instance pointer 569 * @param err Error value. 0 on success, GATT error on positive value 570 * or errno on negative value. 571 * @param orders The playing orders supported 572 */ 573 void (*playing_orders_supported_recv)(struct media_player *player, int err, 574 uint16_t orders); 575 576 /** 577 * @brief Media State receive callback 578 * 579 * Called when the Media State is read or changed 580 * See also media_proxy_ctrl_get_media_state() and 581 * media_proxy_ctrl_send_command() 582 * 583 * @param player Media player instance pointer 584 * @param err Error value. 0 on success, GATT error on positive value 585 * or errno on negative value. 586 * @param state The media player state 587 */ 588 void (*media_state_recv)(struct media_player *player, int err, uint8_t state); 589 590 /** 591 * @brief Command send callback 592 * 593 * Called when a command has been sent 594 * See also media_proxy_ctrl_send_command() 595 * 596 * @param player Media player instance pointer 597 * @param err Error value. 0 on success, GATT error on positive value 598 * or errno on negative value. 599 * @param cmd The command sent 600 */ 601 void (*command_send)(struct media_player *player, int err, const struct mpl_cmd *cmd); 602 603 /** 604 * @brief Command result receive callback 605 * 606 * Called when a command result has been received 607 * See also media_proxy_ctrl_send_command() 608 * 609 * @param player Media player instance pointer 610 * @param err Error value. 0 on success, GATT error on positive value 611 * or errno on negative value. 612 * @param result The result received 613 */ 614 void (*command_recv)(struct media_player *player, int err, 615 const struct mpl_cmd_ntf *result); 616 617 /** 618 * @brief Commands supported receive callback 619 * 620 * Called when the Commands Supported is read or changed 621 * See also media_proxy_ctrl_get_commands_supported() 622 * 623 * @param player Media player instance pointer 624 * @param err Error value. 0 on success, GATT error on positive value 625 * or errno on negative value. 626 * @param opcodes The supported command opcodes (bitmap) 627 */ 628 void (*commands_supported_recv)(struct media_player *player, int err, uint32_t opcodes); 629 630 /** 631 * @brief Search send callback 632 * 633 * Called when a search has been sent 634 * See also media_proxy_ctrl_send_search() 635 * 636 * @param player Media player instance pointer 637 * @param err Error value. 0 on success, GATT error on positive value 638 * or errno on negative value. 639 * @param search The search sent 640 */ 641 void (*search_send)(struct media_player *player, int err, const struct mpl_search *search); 642 643 /** 644 * @brief Search result code receive callback 645 * 646 * Called when a search result code has been received 647 * See also media_proxy_ctrl_send_search() 648 * 649 * The search result code tells whether the search was successful or not. 650 * For a successful search, the actual results of the search (i.e. what was found 651 * as a result of the search)can be accessed using the Search Results Object ID. 652 * The Search Results Object ID has a separate callback - search_results_id_recv(). 653 * 654 * @param player Media player instance pointer 655 * @param err Error value. 0 on success, GATT error on positive value 656 * or errno on negative value. 657 * @param result_code Search result code 658 */ 659 void (*search_recv)(struct media_player *player, int err, uint8_t result_code); 660 661 /** 662 * @brief Search Results Object ID receive callback 663 * See also media_proxy_ctrl_get_search_results_id() 664 * 665 * Called when the Search Results Object ID is read or changed 666 * 667 * @param player Media player instance pointer 668 * @param err Error value. 0 on success, GATT error on positive value 669 * or errno on negative value. 670 * @param id The ID of the search results object in Object Transfer Service (48 bits) 671 */ 672 void (*search_results_id_recv)(struct media_player *player, int err, uint64_t id); 673 674 /** 675 * @brief Content Control ID receive callback 676 * 677 * Called when the Content Control ID is read 678 * See also media_proxy_ctrl_get_content_ctrl_id() 679 * 680 * @param player Media player instance pointer 681 * @param err Error value. 0 on success, GATT error on positive value 682 * or errno on negative value. 683 * @param ccid The content control ID 684 */ 685 void (*content_ctrl_id_recv)(struct media_player *player, int err, uint8_t ccid); 686 }; 687 688 /** 689 * @brief Register a controller with the media_proxy 690 * 691 * @param ctrl_cbs Callbacks to the controller 692 * 693 * @return 0 if success, errno on failure 694 */ 695 int media_proxy_ctrl_register(struct media_proxy_ctrl_cbs *ctrl_cbs); 696 697 /** 698 * @brief Discover a remote media player 699 * 700 * Discover a remote media player instance. 701 * The remote player instance will be discovered, and accessed, using Bluetooth, 702 * via the media control client and a remote media control service. 703 * This call will start a GATT discovery of the Media Control Service on the peer, 704 * and setup handles and subscriptions. 705 * 706 * This shall be called once before any other actions can be executed for the 707 * remote player. The remote player instance will be returned in the 708 * discover_player() callback. 709 * 710 * @param conn The connection to do discovery for 711 * 712 * @return 0 if success, errno on failure 713 */ 714 int media_proxy_ctrl_discover_player(struct bt_conn *conn); 715 716 /** 717 * @brief Read Media Player Name 718 * 719 * @param player Media player instance pointer 720 * 721 * @return 0 if success, errno on failure. 722 */ 723 int media_proxy_ctrl_get_player_name(struct media_player *player); 724 725 /** 726 * @brief Read Icon Object ID 727 * 728 * Get an ID (48 bit) that can be used to retrieve the Icon 729 * Object from an Object Transfer Service 730 * 731 * See the Media Control Service spec v1.0 sections 3.2 and 732 * 4.1 for a description of the Icon Object. 733 * 734 * Requires Object Transfer Service 735 * 736 * @param player Media player instance pointer 737 * 738 * @return 0 if success, errno on failure. 739 */ 740 int media_proxy_ctrl_get_icon_id(struct media_player *player); 741 742 /** 743 * @brief Read Icon URL 744 * 745 * Get a URL to the media player's icon. 746 * 747 * @param player Media player instance pointer 748 */ 749 int media_proxy_ctrl_get_icon_url(struct media_player *player); 750 751 /** 752 * @brief Read Track Title 753 * 754 * @param player Media player instance pointer 755 * 756 * @return 0 if success, errno on failure. 757 */ 758 int media_proxy_ctrl_get_track_title(struct media_player *player); 759 760 /** 761 * @brief Read Track Duration 762 * 763 * The duration of a track is measured in hundredths of a 764 * second. 765 * 766 * @param player Media player instance pointer 767 * 768 * @return 0 if success, errno on failure. 769 */ 770 int media_proxy_ctrl_get_track_duration(struct media_player *player); 771 772 /** 773 * @brief Read Track Position 774 * 775 * The position of the player (the playing position) is 776 * measured in hundredths of a second from the beginning of 777 * the track 778 * 779 * @param player Media player instance pointer 780 * 781 * @return 0 if success, errno on failure. 782 */ 783 int media_proxy_ctrl_get_track_position(struct media_player *player); 784 785 /** 786 * @brief Set Track Position 787 * 788 * Set the playing position of the media player in the current 789 * track. The position is given in in hundredths of a second, 790 * from the beginning of the track of the track for positive 791 * values, and (backwards) from the end of the track for 792 * negative values. 793 * 794 * @param player Media player instance pointer 795 * @param position The track position to set 796 * 797 * @return 0 if success, errno on failure. 798 */ 799 int media_proxy_ctrl_set_track_position(struct media_player *player, int32_t position); 800 801 /** 802 * @brief Get Playback Speed 803 * 804 * The playback speed parameter is related to the actual 805 * playback speed as follows: 806 * actual playback speed = 2^(speed_parameter/64) 807 * 808 * A speed parameter of 0 corresponds to unity speed playback 809 * (i.e. playback at "normal" speed). A speed parameter of 810 * -128 corresponds to playback at one fourth of normal speed, 811 * 127 corresponds to playback at almost four times the normal 812 * speed. 813 * 814 * @param player Media player instance pointer 815 * 816 * @return 0 if success, errno on failure. 817 */ 818 int media_proxy_ctrl_get_playback_speed(struct media_player *player); 819 820 /** 821 * @brief Set Playback Speed 822 * 823 * See the get_playback_speed() function for an explanation of 824 * the playback speed parameter. 825 * 826 * Note that the media player may not support all possible 827 * values of the playback speed parameter. If the value given 828 * is not supported, and is higher than the current value, the 829 * player should set the playback speed to the next higher 830 * supported value. (And correspondingly to the next lower 831 * supported value for given values lower than the current 832 * value.) 833 * 834 * @param player Media player instance pointer 835 * @param speed The playback speed parameter to set 836 * 837 * @return 0 if success, errno on failure. 838 */ 839 int media_proxy_ctrl_set_playback_speed(struct media_player *player, int8_t speed); 840 841 /** 842 * @brief Get Seeking Speed 843 * 844 * The seeking speed gives the speed with which the player is 845 * seeking. It is a factor, relative to real-time playback 846 * speed - a factor four means seeking happens at four times 847 * the real-time playback speed. Positive values are for 848 * forward seeking, negative values for backwards seeking. 849 * 850 * The seeking speed is not settable - a non-zero seeking speed 851 * is the result of "fast rewind" of "fast forward" commands. 852 * 853 * @param player Media player instance pointer 854 * 855 * @return 0 if success, errno on failure. 856 */ 857 int media_proxy_ctrl_get_seeking_speed(struct media_player *player); 858 859 /** 860 * @brief Read Current Track Segments Object ID 861 * 862 * Get an ID (48 bit) that can be used to retrieve the Current 863 * Track Segments Object from an Object Transfer Service 864 * 865 * See the Media Control Service spec v1.0 sections 3.10 and 866 * 4.2 for a description of the Track Segments Object. 867 * 868 * Requires Object Transfer Service 869 * 870 * @param player Media player instance pointer 871 * 872 * @return 0 if success, errno on failure. 873 */ 874 int media_proxy_ctrl_get_track_segments_id(struct media_player *player); 875 876 /** 877 * @brief Read Current Track Object ID 878 * 879 * Get an ID (48 bit) that can be used to retrieve the Current 880 * Track Object from an Object Transfer Service 881 * 882 * See the Media Control Service spec v1.0 sections 3.11 and 883 * 4.3 for a description of the Current Track Object. 884 * 885 * Requires Object Transfer Service 886 * 887 * @param player Media player instance pointer 888 * 889 * @return 0 if success, errno on failure. 890 */ 891 int media_proxy_ctrl_get_current_track_id(struct media_player *player); 892 893 /** 894 * @brief Set Current Track Object ID 895 * 896 * Change the player's current track to the track given by the ID. 897 * (Behaves similarly to the goto track command.) 898 * 899 * Requires Object Transfer Service 900 * 901 * @param player Media player instance pointer 902 * @param id The ID of a track object 903 * 904 * @return 0 if success, errno on failure. 905 */ 906 int media_proxy_ctrl_set_current_track_id(struct media_player *player, uint64_t id); 907 908 /** 909 * @brief Read Next Track Object ID 910 * 911 * Get an ID (48 bit) that can be used to retrieve the Next 912 * Track Object from an Object Transfer Service 913 * 914 * Requires Object Transfer Service 915 * 916 * @param player Media player instance pointer 917 * 918 * @return 0 if success, errno on failure. 919 */ 920 int media_proxy_ctrl_get_next_track_id(struct media_player *player); 921 922 /** 923 * @brief Set Next Track Object ID 924 * 925 * Change the player's next track to the track given by the ID. 926 * 927 * Requires Object Transfer Service 928 * 929 * @param player Media player instance pointer 930 * @param id The ID of a track object 931 * 932 * @return 0 if success, errno on failure. 933 */ 934 int media_proxy_ctrl_set_next_track_id(struct media_player *player, uint64_t id); 935 936 /** 937 * @brief Read Parent Group Object ID 938 * 939 * Get an ID (48 bit) that can be used to retrieve the Parent 940 * Track Object from an Object Transfer Service 941 * 942 * The parent group is the parent of the current group. 943 * 944 * See the Media Control Service spec v1.0 sections 3.14 and 945 * 4.4 for a description of the Current Track Object. 946 * 947 * Requires Object Transfer Service 948 * 949 * @param player Media player instance pointer 950 * 951 * @return 0 if success, errno on failure. 952 */ 953 int media_proxy_ctrl_get_parent_group_id(struct media_player *player); 954 955 /** 956 * @brief Read Current Group Object ID 957 * 958 * Get an ID (48 bit) that can be used to retrieve the Current 959 * Track Object from an Object Transfer Service 960 * 961 * See the Media Control Service spec v1.0 sections 3.14 and 962 * 4.4 for a description of the Current Group Object. 963 * 964 * Requires Object Transfer Service 965 * 966 * @param player Media player instance pointer 967 * 968 * @return 0 if success, errno on failure. 969 */ 970 int media_proxy_ctrl_get_current_group_id(struct media_player *player); 971 972 /** 973 * @brief Set Current Group Object ID 974 * 975 * Change the player's current group to the group given by the 976 * ID, and the current track to the first track in that group. 977 * 978 * Requires Object Transfer Service 979 * 980 * @param player Media player instance pointer 981 * @param id The ID of a group object 982 * 983 * @return 0 if success, errno on failure. 984 */ 985 int media_proxy_ctrl_set_current_group_id(struct media_player *player, uint64_t id); 986 987 /** 988 * @brief Read Playing Order 989 * 990 * @param player Media player instance pointer 991 * 992 * @return 0 if success, errno on failure. 993 */ 994 int media_proxy_ctrl_get_playing_order(struct media_player *player); 995 996 /** 997 * @brief Set Playing Order 998 * 999 * Set the media player's playing order 1000 * 1001 * @param player Media player instance pointer 1002 * @param order The playing order to set 1003 * 1004 * @return 0 if success, errno on failure. 1005 */ 1006 int media_proxy_ctrl_set_playing_order(struct media_player *player, uint8_t order); 1007 1008 /** 1009 * @brief Read Playing Orders Supported 1010 * 1011 * Read a bitmap containing the media player's supported 1012 * playing orders. 1013 * 1014 * @param player Media player instance pointer 1015 * 1016 * @return 0 if success, errno on failure. 1017 */ 1018 int media_proxy_ctrl_get_playing_orders_supported(struct media_player *player); 1019 1020 /** 1021 * @brief Read Media State 1022 * 1023 * Read the media player's state 1024 * 1025 * @param player Media player instance pointer 1026 * 1027 * @return 0 if success, errno on failure. 1028 */ 1029 int media_proxy_ctrl_get_media_state(struct media_player *player); 1030 1031 /** 1032 * @brief Send Command 1033 * 1034 * Send a command to the media player. 1035 * Commands may cause the media player to change its state 1036 * May result in two callbacks - one for the actual sending of the command to the 1037 * player, one for the result of the command from the player. 1038 * 1039 * @param player Media player instance pointer 1040 * @param command The command to send 1041 * 1042 * @return 0 if success, errno on failure. 1043 */ 1044 int media_proxy_ctrl_send_command(struct media_player *player, const struct mpl_cmd *command); 1045 1046 /** 1047 * @brief Read Commands Supported 1048 * 1049 * Read a bitmap containing the media player's supported 1050 * command opcodes. 1051 * 1052 * @param player Media player instance pointer 1053 * 1054 * @return 0 if success, errno on failure. 1055 */ 1056 int media_proxy_ctrl_get_commands_supported(struct media_player *player); 1057 1058 /** 1059 * @brief Set Search 1060 * 1061 * Write a search to the media player. 1062 * If the search is successful, the search results will be available as a group object 1063 * in the Object Transfer Service (OTS). 1064 * 1065 * May result in up to three callbacks 1066 * - one for the actual sending of the search to the player 1067 * - one for the result code for the search from the player 1068 * - if the search is successful, one for the the search results object ID in the OTs 1069 * 1070 * Requires Object Transfer Service 1071 * 1072 * @param player Media player instance pointer 1073 * @param search The search to write 1074 * 1075 * @return 0 if success, errno on failure. 1076 */ 1077 int media_proxy_ctrl_send_search(struct media_player *player, const struct mpl_search *search); 1078 1079 /** 1080 * @brief Read Search Results Object ID 1081 * 1082 * Get an ID (48 bit) that can be used to retrieve the Search 1083 * Results Object from an Object Transfer Service 1084 * 1085 * The search results object is a group object. 1086 * The search results object only exists if a successful 1087 * search operation has been done. 1088 * 1089 * Requires Object Transfer Service 1090 * 1091 * @param player Media player instance pointer 1092 * 1093 * @return 0 if success, errno on failure. 1094 */ 1095 int media_proxy_ctrl_get_search_results_id(struct media_player *player); 1096 1097 /** 1098 * @brief Read Content Control ID 1099 * 1100 * The content control ID identifies a content control service 1101 * on a device, and links it to the corresponding audio 1102 * stream. 1103 * 1104 * @param player Media player instance pointer 1105 * 1106 * @return 0 if success, errno on failure. 1107 */ 1108 uint8_t media_proxy_ctrl_get_content_ctrl_id(struct media_player *player); 1109 1110 1111 /* PUBLIC API FOR PLAYERS */ 1112 1113 /** @brief Available calls in a player, that the media proxy can call 1114 * 1115 * Given by a player when registering. 1116 */ 1117 struct media_proxy_pl_calls { 1118 1119 /** 1120 * @brief Read Media Player Name 1121 * 1122 * @return The name of the media player 1123 */ 1124 const char *(*get_player_name)(void); 1125 1126 /** 1127 * @brief Read Icon Object ID 1128 * 1129 * Get an ID (48 bit) that can be used to retrieve the Icon 1130 * Object from an Object Transfer Service 1131 * 1132 * See the Media Control Service spec v1.0 sections 3.2 and 1133 * 4.1 for a description of the Icon Object. 1134 * 1135 * @return The Icon Object ID 1136 */ 1137 uint64_t (*get_icon_id)(void); 1138 1139 /** 1140 * @brief Read Icon URL 1141 * 1142 * Get a URL to the media player's icon. 1143 * 1144 * @return The URL of the Icon 1145 */ 1146 const char *(*get_icon_url)(void); 1147 1148 /** 1149 * @brief Read Track Title 1150 * 1151 * @return The title of the current track 1152 */ 1153 const char *(*get_track_title)(void); 1154 1155 /** 1156 * @brief Read Track Duration 1157 * 1158 * The duration of a track is measured in hundredths of a 1159 * second. 1160 * 1161 * @return The duration of the current track 1162 */ 1163 int32_t (*get_track_duration)(void); 1164 1165 /** 1166 * @brief Read Track Position 1167 * 1168 * The position of the player (the playing position) is 1169 * measured in hundredths of a second from the beginning of 1170 * the track 1171 * 1172 * @return The position of the player in the current track 1173 */ 1174 int32_t (*get_track_position)(void); 1175 1176 /** 1177 * @brief Set Track Position 1178 * 1179 * Set the playing position of the media player in the current 1180 * track. The position is given in in hundredths of a second, 1181 * from the beginning of the track of the track for positive 1182 * values, and (backwards) from the end of the track for 1183 * negative values. 1184 * 1185 * @param position The player position to set 1186 */ 1187 void (*set_track_position)(int32_t position); 1188 1189 /** 1190 * @brief Get Playback Speed 1191 * 1192 * The playback speed parameter is related to the actual 1193 * playback speed as follows: 1194 * actual playback speed = 2^(speed_parameter/64) 1195 * 1196 * A speed parameter of 0 corresponds to unity speed playback 1197 * (i.e. playback at "normal" speed). A speed parameter of 1198 * -128 corresponds to playback at one fourth of normal speed, 1199 * 127 corresponds to playback at almost four times the normal 1200 * speed. 1201 * 1202 * @return The playback speed parameter 1203 */ 1204 int8_t (*get_playback_speed)(void); 1205 1206 /** 1207 * @brief Set Playback Speed 1208 * 1209 * See the get_playback_speed() function for an explanation of 1210 * the playback speed parameter. 1211 * 1212 * Note that the media player may not support all possible 1213 * values of the playback speed parameter. If the value given 1214 * is not supported, and is higher than the current value, the 1215 * player should set the playback speed to the next higher 1216 * supported value. (And correspondingly to the next lower 1217 * supported value for given values lower than the current 1218 * value.) 1219 * 1220 * @param speed The playback speed parameter to set 1221 */ 1222 void (*set_playback_speed)(int8_t speed); 1223 1224 /** 1225 * @brief Get Seeking Speed 1226 * 1227 * The seeking speed gives the speed with which the player is 1228 * seeking. It is a factor, relative to real-time playback 1229 * speed - a factor four means seeking happens at four times 1230 * the real-time playback speed. Positive values are for 1231 * forward seeking, negative values for backwards seeking. 1232 * 1233 * The seeking speed is not settable - a non-zero seeking speed 1234 * is the result of "fast rewind" of "fast forward" commands. 1235 * 1236 * @return The seeking speed factor 1237 */ 1238 int8_t (*get_seeking_speed)(void); 1239 1240 /** 1241 * @brief Read Current Track Segments Object ID 1242 * 1243 * Get an ID (48 bit) that can be used to retrieve the Current 1244 * Track Segments Object from an Object Transfer Service 1245 * 1246 * See the Media Control Service spec v1.0 sections 3.10 and 1247 * 4.2 for a description of the Track Segments Object. 1248 * 1249 * @return Current The Track Segments Object ID 1250 */ 1251 uint64_t (*get_track_segments_id)(void); 1252 1253 /** 1254 * @brief Read Current Track Object ID 1255 * 1256 * Get an ID (48 bit) that can be used to retrieve the Current 1257 * Track Object from an Object Transfer Service 1258 * 1259 * See the Media Control Service spec v1.0 sections 3.11 and 1260 * 4.3 for a description of the Current Track Object. 1261 * 1262 * @return The Current Track Object ID 1263 */ 1264 uint64_t (*get_current_track_id)(void); 1265 1266 /** 1267 * @brief Set Current Track Object ID 1268 * 1269 * Change the player's current track to the track given by the ID. 1270 * (Behaves similarly to the goto track command.) 1271 * 1272 * @param id The ID of a track object 1273 */ 1274 void (*set_current_track_id)(uint64_t id); 1275 1276 /** 1277 * @brief Read Next Track Object ID 1278 * 1279 * Get an ID (48 bit) that can be used to retrieve the Next 1280 * Track Object from an Object Transfer Service 1281 * 1282 * @return The Next Track Object ID 1283 */ 1284 uint64_t (*get_next_track_id)(void); 1285 1286 /** 1287 * @brief Set Next Track Object ID 1288 * 1289 * Change the player's next track to the track given by the ID. 1290 * 1291 * @param id The ID of a track object 1292 */ 1293 void (*set_next_track_id)(uint64_t id); 1294 1295 /** 1296 * @brief Read Parent Group Object ID 1297 * 1298 * Get an ID (48 bit) that can be used to retrieve the Parent 1299 * Track Object from an Object Transfer Service 1300 * 1301 * The parent group is the parent of the current group. 1302 * 1303 * See the Media Control Service spec v1.0 sections 3.14 and 1304 * 4.4 for a description of the Current Track Object. 1305 * 1306 * @return The Current Group Object ID 1307 */ 1308 uint64_t (*get_parent_group_id)(void); 1309 1310 /** 1311 * @brief Read Current Group Object ID 1312 * 1313 * Get an ID (48 bit) that can be used to retrieve the Current 1314 * Track Object from an Object Transfer Service 1315 * 1316 * See the Media Control Service spec v1.0 sections 3.14 and 1317 * 4.4 for a description of the Current Group Object. 1318 * 1319 * @return The Current Group Object ID 1320 */ 1321 uint64_t (*get_current_group_id)(void); 1322 1323 /** 1324 * @brief Set Current Group Object ID 1325 * 1326 * Change the player's current group to the group given by the 1327 * ID, and the current track to the first track in that group. 1328 * 1329 * @param id The ID of a group object 1330 */ 1331 void (*set_current_group_id)(uint64_t id); 1332 1333 /** 1334 * @brief Read Playing Order 1335 * 1336 * return The media player's current playing order 1337 */ 1338 uint8_t (*get_playing_order)(void); 1339 1340 /** 1341 * @brief Set Playing Order 1342 * 1343 * Set the media player's playing order. 1344 * See the MEDIA_PROXY_PLAYING_ORDER_* defines. 1345 * 1346 * @param order The playing order to set 1347 */ 1348 void (*set_playing_order)(uint8_t order); 1349 1350 /** 1351 * @brief Read Playing Orders Supported 1352 * 1353 * Read a bitmap containing the media player's supported 1354 * playing orders. 1355 * See the MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_* defines. 1356 * 1357 * @return The media player's supported playing orders 1358 */ 1359 uint16_t (*get_playing_orders_supported)(void); 1360 1361 /** 1362 * @brief Read Media State 1363 * 1364 * Read the media player's state 1365 * See the MEDIA_PROXY_MEDIA_STATE_* defines. 1366 * 1367 * @return The media player's state 1368 */ 1369 uint8_t (*get_media_state)(void); 1370 1371 /** 1372 * @brief Send Command 1373 * 1374 * Send a command to the media player. 1375 * For command opcodes (play, pause, ...) - see the MEDIA_PROXY_OP_* 1376 * defines. 1377 * 1378 * @param command The command to send 1379 */ 1380 void (*send_command)(const struct mpl_cmd *command); 1381 1382 /** 1383 * @brief Read Commands Supported 1384 * 1385 * Read a bitmap containing the media player's supported 1386 * command opcodes. 1387 * See the MEDIA_PROXY_OP_SUP_* defines. 1388 * 1389 * @return The media player's supported command opcodes 1390 */ 1391 uint32_t (*get_commands_supported)(void); 1392 1393 /** 1394 * @brief Set Search 1395 * 1396 * Write a search to the media player. 1397 * (For the formatting of a search, see the Media Control 1398 * Service spec and the mcs.h file.) 1399 * 1400 * @param search The search to write 1401 */ 1402 void (*send_search)(const struct mpl_search *search); 1403 1404 /** 1405 * @brief Read Search Results Object ID 1406 * 1407 * Get an ID (48 bit) that can be used to retrieve the Search 1408 * Results Object from an Object Transfer Service 1409 * 1410 * The search results object is a group object. 1411 * The search results object only exists if a successful 1412 * search operation has been done. 1413 * 1414 * @return The Search Results Object ID 1415 */ 1416 uint64_t (*get_search_results_id)(void); 1417 1418 /** 1419 * @brief Read Content Control ID 1420 * 1421 * The content control ID identifies a content control service 1422 * on a device, and links it to the corresponding audio 1423 * stream. 1424 * 1425 * @return The content control ID for the media player 1426 */ 1427 uint8_t (*get_content_ctrl_id)(void); 1428 }; 1429 1430 /** 1431 * @brief Register a player with the media proxy 1432 * 1433 * Register a player with the media proxy module, for use by media 1434 * controllers. 1435 * 1436 * The media proxy may call any non-NULL function pointers in the 1437 * supplied media_proxy_pl_calls structure. 1438 * 1439 * @param pl_calls Function pointers to the media player's calls 1440 * 1441 * @return 0 if success, errno on failure 1442 */ 1443 int media_proxy_pl_register(struct media_proxy_pl_calls *pl_calls); 1444 1445 /* Initialize player - TODO: Move to player header file */ 1446 int media_proxy_pl_init(void); 1447 1448 /* TODO: Find best location for this call, and move this one also */ 1449 struct bt_ots *bt_mcs_get_ots(void); 1450 1451 /* Callbacks from the player to the media proxy */ 1452 /** 1453 * @brief Player name changed callback 1454 * 1455 * To be called when the player's name is changed. 1456 * 1457 * @param name The name of the player 1458 */ 1459 void media_proxy_pl_name_cb(const char *name); 1460 1461 /** 1462 * @brief Player icon URL changed callback 1463 * 1464 * To be called when the player's icon URL is changed. 1465 * 1466 * @param url The URL of the player's icon 1467 */ 1468 void media_proxy_pl_icon_url_cb(const char *url); 1469 1470 /** 1471 * @brief Track changed callback 1472 * 1473 * To be called when the player's current track is changed 1474 */ 1475 void media_proxy_pl_track_changed_cb(void); 1476 1477 /** 1478 * @brief Track title callback 1479 * 1480 * To be called when the player's current track is changed 1481 * 1482 * @param title The title of the track 1483 */ 1484 void media_proxy_pl_track_title_cb(char *title); 1485 1486 /** 1487 * @brief Track duration callback 1488 * 1489 * To be called when the current track's duration is changed (e.g. due 1490 * to a track change) 1491 * 1492 * The track duration is given in hundredths of a second. 1493 * 1494 * @param duration The track duration 1495 */ 1496 void media_proxy_pl_track_duration_cb(int32_t duration); 1497 1498 /** 1499 * @brief Track position callback 1500 * 1501 * To be called when the media player's position in the track is 1502 * changed, or when the player is paused or similar. 1503 * 1504 * Exception: This callback should not be called when the position 1505 * changes during regular playback, i.e. while the player is playing 1506 * and playback happens at a constant speed. 1507 * 1508 * The track position is given in hundredths of a second from the 1509 * start of the track. 1510 * 1511 * @param position The media player's position in the track 1512 */ 1513 void media_proxy_pl_track_position_cb(int32_t position); 1514 1515 /** 1516 * @brief Playback speed callback 1517 * 1518 * To be called when the playback speed is changed. 1519 * 1520 * @param speed The playback speed parameter 1521 */ 1522 void media_proxy_pl_playback_speed_cb(int8_t speed); 1523 1524 /** 1525 * @brief Seeking speed callback 1526 * 1527 * To be called when the seeking speed is changed. 1528 * 1529 * @param speed The seeking speed factor 1530 */ 1531 void media_proxy_pl_seeking_speed_cb(int8_t speed); 1532 1533 /** 1534 * @brief Current track object ID callback 1535 * 1536 * To be called when the ID of the current track is changed (e.g. due 1537 * to a track change). 1538 * 1539 * @param id The ID of the current track object in the OTS 1540 */ 1541 void media_proxy_pl_current_track_id_cb(uint64_t id); 1542 1543 /** 1544 * @brief Next track object ID callback 1545 * 1546 * To be called when the ID of the current track is changes 1547 * 1548 * @param id The ID of the next track object in the OTS 1549 */ 1550 void media_proxy_pl_next_track_id_cb(uint64_t id); 1551 1552 /** 1553 * @brief Parent group object ID callback 1554 * 1555 * To be called when the ID of the parent group is changed 1556 * 1557 * @param id The ID of the parent group object in the OTS 1558 */ 1559 void media_proxy_pl_parent_group_id_cb(uint64_t id); 1560 1561 /** 1562 * @brief Current group object ID callback 1563 * 1564 * To be called when the ID of the current group is changed 1565 * 1566 * @param id The ID of the current group object in the OTS 1567 */ 1568 void media_proxy_pl_current_group_id_cb(uint64_t id); 1569 1570 /** 1571 * @brief Playing order callback 1572 * 1573 * To be called when the playing order is changed 1574 * 1575 * @param order The playing order 1576 */ 1577 void media_proxy_pl_playing_order_cb(uint8_t order); 1578 1579 /** 1580 * @brief Media state callback 1581 * 1582 * To be called when the media state is changed 1583 * 1584 * @param state The media player's state 1585 */ 1586 void media_proxy_pl_media_state_cb(uint8_t state); 1587 1588 /** 1589 * @brief Command callback 1590 * 1591 * To be called when a command has been sent, to notify whether the 1592 * command was successfully performed or not. 1593 * See the MEDIA_PROXY_CMD_* result code defines. 1594 * 1595 * @param cmd_ntf The result of the command 1596 */ 1597 void media_proxy_pl_command_cb(const struct mpl_cmd_ntf *cmd_ntf); 1598 1599 /** 1600 * @brief Commands supported callback 1601 * 1602 * To be called when the set of commands supported is changed 1603 * 1604 * @param opcodes The supported commands opcodes 1605 */ 1606 void media_proxy_pl_commands_supported_cb(uint32_t opcodes); 1607 1608 /** 1609 * @brief Search callback 1610 * 1611 * To be called when a search has been set to notify whether the 1612 * search was successfully performed or not. 1613 * See the MEDIA_PROXY_SEARCH_* result code defines. 1614 * 1615 * The actual results of the search, if successful, can be found in 1616 * the search results object. 1617 * 1618 * @param result_code The result (success or failure) of the search 1619 */ 1620 void media_proxy_pl_search_cb(uint8_t result_code); 1621 1622 /** 1623 * @brief Search Results object ID callback 1624 * 1625 * To be called when the ID of the search results is changed 1626 * (typically as the result of a new successful search). 1627 * 1628 * @param id The ID of the search results object in the OTS 1629 */ 1630 void media_proxy_pl_search_results_id_cb(uint64_t id); 1631 1632 #ifdef __cplusplus 1633 } 1634 #endif 1635 1636 /** @} */ /* End of group bt_media_proxy */ 1637 1638 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_MEDIA_PROXY_H_ */ 1639
