Apple Media Service (AMS) Client

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:

0 – If the operation is successful. Otherwise, a (negative) error code is returned.

int bt_ams_subscribe_remote_command(struct bt_ams_client *ams_c, bt_ams_remote_command_notify_cb func)

Subscribe to the Remote Command notification.

Parameters:
  • ams_c[in] AMS client instance.

  • func[in] Notification callback function handler.

Return values:

0 – If the operation is successful. Otherwise, a (negative) error code is returned.

int bt_ams_unsubscribe_remote_command(struct bt_ams_client *ams_c)

Unsubscribe from the Remote Command notification.

Parameters:
  • ams_c[in] AMS client instance.

Return values:

0 – If the operation is successful. Otherwise, a (negative) error code is returned.

int bt_ams_subscribe_entity_update(struct bt_ams_client *ams_c, bt_ams_entity_update_notify_cb func)

Subscribe to the Entity Update notification.

Parameters:
  • ams_c[in] AMS client instance.

  • func[in] Notification callback function handler.

Return values:

0 – If the operation is successful. Otherwise, a (negative) error code is returned.

int bt_ams_unsubscribe_entity_update(struct bt_ams_client *ams_c)

Unsubscribe from the Entity Update notification.

Parameters:
  • ams_c[in] AMS client instance.

Return values:

0 – If the operation is successful. Otherwise, a (negative) error code is returned.

int bt_ams_write_remote_command(struct bt_ams_client *ams_c, enum bt_ams_remote_command_id command, bt_ams_write_cb func)

Write data to the Remote Command characteristic.

Parameters:
  • ams_c[in] AMS client instance.

  • command[in] Remote Command ID.

  • func[in] Write callback function handler.

Return values:

0 – If the operation is successful. Otherwise, a (negative) error code is returned.

int bt_ams_write_entity_update(struct bt_ams_client *ams_c, const struct bt_ams_entity_attribute_list *ent_attr_list, bt_ams_write_cb func)

Write data to the Entity Update characteristic.

Parameters:
  • ams_c[in] AMS client instance.

  • ent_attr_list[in] Entity Attribute list.

  • func[in] Write callback function handler.

Return values:

0 – If the operation is successful. Otherwise, a (negative) error code is returned.

int bt_ams_write_entity_attribute(struct bt_ams_client *ams_c, const struct bt_ams_entity_attribute *ent_attr, bt_ams_write_cb func)

Write data to the Entity Attribute characteristic.

Parameters:
  • ams_c[in] AMS client instance.

  • ent_attr[in] Entity Attribute pair.

  • func[in] Write callback function handler.

Return values:

0 – If the operation is successful. Otherwise, a (negative) error code is returned.

int bt_ams_read_entity_attribute(struct bt_ams_client *ams_c, bt_ams_read_cb func)

Read data from the Entity Attribute characteristic.

Parameters:
  • ams_c[in] AMS client instance.

  • func[in] Read callback function handler.

Return values:

0 – If the operation is successful. Otherwise, a (negative) error code is returned.

struct bt_ams_entity_attribute
#include <ams_client.h>

Structure for Entity Attribute pair.

Public Members

enum bt_ams_entity_id entity

Entity ID.

union bt_ams_entity_attribute.[anonymous] attribute

Attribute ID.

struct bt_ams_entity_attribute_list
#include <ams_client.h>

Structure for Entity Attribute pair list.

Public Members

enum bt_ams_entity_id entity

Entity ID.

union bt_ams_entity_attribute_list.[anonymous] attribute

Attribute ID pointer.

size_t attribute_count

Attribute ID count.

struct bt_ams_entity_update_notif
#include <ams_client.h>

Structure for Entity Update notification.

Public Members

struct bt_ams_entity_attribute ent_attr

Entity Attribute pair.

uint8_t flags

Flags bitmask.

const uint8_t *data

Value data pointer.

size_t len

Value data size.

struct bt_ams_client
#include <ams_client.h>

AMS client structure, which contains various status information for the client.

Public Members

struct bt_conn *conn

Connection object.

atomic_t state

Internal state.

struct bt_ams_entity_attribute_characteristic
#include <ams_client.h>

Entity Attribute Characteristic.

Public Members

uint16_t handle

Handle.

struct bt_gatt_write_params write_params

GATT write parameters.

bt_ams_write_cb write_cb

Callback function for the GATT write.

uint8_t data[2]

Data buffer for the GATT write.

struct bt_gatt_read_params read_params

GATT read parameters.

bt_ams_read_cb read_cb

Callback function for the GATT read.

struct bt_ams_entity_update_characteristic
#include <ams_client.h>

Entity Update Characteristic.

Public Members

uint16_t handle

Handle.

uint16_t handle_ccc

Handle of the CCCD.

struct bt_gatt_subscribe_params notif_params

GATT subscribe parameters.

bt_ams_entity_update_notify_cb notify_cb

Callback function for the GATT notification.

struct bt_gatt_write_params write_params

GATT write parameters.

bt_ams_write_cb write_cb

Callback function for the GATT write.

uint8_t data[4 + 1]

Data buffer for the GATT write.

struct bt_ams_remote_command_characteristic
#include <ams_client.h>

Remote Command Characteristic.

Public Members

uint16_t handle

Handle.

uint16_t handle_ccc

Handle of the CCCD.

struct bt_gatt_subscribe_params notif_params

GATT subscribe parameters.

bt_ams_remote_command_notify_cb notify_cb

Callback function for the GATT notification.

struct bt_gatt_write_params write_params

GATT write parameters.

bt_ams_write_cb write_cb

Callback function for the GATT write.

uint8_t data

Data buffer for the GATT write.