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