Bluetooth Media

API Reference

Media Control Service

group bt_mcs

Media Control Service (MCS)

Definitions and types related to the Media Control Service and Media Control Profile specifications.

Since: 3.0
Version: 0.8.0

Defines

BT_MCS_ERR_LONG_VAL_CHANGED

BT_MCS_PLAYBACK_SPEED_MIN

Playback speeds.

All values from -128 to 127 allowed, only some defined

BT_MCS_PLAYBACK_SPEED_QUARTER

BT_MCS_PLAYBACK_SPEED_HALF

BT_MCS_PLAYBACK_SPEED_UNITY

BT_MCS_PLAYBACK_SPEED_DOUBLE

BT_MCS_PLAYBACK_SPEED_MAX

BT_MCS_SEEKING_SPEED_FACTOR_MAX

Seeking speed.

The allowed values for seeking speed are the range -64 to -4 (endpoints included), the value 0, and the range 4 to 64 (endpoints included).

BT_MCS_SEEKING_SPEED_FACTOR_MIN

BT_MCS_SEEKING_SPEED_FACTOR_ZERO

BT_MCS_PLAYING_ORDER_SINGLE_ONCE: Playing orders.

BT_MCS_PLAYING_ORDER_SINGLE_REPEAT

BT_MCS_PLAYING_ORDER_INORDER_ONCE

BT_MCS_PLAYING_ORDER_INORDER_REPEAT

BT_MCS_PLAYING_ORDER_OLDEST_ONCE

BT_MCS_PLAYING_ORDER_OLDEST_REPEAT

BT_MCS_PLAYING_ORDER_NEWEST_ONCE

BT_MCS_PLAYING_ORDER_NEWEST_REPEAT

BT_MCS_PLAYING_ORDER_SHUFFLE_ONCE

BT_MCS_PLAYING_ORDER_SHUFFLE_REPEAT

BT_MCS_PLAYING_ORDERS_SUPPORTED_SINGLE_ONCE

Playing orders supported.

A bitmap, in the same order as the playing orders above. Note that playing order 1 corresponds to bit 0, and so on.

BT_MCS_PLAYING_ORDERS_SUPPORTED_SINGLE_REPEAT

BT_MCS_PLAYING_ORDERS_SUPPORTED_INORDER_ONCE

BT_MCS_PLAYING_ORDERS_SUPPORTED_INORDER_REPEAT

BT_MCS_PLAYING_ORDERS_SUPPORTED_OLDEST_ONCE

BT_MCS_PLAYING_ORDERS_SUPPORTED_OLDEST_REPEAT

BT_MCS_PLAYING_ORDERS_SUPPORTED_NEWEST_ONCE

BT_MCS_PLAYING_ORDERS_SUPPORTED_NEWEST_REPEAT

BT_MCS_PLAYING_ORDERS_SUPPORTED_SHUFFLE_ONCE

BT_MCS_PLAYING_ORDERS_SUPPORTED_SHUFFLE_REPEAT

BT_MCS_MEDIA_STATE_INACTIVE: Media states.

BT_MCS_MEDIA_STATE_PLAYING

BT_MCS_MEDIA_STATE_PAUSED

BT_MCS_MEDIA_STATE_SEEKING

BT_MCS_MEDIA_STATE_LAST

BT_MCS_OPC_PLAY: Media control point opcodes.

BT_MCS_OPC_PAUSE

BT_MCS_OPC_FAST_REWIND

BT_MCS_OPC_FAST_FORWARD

BT_MCS_OPC_STOP

BT_MCS_OPC_MOVE_RELATIVE

BT_MCS_OPC_PREV_SEGMENT

BT_MCS_OPC_NEXT_SEGMENT

BT_MCS_OPC_FIRST_SEGMENT

BT_MCS_OPC_LAST_SEGMENT

BT_MCS_OPC_GOTO_SEGMENT

BT_MCS_OPC_PREV_TRACK

BT_MCS_OPC_NEXT_TRACK

BT_MCS_OPC_FIRST_TRACK

BT_MCS_OPC_LAST_TRACK

BT_MCS_OPC_GOTO_TRACK

BT_MCS_OPC_PREV_GROUP

BT_MCS_OPC_NEXT_GROUP

BT_MCS_OPC_FIRST_GROUP

BT_MCS_OPC_LAST_GROUP

BT_MCS_OPC_GOTO_GROUP

BT_MCS_OPCODES_SUPPORTED_LEN: Media control point supported opcodes length.

BT_MCS_OPC_SUP_PLAY: Media control point supported opcodes values.

BT_MCS_OPC_SUP_PAUSE

BT_MCS_OPC_SUP_FAST_REWIND

BT_MCS_OPC_SUP_FAST_FORWARD

BT_MCS_OPC_SUP_STOP

BT_MCS_OPC_SUP_MOVE_RELATIVE

BT_MCS_OPC_SUP_PREV_SEGMENT

BT_MCS_OPC_SUP_NEXT_SEGMENT

BT_MCS_OPC_SUP_FIRST_SEGMENT

BT_MCS_OPC_SUP_LAST_SEGMENT

BT_MCS_OPC_SUP_GOTO_SEGMENT

BT_MCS_OPC_SUP_PREV_TRACK

BT_MCS_OPC_SUP_NEXT_TRACK

BT_MCS_OPC_SUP_FIRST_TRACK

BT_MCS_OPC_SUP_LAST_TRACK

BT_MCS_OPC_SUP_GOTO_TRACK

BT_MCS_OPC_SUP_PREV_GROUP

BT_MCS_OPC_SUP_NEXT_GROUP

BT_MCS_OPC_SUP_FIRST_GROUP

BT_MCS_OPC_SUP_LAST_GROUP

BT_MCS_OPC_SUP_GOTO_GROUP

BT_MCS_OPC_NTF_SUCCESS: Media control point notification result codes.

BT_MCS_OPC_NTF_NOT_SUPPORTED

BT_MCS_OPC_NTF_PLAYER_INACTIVE

BT_MCS_OPC_NTF_CANNOT_BE_COMPLETED

BT_MCS_SEARCH_TYPE_TRACK_NAME: Search control point type values.

BT_MCS_SEARCH_TYPE_ARTIST_NAME

BT_MCS_SEARCH_TYPE_ALBUM_NAME

BT_MCS_SEARCH_TYPE_GROUP_NAME

BT_MCS_SEARCH_TYPE_EARLIEST_YEAR

BT_MCS_SEARCH_TYPE_LATEST_YEAR

BT_MCS_SEARCH_TYPE_GENRE

BT_MCS_SEARCH_TYPE_ONLY_TRACKS

BT_MCS_SEARCH_TYPE_ONLY_GROUPS

SEARCH_LEN_MIN: Search control point values.

SEARCH_SCI_LEN_MIN

SEARCH_LEN_MAX

SEARCH_PARAM_MAX

BT_MCS_SCP_NTF_SUCCESS: Search notification result codes.

BT_MCS_SCP_NTF_FAILURE

BT_MCS_GROUP_OBJECT_TRACK_TYPE

BT_MCS_GROUP_OBJECT_GROUP_TYPE

Media Proxy

group bt_media_proxy

Media proxy module.

The media proxy module is the connection point between media players and media controllers.

Since: 3.0
Version: 0.8.0

A media player has (access to) media content and knows how to navigate and play this content. A media controller reads or gets information from a player and controls the player by setting player parameters and giving the player commands.

The media proxy module allows media player implementations to make themselves available to media controllers. And it allows controllers to access, and get updates from, any player.

The media proxy module allows both local and remote control of local player instances: A media controller may be a local application, or it may be a Media Control Service relaying requests from a remote Media Control Client. There may be either local or remote control, or both, or even multiple instances of each.

Defines

MEDIA_PROXY_PLAYBACK_SPEED_MIN

Playback speed parameters.

All values from -128 to 127 allowed, only some defined

MEDIA_PROXY_PLAYBACK_SPEED_QUARTER

MEDIA_PROXY_PLAYBACK_SPEED_HALF

MEDIA_PROXY_PLAYBACK_SPEED_UNITY

MEDIA_PROXY_PLAYBACK_SPEED_DOUBLE

MEDIA_PROXY_PLAYBACK_SPEED_MAX

MEDIA_PROXY_SEEKING_SPEED_FACTOR_MAX

Seeking speed factors.

The allowed values for seeking speed are the range -64 to -4 (endpoints included), the value 0, and the range 4 to 64 (endpoints included).

MEDIA_PROXY_SEEKING_SPEED_FACTOR_MIN

MEDIA_PROXY_SEEKING_SPEED_FACTOR_ZERO

MEDIA_PROXY_PLAYING_ORDER_SINGLE_ONCE: Playing orders.

MEDIA_PROXY_PLAYING_ORDER_SINGLE_REPEAT

MEDIA_PROXY_PLAYING_ORDER_INORDER_ONCE

MEDIA_PROXY_PLAYING_ORDER_INORDER_REPEAT

MEDIA_PROXY_PLAYING_ORDER_OLDEST_ONCE

MEDIA_PROXY_PLAYING_ORDER_OLDEST_REPEAT

MEDIA_PROXY_PLAYING_ORDER_NEWEST_ONCE

MEDIA_PROXY_PLAYING_ORDER_NEWEST_REPEAT

MEDIA_PROXY_PLAYING_ORDER_SHUFFLE_ONCE

MEDIA_PROXY_PLAYING_ORDER_SHUFFLE_REPEAT

MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_SINGLE_ONCE

Playing orders supported.

A bitmap, in the same order as the playing orders above. Note that playing order 1 corresponds to bit 0, and so on.

MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_SINGLE_REPEAT

MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_INORDER_ONCE

MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_INORDER_REPEAT

MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_OLDEST_ONCE

MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_OLDEST_REPEAT

MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_NEWEST_ONCE

MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_NEWEST_REPEAT

MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_SHUFFLE_ONCE

MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_SHUFFLE_REPEAT

MEDIA_PROXY_STATE_INACTIVE: Media player states.

MEDIA_PROXY_STATE_PLAYING

MEDIA_PROXY_STATE_PAUSED

MEDIA_PROXY_STATE_SEEKING

MEDIA_PROXY_STATE_LAST

MEDIA_PROXY_OP_PLAY: Media player command opcodes.

MEDIA_PROXY_OP_PAUSE

MEDIA_PROXY_OP_FAST_REWIND

MEDIA_PROXY_OP_FAST_FORWARD

MEDIA_PROXY_OP_STOP

MEDIA_PROXY_OP_MOVE_RELATIVE

MEDIA_PROXY_OP_PREV_SEGMENT

MEDIA_PROXY_OP_NEXT_SEGMENT

MEDIA_PROXY_OP_FIRST_SEGMENT

MEDIA_PROXY_OP_LAST_SEGMENT

MEDIA_PROXY_OP_GOTO_SEGMENT

MEDIA_PROXY_OP_PREV_TRACK

MEDIA_PROXY_OP_NEXT_TRACK

MEDIA_PROXY_OP_FIRST_TRACK

MEDIA_PROXY_OP_LAST_TRACK

MEDIA_PROXY_OP_GOTO_TRACK

MEDIA_PROXY_OP_PREV_GROUP

MEDIA_PROXY_OP_NEXT_GROUP

MEDIA_PROXY_OP_FIRST_GROUP

MEDIA_PROXY_OP_LAST_GROUP

MEDIA_PROXY_OP_GOTO_GROUP

MEDIA_PROXY_OPCODES_SUPPORTED_LEN: Media player supported opcodes length.

MEDIA_PROXY_OP_SUP_PLAY: Media player supported command opcodes.

MEDIA_PROXY_OP_SUP_PAUSE

MEDIA_PROXY_OP_SUP_FAST_REWIND

MEDIA_PROXY_OP_SUP_FAST_FORWARD

MEDIA_PROXY_OP_SUP_STOP

MEDIA_PROXY_OP_SUP_MOVE_RELATIVE

MEDIA_PROXY_OP_SUP_PREV_SEGMENT

MEDIA_PROXY_OP_SUP_NEXT_SEGMENT

MEDIA_PROXY_OP_SUP_FIRST_SEGMENT

MEDIA_PROXY_OP_SUP_LAST_SEGMENT

MEDIA_PROXY_OP_SUP_GOTO_SEGMENT

MEDIA_PROXY_OP_SUP_PREV_TRACK

MEDIA_PROXY_OP_SUP_NEXT_TRACK

MEDIA_PROXY_OP_SUP_FIRST_TRACK

MEDIA_PROXY_OP_SUP_LAST_TRACK

MEDIA_PROXY_OP_SUP_GOTO_TRACK

MEDIA_PROXY_OP_SUP_PREV_GROUP

MEDIA_PROXY_OP_SUP_NEXT_GROUP

MEDIA_PROXY_OP_SUP_FIRST_GROUP

MEDIA_PROXY_OP_SUP_LAST_GROUP

MEDIA_PROXY_OP_SUP_GOTO_GROUP

MEDIA_PROXY_CMD_SUCCESS: Media player command result codes.

MEDIA_PROXY_CMD_NOT_SUPPORTED

MEDIA_PROXY_CMD_PLAYER_INACTIVE

MEDIA_PROXY_CMD_CANNOT_BE_COMPLETED

MEDIA_PROXY_SEARCH_TYPE_TRACK_NAME: Search operation type values.

MEDIA_PROXY_SEARCH_TYPE_ARTIST_NAME

MEDIA_PROXY_SEARCH_TYPE_ALBUM_NAME

MEDIA_PROXY_SEARCH_TYPE_GROUP_NAME

MEDIA_PROXY_SEARCH_TYPE_EARLIEST_YEAR

MEDIA_PROXY_SEARCH_TYPE_LATEST_YEAR

MEDIA_PROXY_SEARCH_TYPE_GENRE

MEDIA_PROXY_SEARCH_TYPE_ONLY_TRACKS

MEDIA_PROXY_SEARCH_TYPE_ONLY_GROUPS

MEDIA_PROXY_SEARCH_SUCCESS: Search operation result codes.

MEDIA_PROXY_SEARCH_FAILURE

MEDIA_PROXY_GROUP_OBJECT_TRACK_TYPE

MEDIA_PROXY_GROUP_OBJECT_GROUP_TYPE

Functions

int media_proxy_ctrl_register(struct media_proxy_ctrl_cbs *ctrl_cbs)

Register a controller with the media_proxy.

Parameters:

ctrl_cbs – Callbacks to the controller

Returns:

0 if success, errno on failure

int media_proxy_ctrl_discover_player(struct bt_conn *conn)

Discover a remote media player.

Discover a remote media player instance. The remote player instance will be discovered, and accessed, using Bluetooth, via the media control client and a remote media control service. This call will start a GATT discovery of the Media Control Service on the peer, and setup handles and subscriptions.

This shall be called once before any other actions can be executed for the remote player. The remote player instance will be returned in the discover_player() callback.

Parameters:

conn – The connection to do discovery for

Returns:

0 if success, errno on failure

int media_proxy_ctrl_get_player_name(struct media_player *player)

Read Media Player Name.

Parameters:

player – Media player instance pointer

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_get_icon_id(struct media_player *player)

Read Icon Object ID.

Get an ID (48 bit) that can be used to retrieve the Icon Object from an Object Transfer Service

See the Media Control Service spec v1.0 sections 3.2 and 4.1 for a description of the Icon Object.

Requires Object Transfer Service

Parameters:

player – Media player instance pointer

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_get_icon_url(struct media_player *player)

Read Icon URL.

Get a URL to the media player’s icon.

Parameters:

player – Media player instance pointer

int media_proxy_ctrl_get_track_title(struct media_player *player)

Read Track Title.

Parameters:

player – Media player instance pointer

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_get_track_duration(struct media_player *player)

Read Track Duration.

The duration of a track is measured in hundredths of a second.

Parameters:

player – Media player instance pointer

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_get_track_position(struct media_player *player)

Read Track Position.

The position of the player (the playing position) is measured in hundredths of a second from the beginning of the track

Parameters:

player – Media player instance pointer

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_set_track_position(struct media_player *player, int32_t position)

Set Track Position.

Set the playing position of the media player in the current track. The position is given in in hundredths of a second, from the beginning of the track of the track for positive values, and (backwards) from the end of the track for negative values.

Parameters:

player – Media player instance pointer
position – The track position to set

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_get_playback_speed(struct media_player *player)

Get Playback Speed.

The playback speed parameter is related to the actual playback speed as follows: actual playback speed = 2^(speed_parameter/64)

A speed parameter of 0 corresponds to unity speed playback (i.e. playback at “normal” speed). A speed parameter of -128 corresponds to playback at one fourth of normal speed, 127 corresponds to playback at almost four times the normal speed.

Parameters:

player – Media player instance pointer

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_set_playback_speed(struct media_player *player, int8_t speed)

Set Playback Speed.

See the get_playback_speed() function for an explanation of the playback speed parameter.

Note that the media player may not support all possible values of the playback speed parameter. If the value given is not supported, and is higher than the current value, the player should set the playback speed to the next higher supported value. (And correspondingly to the next lower supported value for given values lower than the current value.)

Parameters:

player – Media player instance pointer
speed – The playback speed parameter to set

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_get_seeking_speed(struct media_player *player)

Get Seeking Speed.

The seeking speed gives the speed with which the player is seeking. It is a factor, relative to real-time playback speed - a factor four means seeking happens at four times the real-time playback speed. Positive values are for forward seeking, negative values for backwards seeking.

The seeking speed is not settable - a non-zero seeking speed is the result of “fast rewind” of “fast forward” commands.

Parameters:

player – Media player instance pointer

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_get_track_segments_id(struct media_player *player)

Read Current Track Segments Object ID.

Get an ID (48 bit) that can be used to retrieve the Current Track Segments Object from an Object Transfer Service

See the Media Control Service spec v1.0 sections 3.10 and 4.2 for a description of the Track Segments Object.

Requires Object Transfer Service

Parameters:

player – Media player instance pointer

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_get_current_track_id(struct media_player *player)

Read Current Track Object ID.

Get an ID (48 bit) that can be used to retrieve the Current Track Object from an Object Transfer Service

See the Media Control Service spec v1.0 sections 3.11 and 4.3 for a description of the Current Track Object.

Requires Object Transfer Service

Parameters:

player – Media player instance pointer

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_set_current_track_id(struct media_player *player, uint64_t id)

Set Current Track Object ID.

Change the player’s current track to the track given by the ID. (Behaves similarly to the goto track command.)

Requires Object Transfer Service

Parameters:

player – Media player instance pointer
id – The ID of a track object

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_get_next_track_id(struct media_player *player)

Media Control Client

group bt_gatt_mcc

Bluetooth Media Control Client (MCC) interface.

Updated to the Media Control Profile specification revision 1.0

Since: 3.0
Version: 0.8.0

Typedefs

typedef void (*bt_mcc_discover_mcs_cb)(struct bt_conn *conn, int err)

Callback function for bt_mcc_discover_mcs()

Called when a media control server is discovered

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail

typedef void (*bt_mcc_read_player_name_cb)(struct bt_conn *conn, int err, const char *name)

Callback function for bt_mcc_read_player_name()

Called when the player name is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param name:: Player name

typedef void (*bt_mcc_read_icon_obj_id_cb)(struct bt_conn *conn, int err, uint64_t icon_id)

Callback function for bt_mcc_read_icon_obj_id()

Called when the icon object ID is read

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param icon_id:: The ID of the Icon Object. This is a UINT48 in a uint64_t

typedef void (*bt_mcc_read_icon_url_cb)(struct bt_conn *conn, int err, const char *icon_url)

Callback function for bt_mcc_read_icon_url()

Called when the icon URL is read

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param icon_url:: The URL of the Icon

typedef void (*bt_mcc_track_changed_ntf_cb)(struct bt_conn *conn, int err)

Callback function for track changed notifications.

Called when a track change is notified.

The track changed characteristic is a special case. It can not be read or set, it can only be notified.

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail

typedef void (*bt_mcc_read_track_title_cb)(struct bt_conn *conn, int err, const char *title)

Callback function for bt_mcc_read_track_title()

Called when the track title is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param title:: The title of the track

typedef void (*bt_mcc_read_track_duration_cb)(struct bt_conn *conn, int err, int32_t dur)

Callback function for bt_mcc_read_track_duration()

Called when the track duration is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param dur:: The duration of the track

typedef void (*bt_mcc_read_track_position_cb)(struct bt_conn *conn, int err, int32_t pos)

Callback function for bt_mcc_read_track_position()

Called when the track position is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param pos:: The Track Position

typedef void (*bt_mcc_set_track_position_cb)(struct bt_conn *conn, int err, int32_t pos)

Callback function for bt_mcc_set_track_position()

Called when the track position is set

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param pos:: The Track Position set (or attempted to set)

typedef void (*bt_mcc_read_playback_speed_cb)(struct bt_conn *conn, int err, int8_t speed)

Callback function for bt_mcc_read_playback_speed()

Called when the playback speed is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param speed:: The Playback Speed

typedef void (*bt_mcc_set_playback_speed_cb)(struct bt_conn *conn, int err, int8_t speed)

Callback function for bt_mcc_set_playback_speed()

Called when the playback speed is set

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param speed:: The Playback Speed set (or attempted to set)

typedef void (*bt_mcc_read_seeking_speed_cb)(struct bt_conn *conn, int err, int8_t speed)

Callback function for bt_mcc_read_seeking_speed()

Called when the seeking speed is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param speed:: The Seeking Speed

typedef void (*bt_mcc_read_segments_obj_id_cb)(struct bt_conn *conn, int err, uint64_t id)

Callback function for bt_mcc_read_segments_obj_id()

Called when the track segments object ID is read

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param id:: The Track Segments Object ID (UINT48)

typedef void (*bt_mcc_read_current_track_obj_id_cb)(struct bt_conn *conn, int err, uint64_t id)

Callback function for bt_mcc_read_current_track_obj_id()

Called when the current track object ID is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param id:: The Current Track Object ID (UINT48)

typedef void (*bt_mcc_set_current_track_obj_id_cb)(struct bt_conn *conn, int err, uint64_t id)

Callback function for bt_mcc_set_current_track_obj_id()

Called when the current track object ID is set

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param id:: The Object ID (UINT48) set (or attempted to set)

typedef void (*bt_mcc_read_next_track_obj_id_cb)(struct bt_conn *conn, int err, uint64_t id)

Callback function for bt_mcc_read_next_track_obj_id_obj()

Called when the next track object ID is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param id:: The Next Track Object ID (UINT48)

typedef void (*bt_mcc_set_next_track_obj_id_cb)(struct bt_conn *conn, int err, uint64_t id)

Callback function for bt_mcc_set_next_track_obj_id()

Called when the next track object ID is set

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param id:: The Object ID (UINT48) set (or attempted to set)

typedef void (*bt_mcc_read_parent_group_obj_id_cb)(struct bt_conn *conn, int err, uint64_t id)

Callback function for bt_mcc_read_parent_group_obj_id()

Called when the parent group object ID is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param id:: The Parent Group Object ID (UINT48)

typedef void (*bt_mcc_read_current_group_obj_id_cb)(struct bt_conn *conn, int err, uint64_t id)

Callback function for bt_mcc_read_current_group_obj_id()

Called when the current group object ID is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param id:: The Current Group Object ID (UINT48)

typedef void (*bt_mcc_set_current_group_obj_id_cb)(struct bt_conn *conn, int err, uint64_t obj_id)

Callback function for bt_mcc_set_current_group_obj_id()

Called when the current group object ID is set

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param obj_id:: The Object ID (UINT48) set (or attempted to set)

typedef void (*bt_mcc_read_playing_order_cb)(struct bt_conn *conn, int err, uint8_t order)

Callback function for bt_mcc_read_playing_order()

Called when the playing order is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param order:: The playback order

typedef void (*bt_mcc_set_playing_order_cb)(struct bt_conn *conn, int err, uint8_t order)

Callback function for bt_mcc_set_playing_order()

Called when the playing order is set

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param order:: The Playing Order set (or attempted to set)

typedef void (*bt_mcc_read_playing_orders_supported_cb)(struct bt_conn *conn, int err, uint16_t orders)

Callback function for bt_mcc_read_playing_orders_supported()

Called when the supported playing orders are read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param orders:: The playing orders supported (bitmap)

typedef void (*bt_mcc_read_media_state_cb)(struct bt_conn *conn, int err, uint8_t state)

Callback function for bt_mcc_read_media_state()

Called when the media state is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param state:: The Media State

typedef void (*bt_mcc_send_cmd_cb)(struct bt_conn *conn, int err, const struct mpl_cmd *cmd)

Callback function for bt_mcc_send_cmd()

Called when a command is sent, i.e. when the media control point is set

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param cmd:: The command sent

typedef void (*bt_mcc_cmd_ntf_cb)(struct bt_conn *conn, int err, const struct mpl_cmd_ntf *ntf)

Callback function for command notifications.

Called when the media control point is notified

Notifications for commands (i.e. for writes to the media control point) use a different parameter structure than what is used for sending commands (writing to the media control point)

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param ntf:: The command notification

typedef void (*bt_mcc_read_opcodes_supported_cb)(struct bt_conn *conn, int err, uint32_t opcodes)

Callback function for bt_mcc_read_opcodes_supported()

Called when the supported opcodes (commands) are read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param opcodes:: The supported opcodes

typedef void (*bt_mcc_send_search_cb)(struct bt_conn *conn, int err, const struct mpl_search *search)

Callback function for bt_mcc_send_search()

Called when a search is sent, i.e. when the search control point is set

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param search:: The search set (or attempted to set)

typedef void (*bt_mcc_search_ntf_cb)(struct bt_conn *conn, int err, uint8_t result_code)

Callback function for search notifications.

Called when the search control point is notified

Notifications for searches (i.e. for writes to the search control point) use a different parameter structure than what is used for sending searches (writing to the search control point)

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param result_code:: The search notification

typedef void (*bt_mcc_read_search_results_obj_id_cb)(struct bt_conn *conn, int err, uint64_t id)

Callback function for bt_mcc_read_search_results_obj_id()

Called when the search results object ID is read or notified

Note that the Search Results Object ID value may be zero, in case the characteristic does not exist on the server. (This will be the case if there has not been a successful search.)

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param id:: The Search Results Object ID (UINT48)

typedef void (*bt_mcc_read_content_control_id_cb)(struct bt_conn *conn, int err, uint8_t ccid)

Callback function for bt_mcc_read_content_control_id()

Called when the content control ID is read

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param ccid:: The Content Control ID

typedef void (*bt_mcc_otc_obj_selected_cb)(struct bt_conn *conn, int err)

Callback function for object selected.

Called when an object is selected

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail

typedef void (*bt_mcc_otc_obj_metadata_cb)(struct bt_conn *conn, int err)

Callback function for bt_mcc_otc_read_object_meatadata()

Called when object metadata is read

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail

typedef void (*bt_mcc_otc_read_icon_object_cb)(struct bt_conn *conn, int err, struct net_buf_simple *buf)

Callback function for bt_mcc_otc_read_icon_object()

Called when the icon object is read

If err is EMSGSIZE, the object contents have been truncated.

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param buf:: Buffer containing the object contents

typedef void (*bt_mcc_otc_read_track_segments_object_cb)(struct bt_conn *conn, int err, struct net_buf_simple *buf)

Callback function for bt_mcc_otc_read_track_segments_object()

Called when the track segments object is read

If err is EMSGSIZE, the object contents have been truncated.

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param buf:: Buffer containing the object contents

typedef void (*bt_mcc_otc_read_current_track_object_cb)(struct bt_conn *conn, int err, struct net_buf_simple *buf)

Callback function for bt_mcc_otc_read_current_track_object()

Called when the current track object is read

If err is EMSGSIZE, the object contents have been truncated.

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param buf:: Buffer containing the object contents

typedef void (*bt_mcc_otc_read_next_track_object_cb)(struct bt_conn *conn, int err, struct net_buf_simple *buf)

Callback function for bt_mcc_otc_read_next_track_object()

Called when the next track object is read

If err is EMSGSIZE, the object contents have been truncated.

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param buf:: Buffer containing the object contents

typedef void (*bt_mcc_otc_read_parent_group_object_cb)(struct bt_conn *conn, int err, struct net_buf_simple *buf)

Callback function for bt_mcc_otc_read_parent_group_object()

Called when the parent group object is read

If err is EMSGSIZE, the object contents have been truncated.

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param buf:: Buffer containing the object contents

typedef void (*bt_mcc_otc_read_current_group_object_cb)(struct bt_conn *conn, int err, struct net_buf_simple *buf)

Callback function for bt_mcc_otc_read_current_group_object()

Called when the current group object is read

If err is EMSGSIZE, the object contents have been truncated.

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param buf:: Buffer containing the object contents

Functions

int bt_mcc_init(struct bt_mcc_cb *cb)

Initialize Media Control Client.

Parameters:

cb – Callbacks to be used

Returns:

0 if success, errno on failure.

int bt_mcc_discover_mcs(struct bt_conn *conn, bool subscribe)

Discover Media Control Service.

Discover Media Control Service (MCS) on the server given by the connection Optionally subscribe to notifications.

Shall be called once, after media control client initialization and before using other media control client functionality.

Parameters:

conn – Connection to the peer device
subscribe – Whether to subscribe to notifications

Returns:

0 if success, errno on failure.

int bt_mcc_read_player_name(struct bt_conn *conn)

Read Media Player Name.

Parameters:

conn – Connection to the peer device

Returns:

0 if success, errno on failure.

int bt_mcc_read_icon_obj_id(struct bt_conn *conn)

Read Icon Object ID.

Parameters:

conn – Connection to the peer device

Returns:

0 if success, errno on failure.

int bt_mcc_read_icon_url(struct bt_conn *conn)

Read Icon Object URL.

Parameters:

conn – Connection to the peer device

Returns:

0 if success, errno on failure.

int bt_mcc_read_track_title(struct bt_conn *conn)

Read Track Title.

Parameters:

conn – Connection to the peer device

Returns:

0 if success, errno on failure.

int bt_mcc_read_track_duration(struct bt_conn *conn)

Read Track Duration.

Parameters:

conn – Connection to the peer device

Returns:

0 if success, errno on failure.

int bt_mcc_read_track_position(struct bt_conn *conn)

Read Track Position.

Parameters:

conn – Connection to the peer device

Returns:

0 if success, errno on failure.

int bt_mcc_set_track_position(struct bt_conn *conn, int32_t pos)

Set Track position.

Parameters:

conn – Connection to the peer device
pos – Track position

Returns:

0 if success, errno on failure.

int bt_mcc_read_playback_speed(struct bt_conn *conn)

Read Playback speed.

Parameters:

conn – Connection to the peer device

Returns:

0 if success, errno on failure.

int bt_mcc_set_playback_speed(struct bt_conn *conn, int8_t speed)

Set Playback Speed.

Parameters:

conn – Connection to the peer device
speed – Playback speed

Returns:

0 if success, errno on failure.

int bt_mcc_read_seeking_speed(struct bt_conn *conn)

Read Seeking speed.

Parameters:

conn – Connection to the peer device

Returns:

0 if success, errno on failure.

int bt_mcc_read_segments_obj_id(struct bt_conn *conn)

Read Track Segments Object ID.

Parameters:

conn – Connection to the peer device

Returns:

0 if success, errno on failure.

int bt_mcc_read_current_track_obj_id(struct bt_conn *conn)

Read Current Track Object ID.

Parameters:

conn – Connection to the peer device

Returns:

0 if success, errno on failure.

int bt_mcc_set_current_track_obj_id(struct bt_conn *conn, uint64_t id)

Set Current Track Object ID.

Set the Current Track to the the track given by the id parameter

Parameters:

conn – Connection to the peer device
id – Object Transfer Service ID (UINT48) of the track to set as the current track

Returns:

0 if success, errno on failure.

int bt_mcc_read_next_track_obj_id(struct bt_conn *conn)