Apple Media Service (AMS) Client

API documentation

This module implements the Apple Media Service (AMS) client. This client can be used as a Media Remote (MR) to interact with a Media Source (MS). The MS is typically an iOS device. For detailed information about the Apple Media Service, see Apple Developer Documentation.

The AMS Client is used in the Bluetooth: Peripheral AMS client sample.

API documentation 

Header file: include/bluetooth/services/ams_client.h

Source file: subsys/bluetooth/services/ams_client.c

group bt_ams_client

Apple Media Service Client module.

Defines

BT_UUID_AMS_VAL: Apple Media Service UUID.

BT_UUID_AMS_REMOTE_COMMAND_VAL: Remote Command Characteristic UUID.

BT_UUID_AMS_ENTITY_UPDATE_VAL: Entity Update Characteristic UUID.

BT_UUID_AMS_ENTITY_ATTRIBUTE_VAL: Entity Attribute Characteristic UUID.

BT_UUID_AMS

BT_UUID_AMS_REMOTE_COMMAND

BT_UUID_AMS_ENTITY_UPDATE

BT_UUID_AMS_ENTITY_ATTRIBUTE

BT_AMS_EU_NOTIF_ENTITY_IDX: Entity Update notification: Entity index.

BT_AMS_EU_NOTIF_ATTRIBUTE_IDX: Entity Update notification: Attribute index.

BT_AMS_EU_NOTIF_FLAGS_IDX: Entity Update notification: Flags index.

BT_AMS_EU_NOTIF_VALUE_IDX: Entity Update notification: Value index.

BT_AMS_ENTITY_UPDATE_FLAG_TRUNCATED: Entity Update flag: truncated.

BT_AMS_EU_CMD_ENTITY_IDX: Entity Update command: Entity index.

BT_AMS_EU_CMD_ATTRIBUTE_IDX: Entity Update command: Attribute index.

BT_AMS_EU_CMD_ATTRIBUTE_COUNT_MAX: Entity Update command: Maximum value of Attribute ID count.

BT_AMS_EA_CMD_ENTITY_IDX: Entity Attribute command: Entity index.

BT_AMS_EA_CMD_ATTRIBUTE_IDX: Entity Attribute command: Attribute index.

BT_AMS_EA_CMD_LEN: Entity Attribute command length.

BT_ATT_ERR_AMS_MS_INVALID_STATE: AMS error code: MS is not properly set up.

BT_ATT_ERR_AMS_MS_INVALID_COMMAND: AMS error code: The command format is invalid.

BT_ATT_ERR_AMS_MS_ABSENT_ATTRIBUTE: AMS error code: The entity attribute is empty.

Typedefs

typedef void (*bt_ams_remote_command_notify_cb)(struct bt_ams_client *ams_c, const uint8_t *data, size_t len)

Remote Command notification callback function.

Param ams_c: [in] AMS client instance.
Param data: [in] List of Remote Command ID supported.
Param len: [in] Number of Remote Command ID.

typedef void (*bt_ams_entity_update_notify_cb)(struct bt_ams_client *ams_c, const struct bt_ams_entity_update_notif *notif, int err)

Entity Update notification callback function.

Param ams_c: [in] AMS client instance.
Param notif: [in] Notification data.
Param err: [in] 0 if the notification is valid. Otherwise, contains a (negative) error code.

typedef void (*bt_ams_write_cb)(struct bt_ams_client *ams_c, uint8_t err)

Write response callback function.

Param ams_c: [in] AMS client instance.
Param err: [in] ATT error code.

typedef void (*bt_ams_read_cb)(struct bt_ams_client *ams_c, uint8_t err, const uint8_t *data, size_t len)

Read response callback function.

Param ams_c: [in] AMS client instance.
Param err: [in] ATT error code.
Param data: [in] Data pointer.
Param len: [in] Data length.

Enums

enum bt_ams_remote_command_id

Remote Command ID values.

Values:

enumerator BT_AMS_REMOTE_COMMAND_ID_PLAY

enumerator BT_AMS_REMOTE_COMMAND_ID_PAUSE

enumerator BT_AMS_REMOTE_COMMAND_ID_TOGGLE_PLAY_PAUSE

enumerator BT_AMS_REMOTE_COMMAND_ID_NEXT_TRACK

enumerator BT_AMS_REMOTE_COMMAND_ID_PREVIOUS_TRACK

enumerator BT_AMS_REMOTE_COMMAND_ID_VOLUME_UP

enumerator BT_AMS_REMOTE_COMMAND_ID_VOLUME_DOWN

enumerator BT_AMS_REMOTE_COMMAND_ID_ADVANCE_REPEAT_MODE

enumerator BT_AMS_REMOTE_COMMAND_ID_ADVANCE_SHUFFLE_MODE

enumerator BT_AMS_REMOTE_COMMAND_ID_SKIP_FORWARD

enumerator BT_AMS_REMOTE_COMMAND_ID_SKIP_BACKWARD

enumerator BT_AMS_REMOTE_COMMAND_ID_LIKE_TRACK

enumerator BT_AMS_REMOTE_COMMAND_ID_DISLIKE_TRACK

enumerator BT_AMS_REMOTE_COMMAND_ID_BOOKMARK_TRACK

enum bt_ams_entity_id

Entity ID values.

Values:

enumerator BT_AMS_ENTITY_ID_PLAYER

enumerator BT_AMS_ENTITY_ID_QUEUE

enumerator BT_AMS_ENTITY_ID_TRACK

enum bt_ams_player_attribute_id

Player Attribute ID values.

Values:

enumerator BT_AMS_PLAYER_ATTRIBUTE_ID_NAME

enumerator BT_AMS_PLAYER_ATTRIBUTE_ID_PLAYBACK_INFO

enumerator BT_AMS_PLAYER_ATTRIBUTE_ID_VOLUME

enum bt_ams_queue_attribute_id

Queue Attribute ID values.

Values:

enumerator BT_AMS_QUEUE_ATTRIBUTE_ID_INDEX

enumerator BT_AMS_QUEUE_ATTRIBUTE_ID_COUNT

enumerator BT_AMS_QUEUE_ATTRIBUTE_ID_SHUFFLE_MODE

enumerator BT_AMS_QUEUE_ATTRIBUTE_ID_REPEAT_MODE

enum bt_ams_shuffle_mode

Shuffle Mode constants.

Values:

enumerator BT_AMS_SHUFFLE_MODE_OFF

enumerator BT_AMS_SHUFFLE_MODE_ONE

enumerator BT_AMS_SHUFFLE_MODE_ALL

enum bt_ams_repeat_mode

Repeat Mode constants.

Values:

enumerator BT_AMS_REPEAT_MODE_OFF

enumerator BT_AMS_REPEAT_MODE_ONE

enumerator BT_AMS_REPEAT_MODE_ALL

enum bt_ams_track_attribute_id

Track Attribute ID values.

Values:

enumerator BT_AMS_TRACK_ATTRIBUTE_ID_ARTIST

enumerator BT_AMS_TRACK_ATTRIBUTE_ID_ALBUM

enumerator BT_AMS_TRACK_ATTRIBUTE_ID_TITLE

enumerator BT_AMS_TRACK_ATTRIBUTE_ID_DURATION

Functions

int bt_ams_client_init(struct bt_ams_client *ams_c)

Initialize the AMS Client instance.

Parameters

ams_c – [out] AMS client instance.

Return values

0 – If the client is initialized successfully. Otherwise, a (negative) error code is returned.

int bt_ams_handles_assign(struct bt_gatt_dm *dm, struct bt_ams_client *ams_c)

Assign handles to the AMS Client instance.

Call this function when a link has been established with a peer to associate the link to this instance of the module. This makes it possible to handle several links and associate each link to a particular instance of this module.

Parameters

dm – [in] Discovery object.
ams_c – [inout] AMS client instance.

Return values