PebbleOS v4.47.0-505-g4bbc630fa
Loading...
Searching...
No Matches
AMS client

Client of the Apple Media Service of a connected iOS device. More...

Data Structures

struct  pbl_bt_ams_client_cb
 What a client reports; any may be null. More...
 
struct  pbl_bt_ams_client
 A client. More...
 

Macros

#define PBL_BT_AMS_CLIENT_ATTRS_MAX   8
 At most this many attributes in a registration.
 
#define PBL_BT_AMS_CLIENT_DEFINE(_name)
 Define a client.
 

Enumerations

enum  pbl_bt_ams_source { PBL_BT_AMS_SOURCE_REMOTE_COMMAND , PBL_BT_AMS_SOURCE_ENTITY_UPDATE }
 What the service notifies from. More...
 

Functions

int pbl_bt_ams_client_start (struct pbl_bt_ams_client *client, uint16_t conn_handle, const struct pbl_bt_ams_client_cb *cb)
 Look for the service on a connection.
 
int pbl_bt_ams_client_rediscover (struct pbl_bt_ams_client *client)
 Look for the service again, as when the device says its services changed.
 
void pbl_bt_ams_client_stop (struct pbl_bt_ams_client *client)
 Forget the service, the connection and the read in progress.
 
int pbl_bt_ams_client_subscribe (struct pbl_bt_ams_client *client, enum pbl_bt_ams_source source, bool enable)
 Subscribe to a source, or unsubscribe.
 
int pbl_bt_ams_client_send_command (struct pbl_bt_ams_client *client, enum pbl_bt_ams_command command)
 Send a command to the media player.
 
int pbl_bt_ams_client_register (struct pbl_bt_ams_client *client, enum pbl_bt_ams_entity entity, const uint8_t *attrs, uint8_t num_attrs)
 Register for attributes of an entity: their values are told now, and as they change.
 
int pbl_bt_ams_client_read_attr (struct pbl_bt_ams_client *client, enum pbl_bt_ams_entity entity, uint8_t attr)
 Read the whole value of an attribute, as when an update had it cut.
 
bool pbl_bt_ams_client_notify_rx (struct pbl_bt_ams_client *client, uint16_t conn_handle, uint16_t attr_handle, struct os_mbuf *om)
 Take a notification of a peer if it is of the service of the client.
 

Detailed Description

Client of the Apple Media Service of a connected iOS device.

A client serves one connection at a time: define one for each connection to serve at once. It finds the service, sends commands to the media player, registers for attributes of the player, the queue and the track and reports their values as the device updates them, and on request reads the whole of a value that was cut. The service requires an encrypted link: start the client once the link is.

static const uint8_t s_track_attrs[] = {
};
static void prv_discovered(struct pbl_bt_ams_client *client, int status) {
if (status == 0) {
}
}
static void prv_subscribed(struct pbl_bt_ams_client *client, enum pbl_bt_ams_source source,
bool enable, int status) {
if (status == 0) {
PBL_ARRAY_SIZE(s_track_attrs));
}
}
static void prv_update(struct pbl_bt_ams_client *client,
const struct pbl_bt_ams_update *update) {
if (update->entity == PBL_BT_AMS_ENTITY_TRACK &&
}
}
static const struct pbl_bt_ams_client_cb s_cb = {
.discovered = prv_discovered,
.subscribed = prv_subscribed,
.update = prv_update,
};
pbl_bt_ams_client_start(&s_client, conn_handle, &s_cb);
A client.
Definition ams.h:148
int pbl_bt_ams_client_register(struct pbl_bt_ams_client *client, enum pbl_bt_ams_entity entity, const uint8_t *attrs, uint8_t num_attrs)
Register for attributes of an entity: their values are told now, and as they change.
int pbl_bt_ams_client_send_command(struct pbl_bt_ams_client *client, enum pbl_bt_ams_command command)
Send a command to the media player.
int pbl_bt_ams_client_start(struct pbl_bt_ams_client *client, uint16_t conn_handle, const struct pbl_bt_ams_client_cb *cb)
Look for the service on a connection.
int pbl_bt_ams_client_subscribe(struct pbl_bt_ams_client *client, enum pbl_bt_ams_source source, bool enable)
Subscribe to a source, or unsubscribe.
pbl_bt_ams_source
What the service notifies from.
Definition ams.h:74
#define PBL_BT_AMS_CLIENT_DEFINE(_name)
Define a client.
Definition ams.h:165
@ PBL_BT_AMS_SOURCE_ENTITY_UPDATE
Entity Update: the values of the attributes registered for.
Definition ams.h:78
uint8_t entity
An enum pbl_bt_ams_entity.
Definition ams.h:147
uint8_t attr
The attribute of the entity.
Definition ams.h:149
The value of an attribute, as the Entity Update tells it.
Definition ams.h:145
@ PBL_BT_AMS_TRACK_ATTR_ARTIST
Definition ams.h:118
@ PBL_BT_AMS_TRACK_ATTR_TITLE
Definition ams.h:120
@ PBL_BT_AMS_ENTITY_TRACK
The track: its attributes are an enum pbl_bt_ams_track_attr.
Definition ams.h:63
@ PBL_BT_AMS_COMMAND_VOLUME_UP
Definition ams.h:45
#define PBL_ARRAY_SIZE(array)
Get the number of elements of an array.
Definition size.h:40
What a client reports; any may be null.
Definition ams.h:84
void(* discovered)(struct pbl_bt_ams_client *client, int status)
The search for the service ended.
Definition ams.h:90

Commands and registrations are answered in the order they were made. A client reads one value at a time.

A status is 0, the ATT error code the service answered with (positive, e.g. PBL_BT_AMS_ERR_INVALID_STATE), or a negative errno. Callbacks are called on the host task, and none after pbl_bt_ams_client_stop() returns but one that was already running.


Data Structure Documentation

◆ pbl_bt_ams_client

struct pbl_bt_ams_client

A client.

Define it with PBL_BT_AMS_CLIENT_DEFINE().

Macro Definition Documentation

◆ PBL_BT_AMS_CLIENT_ATTRS_MAX

#define PBL_BT_AMS_CLIENT_ATTRS_MAX   8

At most this many attributes in a registration.

◆ PBL_BT_AMS_CLIENT_DEFINE

#define PBL_BT_AMS_CLIENT_DEFINE (   _name)
Value:
static struct pbl_bt_ams_client _name; \
static bool _name##_notify_rx(uint16_t conn_handle, uint16_t attr_handle, struct os_mbuf *om) { \
return pbl_bt_ams_client_notify_rx(&_name, conn_handle, attr_handle, om); \
} \
PBL_BT_GATTC_NOTIFY_LISTENER_DEFINE(_name, _name##_notify_rx)
bool pbl_bt_ams_client_notify_rx(struct pbl_bt_ams_client *client, uint16_t conn_handle, uint16_t attr_handle, struct os_mbuf *om)
Take a notification of a peer if it is of the service of the client.

Define a client.

Parameters
_nameName of the struct pbl_bt_ams_client.

Enumeration Type Documentation

◆ pbl_bt_ams_source

What the service notifies from.

Enumerator
PBL_BT_AMS_SOURCE_REMOTE_COMMAND 

Remote Command: the commands the media player takes.

PBL_BT_AMS_SOURCE_ENTITY_UPDATE 

Entity Update: the values of the attributes registered for.

Function Documentation

◆ pbl_bt_ams_client_notify_rx()

bool pbl_bt_ams_client_notify_rx ( struct pbl_bt_ams_client *  client,
uint16_t  conn_handle,
uint16_t  attr_handle,
struct os_mbuf *  om 
)

Take a notification of a peer if it is of the service of the client.

PBL_BT_AMS_CLIENT_DEFINE() has it called.

Returns
true if it was.

◆ pbl_bt_ams_client_read_attr()

int pbl_bt_ams_client_read_attr ( struct pbl_bt_ams_client *  client,
enum pbl_bt_ams_entity  entity,
uint8_t  attr 
)

Read the whole value of an attribute, as when an update had it cut.

Parameters
clientClient.
entityThe entity.
attrIts attribute.
Return values
0Asked, attr_read follows.
-EBUSYA read is in progress.
-ENOTCONNThe service was not found (yet).
-ENOMEMOut of memory.
-EIOThe stack refused.

◆ pbl_bt_ams_client_rediscover()

int pbl_bt_ams_client_rediscover ( struct pbl_bt_ams_client *  client)

Look for the service again, as when the device says its services changed.

Nothing changes if the service is still where it was. Otherwise the read in progress is forgotten and discovered is called: with 0 if the service is there now, or elsewhere, and it is to be subscribed to and registered with again, or with why not if it is gone.

Parameters
clientClient.
Return values
0Looking for it.
-ENOTCONNNot started.
-ENOMEMOut of memory.

◆ pbl_bt_ams_client_register()

int pbl_bt_ams_client_register ( struct pbl_bt_ams_client *  client,
enum pbl_bt_ams_entity  entity,
const uint8_t *  attrs,
uint8_t  num_attrs 
)

Register for attributes of an entity: their values are told now, and as they change.

Subscribe to the Entity Update first. A registration replaces the one made before for the entity.

Parameters
clientClient.
entityThe entity.
attrsIts attributes.
num_attrsNumber of attributes, at most PBL_BT_AMS_CLIENT_ATTRS_MAX.
Return values
0Asked, registered follows, and then update for each.
-EINVALToo many attributes.
-ENOTCONNThe service was not found (yet).
-ENOMEMOut of memory.
-EIOThe stack refused.

◆ pbl_bt_ams_client_send_command()

int pbl_bt_ams_client_send_command ( struct pbl_bt_ams_client *  client,
enum pbl_bt_ams_command  command 
)

Send a command to the media player.

Parameters
clientClient.
commandThe command.
Return values
0Sent, command_sent follows.
-ENOTCONNThe service was not found (yet).
-ENOMEMOut of memory.
-EIOThe stack refused.

◆ pbl_bt_ams_client_start()

int pbl_bt_ams_client_start ( struct pbl_bt_ams_client *  client,
uint16_t  conn_handle,
const struct pbl_bt_ams_client_cb *  cb 
)

Look for the service on a connection.

Parameters
clientClient.
conn_handleConnection.
cbCallbacks, which must stay valid.
Return values
0Looking for it, discovered follows.
-EALREADYStarted already.
-ENOMEMOut of memory.

◆ pbl_bt_ams_client_stop()

void pbl_bt_ams_client_stop ( struct pbl_bt_ams_client *  client)

Forget the service, the connection and the read in progress.

◆ pbl_bt_ams_client_subscribe()

int pbl_bt_ams_client_subscribe ( struct pbl_bt_ams_client *  client,
enum pbl_bt_ams_source  source,
bool  enable 
)

Subscribe to a source, or unsubscribe.

Parameters
clientClient.
sourceThe source.
enabletrue to subscribe.
Return values
0Asked, subscribed follows.
-ENOTCONNThe service was not found (yet).
-ENOMEMOut of memory.
-EIOThe stack refused.