Line data Source code
1 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 1 : struct mpl_cmd {
62 : /** The opcode. See the MEDIA_PROXY_OP_* values */
63 1 : uint8_t opcode;
64 : /** Whether or not the @ref mpl_cmd.param is used */
65 1 : bool use_param;
66 : /** A 32-bit signed parameter. The parameter value depends on the @ref mpl_cmd.opcode */
67 1 : int32_t param;
68 : };
69 :
70 : /**
71 : * @brief Media command notification
72 : */
73 1 : struct mpl_cmd_ntf {
74 : /** The opcode that was sent */
75 1 : uint8_t requested_opcode;
76 : /** The result of the operation */
77 1 : uint8_t result_code;
78 : };
79 :
80 : /**
81 : * @brief Search control item
82 : */
83 1 : struct mpl_sci {
84 1 : uint8_t len; /**< Length of type and parameter */
85 1 : uint8_t type; /**< MEDIA_PROXY_SEARCH_TYPE_<...> */
86 1 : char param[SEARCH_PARAM_MAX]; /**< Search parameter */
87 : };
88 :
89 : /**
90 : * @brief Search
91 : */
92 1 : struct mpl_search {
93 : /** The length of the @ref mpl_search.search value */
94 1 : uint8_t len;
95 : /** Concatenated search control items - (type, length, param) */
96 1 : 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 1 : #define MEDIA_PROXY_PLAYBACK_SPEED_MIN -128
107 : /** Quarter playback speed, resulting in 25 % speed */
108 1 : #define MEDIA_PROXY_PLAYBACK_SPEED_QUARTER -128
109 : /** Half playback speed, resulting in 50 % speed */
110 1 : #define MEDIA_PROXY_PLAYBACK_SPEED_HALF -64
111 : /** Unity playback speed, resulting in 100 % speed */
112 1 : #define MEDIA_PROXY_PLAYBACK_SPEED_UNITY 0
113 : /** Double playback speed, resulting in 200 % speed */
114 1 : #define MEDIA_PROXY_PLAYBACK_SPEED_DOUBLE 64
115 : /** Max playback speed, resulting in 395.7 % speed (nearly 400 %) */
116 1 : #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 1 : #define MEDIA_PROXY_SEEKING_SPEED_FACTOR_MAX 64
129 : /** Minimum seeking speed - Can be negated */
130 1 : #define MEDIA_PROXY_SEEKING_SPEED_FACTOR_MIN 4
131 : /** No seeking */
132 1 : #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 1 : #define MEDIA_PROXY_PLAYING_ORDER_SINGLE_ONCE 0x01
141 : /** A single track is played repeatedly; the next track is the current track. */
142 1 : #define MEDIA_PROXY_PLAYING_ORDER_SINGLE_REPEAT 0x02
143 : /** The tracks within a group are played once in track order. */
144 1 : #define MEDIA_PROXY_PLAYING_ORDER_INORDER_ONCE 0x03
145 : /** The tracks within a group are played in track order repeatedly. */
146 1 : #define MEDIA_PROXY_PLAYING_ORDER_INORDER_REPEAT 0x04
147 : /** The tracks within a group are played once only from the oldest first. */
148 1 : #define MEDIA_PROXY_PLAYING_ORDER_OLDEST_ONCE 0x05
149 : /** The tracks within a group are played from the oldest first repeatedly. */
150 1 : #define MEDIA_PROXY_PLAYING_ORDER_OLDEST_REPEAT 0x06
151 : /** The tracks within a group are played once only from the newest first. */
152 1 : #define MEDIA_PROXY_PLAYING_ORDER_NEWEST_ONCE 0x07
153 : /** The tracks within a group are played from the newest first repeatedly. */
154 1 : #define MEDIA_PROXY_PLAYING_ORDER_NEWEST_REPEAT 0x08
155 : /** The tracks within a group are played in random order once. */
156 1 : #define MEDIA_PROXY_PLAYING_ORDER_SHUFFLE_ONCE 0x09
157 : /** The tracks within a group are played in random order repeatedly. */
158 1 : #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 1 : #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 1 : #define MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_SINGLE_REPEAT BIT(1)
172 : /** The tracks within a group are played once in track order. */
173 1 : #define MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_INORDER_ONCE BIT(2)
174 : /** The tracks within a group are played in track order repeatedly. */
175 1 : #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 1 : #define MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_OLDEST_ONCE BIT(4)
178 : /** The tracks within a group are played from the oldest first repeatedly. */
179 1 : #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 1 : #define MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_NEWEST_ONCE BIT(6)
182 : /** The tracks within a group are played from the newest first repeatedly. */
183 1 : #define MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_NEWEST_REPEAT BIT(7)
184 : /** The tracks within a group are played in random order once. */
185 1 : #define MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_SHUFFLE_ONCE BIT(8)
186 : /** The tracks within a group are played in random order repeatedly. */
187 1 : #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 1 : #define MEDIA_PROXY_STATE_INACTIVE 0x00
196 : /** The media player is playing the current track. */
197 1 : #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 1 : #define MEDIA_PROXY_STATE_PAUSED 0x02
200 : /** The current track is fast forwarding or fast rewinding. */
201 1 : #define MEDIA_PROXY_STATE_SEEKING 0x03
202 : /** Used internally as the last state value */
203 1 : #define MEDIA_PROXY_STATE_LAST 0x04
204 : /** @} */
205 :
206 : /**
207 : * @name Media player command opcodes
208 : * @{
209 : */
210 : /** Start playing the current track. */
211 1 : #define MEDIA_PROXY_OP_PLAY 0x01
212 : /** Pause playing the current track. */
213 1 : #define MEDIA_PROXY_OP_PAUSE 0x02
214 : /** Fast rewind the current track. */
215 1 : #define MEDIA_PROXY_OP_FAST_REWIND 0x03
216 : /** Fast forward the current track. */
217 1 : #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 1 : #define MEDIA_PROXY_OP_STOP 0x05
223 :
224 : /** Set a new current track position relative to the current track position. */
225 1 : #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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #define MEDIA_PROXY_OP_GOTO_SEGMENT 0x24
252 :
253 : /** Set the current track to the previous track based on the playing order. */
254 1 : #define MEDIA_PROXY_OP_PREV_TRACK 0x30
255 : /** Set the current track to the next track based on the playing order. */
256 1 : #define MEDIA_PROXY_OP_NEXT_TRACK 0x31
257 : /** Set the current track to the first track based on the playing order. */
258 1 : #define MEDIA_PROXY_OP_FIRST_TRACK 0x32
259 : /** Set the current track to the last track based on the playing order. */
260 1 : #define MEDIA_PROXY_OP_LAST_TRACK 0x33
261 : /** Set the current track to the nth track based on the playing order. */
262 1 : #define MEDIA_PROXY_OP_GOTO_TRACK 0x34
263 :
264 : /** Set the current group to the previous group in the sequence of groups. */
265 1 : #define MEDIA_PROXY_OP_PREV_GROUP 0x40
266 : /** Set the current group to the next group in the sequence of groups. */
267 1 : #define MEDIA_PROXY_OP_NEXT_GROUP 0x41
268 : /** Set the current group to the first group in the sequence of groups. */
269 1 : #define MEDIA_PROXY_OP_FIRST_GROUP 0x42
270 : /** Set the current group to the last group in the sequence of groups. */
271 1 : #define MEDIA_PROXY_OP_LAST_GROUP 0x43
272 : /** Set the current group to the nth group in the sequence of groups. */
273 1 : #define MEDIA_PROXY_OP_GOTO_GROUP 0x44
274 : /** @} */
275 :
276 : /**
277 : * @brief Media player supported opcodes length
278 : */
279 1 : #define MEDIA_PROXY_OPCODES_SUPPORTED_LEN 4
280 :
281 : /**
282 : * @brief Media player supported command opcodes
283 : * @{
284 : */
285 : /** Support the Play opcode */
286 1 : #define MEDIA_PROXY_OP_SUP_PLAY BIT(0)
287 : /** Support the Pause opcode */
288 1 : #define MEDIA_PROXY_OP_SUP_PAUSE BIT(1)
289 : /** Support the Fast Rewind opcode */
290 1 : #define MEDIA_PROXY_OP_SUP_FAST_REWIND BIT(2)
291 : /** Support the Fast Forward opcode */
292 1 : #define MEDIA_PROXY_OP_SUP_FAST_FORWARD BIT(3)
293 : /** Support the Stop opcode */
294 1 : #define MEDIA_PROXY_OP_SUP_STOP BIT(4)
295 :
296 : /** Support the Move Relative opcode */
297 1 : #define MEDIA_PROXY_OP_SUP_MOVE_RELATIVE BIT(5)
298 :
299 : /** Support the Previous Segment opcode */
300 1 : #define MEDIA_PROXY_OP_SUP_PREV_SEGMENT BIT(6)
301 : /** Support the Next Segment opcode */
302 1 : #define MEDIA_PROXY_OP_SUP_NEXT_SEGMENT BIT(7)
303 : /** Support the First Segment opcode */
304 1 : #define MEDIA_PROXY_OP_SUP_FIRST_SEGMENT BIT(8)
305 : /** Support the Last Segment opcode */
306 1 : #define MEDIA_PROXY_OP_SUP_LAST_SEGMENT BIT(9)
307 : /** Support the Goto Segment opcode */
308 1 : #define MEDIA_PROXY_OP_SUP_GOTO_SEGMENT BIT(10)
309 :
310 : /** Support the Previous Track opcode */
311 1 : #define MEDIA_PROXY_OP_SUP_PREV_TRACK BIT(11)
312 : /** Support the Next Track opcode */
313 1 : #define MEDIA_PROXY_OP_SUP_NEXT_TRACK BIT(12)
314 : /** Support the First Track opcode */
315 1 : #define MEDIA_PROXY_OP_SUP_FIRST_TRACK BIT(13)
316 : /** Support the Last Track opcode */
317 1 : #define MEDIA_PROXY_OP_SUP_LAST_TRACK BIT(14)
318 : /** Support the Goto Track opcode */
319 1 : #define MEDIA_PROXY_OP_SUP_GOTO_TRACK BIT(15)
320 :
321 : /** Support the Previous Group opcode */
322 1 : #define MEDIA_PROXY_OP_SUP_PREV_GROUP BIT(16)
323 : /** Support the Next Group opcode */
324 1 : #define MEDIA_PROXY_OP_SUP_NEXT_GROUP BIT(17)
325 : /** Support the First Group opcode */
326 1 : #define MEDIA_PROXY_OP_SUP_FIRST_GROUP BIT(18)
327 : /** Support the Last Group opcode */
328 1 : #define MEDIA_PROXY_OP_SUP_LAST_GROUP BIT(19)
329 : /** Support the Goto Group opcode */
330 1 : #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 1 : #define MEDIA_PROXY_CMD_SUCCESS 0x01
339 : /** An invalid or unsupported opcode was used for the Media Control Point write. */
340 1 : #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 1 : #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 1 : #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 1 : #define MEDIA_PROXY_SEARCH_TYPE_TRACK_NAME 0x01
360 : /** Search for Artist Name */
361 1 : #define MEDIA_PROXY_SEARCH_TYPE_ARTIST_NAME 0x02
362 : /** Search for Album Name */
363 1 : #define MEDIA_PROXY_SEARCH_TYPE_ALBUM_NAME 0x03
364 : /** Search for Group Name */
365 1 : #define MEDIA_PROXY_SEARCH_TYPE_GROUP_NAME 0x04
366 : /** Search for Earliest Year */
367 1 : #define MEDIA_PROXY_SEARCH_TYPE_EARLIEST_YEAR 0x05
368 : /** Search for Latest Year */
369 1 : #define MEDIA_PROXY_SEARCH_TYPE_LATEST_YEAR 0x06
370 : /** Search for Genre */
371 1 : #define MEDIA_PROXY_SEARCH_TYPE_GENRE 0x07
372 : /** Search for Tracks only */
373 1 : #define MEDIA_PROXY_SEARCH_TYPE_ONLY_TRACKS 0x08
374 : /** Search for Groups only */
375 1 : #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 1 : #define MEDIA_PROXY_SEARCH_SUCCESS 0x01
385 : /** Search request was invalid; no search started. */
386 1 : #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 1 : #define MEDIA_PROXY_GROUP_OBJECT_TRACK_TYPE 0x00
396 : /** Group object type is group */
397 1 : #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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : struct media_proxy_pl_calls {
1273 :
1274 : /**
1275 : * @brief Read Media Player Name
1276 : *
1277 : * @return The name of the media player
1278 : */
1279 1 : 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 1 : 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 1 : const char *(*get_icon_url)(void);
1302 :
1303 : /**
1304 : * @brief Read Track Title
1305 : *
1306 : * @return The title of the current track
1307 : */
1308 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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_ */
|
