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

Client of the Apple Notification Center Service of a connected iOS device. More...

Data Structures

struct  pbl_bt_ancs_attr_req
 An attribute to ask for. More...
 
struct  pbl_bt_ancs_client_cb
 What a client reports; any may be null. More...
 
struct  pbl_bt_ancs_client
 A client. More...
 

Macros

#define PBL_BT_ANCS_CLIENT_ATTRS_MAX   8
 At most this many attributes in a request.
 
#define PBL_BT_ANCS_CLIENT_DEFINE(_name, _buf_size)
 Define a client.
 

Enumerations

enum  pbl_bt_ancs_source { PBL_BT_ANCS_SOURCE_NOTIFICATION , PBL_BT_ANCS_SOURCE_DATA }
 What the service notifies from. More...
 

Functions

int pbl_bt_ancs_client_start (struct pbl_bt_ancs_client *client, uint16_t conn_handle, const struct pbl_bt_ancs_client_cb *cb)
 Look for the service on a connection.
 
int pbl_bt_ancs_client_rediscover (struct pbl_bt_ancs_client *client)
 Look for the service again, as when the device says its services changed.
 
void pbl_bt_ancs_client_stop (struct pbl_bt_ancs_client *client)
 Forget the service, the connection and the request in progress.
 
int pbl_bt_ancs_client_subscribe (struct pbl_bt_ancs_client *client, enum pbl_bt_ancs_source source, bool enable)
 Subscribe to a source, or unsubscribe.
 
int pbl_bt_ancs_client_get_notif_attrs (struct pbl_bt_ancs_client *client, uint32_t uid, const struct pbl_bt_ancs_attr_req *attrs, uint8_t num_attrs)
 Get attributes of a notification.
 
int pbl_bt_ancs_client_get_app_attrs (struct pbl_bt_ancs_client *client, const void *app_id, size_t app_id_len, const struct pbl_bt_ancs_attr_req *attrs, uint8_t num_attrs)
 Get attributes of an app.
 
int pbl_bt_ancs_client_perform_action (struct pbl_bt_ancs_client *client, uint32_t uid, enum pbl_bt_ancs_action action)
 Perform an action on a notification.
 
void pbl_bt_ancs_client_cancel (struct pbl_bt_ancs_client *client)
 Give up on the request in progress, if any: its outcome is not reported.
 
bool pbl_bt_ancs_client_notify_rx (struct pbl_bt_ancs_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 Notification Center 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, subscribes to its sources, reports the notifications the device adds, modifies and removes, and on request gets their attributes and those of their apps, and performs their actions. The service requires an encrypted link: start the client once the link is.

static const struct pbl_bt_ancs_attr_req s_attrs[] = {
{.id = PBL_BT_ANCS_NOTIF_ATTR_TITLE, .max_len = 32},
{.id = PBL_BT_ANCS_NOTIF_ATTR_MESSAGE, .max_len = 96},
};
static void prv_discovered(struct pbl_bt_ancs_client *client, int status) {
if (status == 0) {
}
}
static void prv_notification(struct pbl_bt_ancs_client *client,
const struct pbl_bt_ancs_notif *notif) {
if (notif->event == PBL_BT_ANCS_EVENT_ADDED) {
pbl_bt_ancs_client_get_notif_attrs(client, notif->uid, s_attrs, PBL_ARRAY_SIZE(s_attrs));
}
}
static const struct pbl_bt_ancs_client_cb s_cb = {
.discovered = prv_discovered,
.notification = prv_notification,
.notif_attrs = prv_notif_attrs,
};
pbl_bt_ancs_client_start(&s_client, conn_handle, &s_cb);
uint8_t id
Which one: an enum pbl_bt_ancs_notif_attr or an enum pbl_bt_ancs_app_attr.
Definition ancs.h:77
A client.
Definition ancs.h:151
An attribute to ask for.
Definition ancs.h:75
int pbl_bt_ancs_client_get_notif_attrs(struct pbl_bt_ancs_client *client, uint32_t uid, const struct pbl_bt_ancs_attr_req *attrs, uint8_t num_attrs)
Get attributes of a notification.
#define PBL_BT_ANCS_CLIENT_DEFINE(_name, _buf_size)
Define a client.
Definition ancs.h:178
int pbl_bt_ancs_client_start(struct pbl_bt_ancs_client *client, uint16_t conn_handle, const struct pbl_bt_ancs_client_cb *cb)
Look for the service on a connection.
int pbl_bt_ancs_client_subscribe(struct pbl_bt_ancs_client *client, enum pbl_bt_ancs_source source, bool enable)
Subscribe to a source, or unsubscribe.
@ PBL_BT_ANCS_SOURCE_DATA
Data Source: the attributes asked for.
Definition ancs.h:71
@ PBL_BT_ANCS_SOURCE_NOTIFICATION
Notification Source: notifications added, modified and removed.
Definition ancs.h:69
uint32_t uid
Identifies the notification for as long as the device is connected.
Definition ancs.h:117
uint8_t event
What happened to it, an enum pbl_bt_ancs_event.
Definition ancs.h:119
A notification of the device, as its Notification Source tells it.
Definition ancs.h:115
@ PBL_BT_ANCS_NOTIF_ATTR_TITLE
Asked for with a maximum length.
Definition ancs.h:80
@ PBL_BT_ANCS_NOTIF_ATTR_MESSAGE
Asked for with a maximum length.
Definition ancs.h:84
@ PBL_BT_ANCS_EVENT_ADDED
Definition ancs.h:41
#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 ancs.h:93
void(* discovered)(struct pbl_bt_ancs_client *client, int status)
The search for the service ended.
Definition ancs.h:99

A client runs one request at a time: getting attributes or performing an action. The outcome of each is reported once, unless the request is cancelled or the client stopped.

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


Data Structure Documentation

◆ pbl_bt_ancs_attr_req

struct pbl_bt_ancs_attr_req

An attribute to ask for.

Data Fields
uint8_t id Which one: an enum pbl_bt_ancs_notif_attr or an enum pbl_bt_ancs_app_attr.
uint16_t max_len Longest value accepted, 0 for any.

The service is told to cut the title, the subtitle and the message of a notification to it, which need one.

bool optional Whether the response may lack it, as that of a device that does not know the attribute.

A response ends once it has the attributes that are not optional.

◆ pbl_bt_ancs_client

struct pbl_bt_ancs_client

A client.

Define it with PBL_BT_ANCS_CLIENT_DEFINE().

Macro Definition Documentation

◆ PBL_BT_ANCS_CLIENT_ATTRS_MAX

#define PBL_BT_ANCS_CLIENT_ATTRS_MAX   8

At most this many attributes in a request.

◆ PBL_BT_ANCS_CLIENT_DEFINE

#define PBL_BT_ANCS_CLIENT_DEFINE (   _name,
  _buf_size 
)
Value:
static uint8_t _name##_buf[_buf_size]; \
static struct pbl_bt_ancs_client _name = { \
.buf = _name##_buf, \
.buf_size = sizeof(_name##_buf), \
}; \
static bool _name##_notify_rx(uint16_t conn_handle, uint16_t attr_handle, struct os_mbuf *om) { \
return pbl_bt_ancs_client_notify_rx(&_name, conn_handle, attr_handle, om); \
} \
PBL_BT_GATTC_NOTIFY_LISTENER_DEFINE(_name, _name##_notify_rx)
bool pbl_bt_ancs_client_notify_rx(struct pbl_bt_ancs_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_ancs_client.
_buf_sizeSize of the buffer responses are gathered in: the longest one expected. The response to pbl_bt_ancs_client_get_notif_attrs() takes 5 bytes, and that to pbl_bt_ancs_client_get_app_attrs() the app identifier and 2 bytes; each attribute then takes 3 bytes and its value.

Enumeration Type Documentation

◆ pbl_bt_ancs_source

What the service notifies from.

Enumerator
PBL_BT_ANCS_SOURCE_NOTIFICATION 

Notification Source: notifications added, modified and removed.

PBL_BT_ANCS_SOURCE_DATA 

Data Source: the attributes asked for.

Function Documentation

◆ pbl_bt_ancs_client_cancel()

void pbl_bt_ancs_client_cancel ( struct pbl_bt_ancs_client *  client)

Give up on the request in progress, if any: its outcome is not reported.

Parameters
clientClient.

◆ pbl_bt_ancs_client_get_app_attrs()

int pbl_bt_ancs_client_get_app_attrs ( struct pbl_bt_ancs_client *  client,
const void *  app_id,
size_t  app_id_len,
const struct pbl_bt_ancs_attr_req *  attrs,
uint8_t  num_attrs 
)

Get attributes of an app.

Parameters
clientClient.
app_idIdentifier of the app, as the app identifier of a notification gives it.
app_id_lenIts length.
attrsThe attributes, each an enum pbl_bt_ancs_app_attr.
num_attrsNumber of attributes, at least one and at most PBL_BT_ANCS_CLIENT_ATTRS_MAX.
Return values
0Asked, app_attrs follows.
-EINVALNo attribute, or too many.
-EBUSYA request is in progress.
-ENOTCONNThe service was not found (yet).
-ENOMEMOut of memory.
-EIOThe stack refused.

◆ pbl_bt_ancs_client_get_notif_attrs()

int pbl_bt_ancs_client_get_notif_attrs ( struct pbl_bt_ancs_client *  client,
uint32_t  uid,
const struct pbl_bt_ancs_attr_req *  attrs,
uint8_t  num_attrs 
)

Get attributes of a notification.

With no attributes, the request ends when the service answers it: with PBL_BT_ANCS_ERR_INVALID_PARAMETER if the notification does not exist.

Parameters
clientClient.
uidThe notification.
attrsThe attributes, each an enum pbl_bt_ancs_notif_attr.
num_attrsNumber of attributes, at most PBL_BT_ANCS_CLIENT_ATTRS_MAX.
Return values
0Asked, notif_attrs follows.
-EINVALToo many attributes.
-EBUSYA request is in progress.
-ENOTCONNThe service was not found (yet).
-ENOMEMOut of memory.
-EIOThe stack refused.

◆ pbl_bt_ancs_client_notify_rx()

bool pbl_bt_ancs_client_notify_rx ( struct pbl_bt_ancs_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_ANCS_CLIENT_DEFINE() has it called.

Returns
true if it was.

◆ pbl_bt_ancs_client_perform_action()

int pbl_bt_ancs_client_perform_action ( struct pbl_bt_ancs_client *  client,
uint32_t  uid,
enum pbl_bt_ancs_action  action 
)

Perform an action on a notification.

Parameters
clientClient.
uidThe notification.
actionThe action.
Return values
0Asked, action_performed follows.
-EBUSYA request is in progress.
-ENOTCONNThe service was not found (yet).
-ENOMEMOut of memory.
-EIOThe stack refused.

◆ pbl_bt_ancs_client_rediscover()

int pbl_bt_ancs_client_rediscover ( struct pbl_bt_ancs_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 request in progress is forgotten and discovered is called: with 0 if the service is there now, or elsewhere, and its sources are to be subscribed to again, or with why not if it is gone.

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

◆ pbl_bt_ancs_client_start()

int pbl_bt_ancs_client_start ( struct pbl_bt_ancs_client *  client,
uint16_t  conn_handle,
const struct pbl_bt_ancs_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_ancs_client_stop()

void pbl_bt_ancs_client_stop ( struct pbl_bt_ancs_client *  client)

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

◆ pbl_bt_ancs_client_subscribe()

int pbl_bt_ancs_client_subscribe ( struct pbl_bt_ancs_client *  client,
enum pbl_bt_ancs_source  source,
bool  enable 
)

Subscribe to a source, or unsubscribe.

Subscribe to the Data Source first, so that no response is missed.

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