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

What clients of a peer's GATT service share: finding the service, and being handed its notifications. More...

Data Structures

struct  pbl_bt_gattc_chr
 A characteristic found by pbl_bt_gattc_discover(). More...
 
struct  pbl_bt_gattc_service_cb
 What a service client reports; any may be null. More...
 
struct  pbl_bt_gattc_service
 A client of one service of one connection at a time. More...
 
struct  pbl_bt_gattc_notify_listener
 A listener of the notifications and indications of peers. More...
 

Macros

#define PBL_BT_GATTC_SERVICE_DEFINE(_name, _svc_uuid, _chr_uuids, _optional, _notifying)
 Define a service client.
 
#define PBL_BT_GATTC_NOTIFY_LISTENER_DEFINE(_name, _fn)
 Define a listener of the notifications and indications of peers.
 

Typedefs

typedef void(* pbl_bt_gattc_discover_cb_t) (uint16_t conn_handle, int status, const struct pbl_bt_gattc_chr *chrs, void *arg)
 Called when pbl_bt_gattc_discover() is done, on the host task.
 

Functions

int pbl_bt_gattc_discover (uint16_t conn_handle, const ble_uuid_t *svc_uuid, const ble_uuid_t *const *chr_uuids, uint8_t num_chrs, pbl_bt_gattc_discover_cb_t cb, void *arg)
 Find a service of the peer and characteristics of it.
 
int pbl_bt_gattc_service_start (struct pbl_bt_gattc_service *svc, uint16_t conn_handle, const struct pbl_bt_gattc_service_cb *cb)
 Look for the service on a connection.
 
int pbl_bt_gattc_service_rediscover (struct pbl_bt_gattc_service *svc)
 Look for the service again, as when the peer says its services changed.
 
void pbl_bt_gattc_service_stop (struct pbl_bt_gattc_service *svc)
 Forget the service and the connection.
 
int pbl_bt_gattc_service_subscribe (struct pbl_bt_gattc_service *svc, uint8_t chr, bool enable)
 Subscribe to the notifications of a characteristic, or unsubscribe.
 
int pbl_bt_gattc_service_write (struct pbl_bt_gattc_service *svc, uint8_t chr, const void *data, uint16_t len)
 Write the value of a characteristic.
 
int pbl_bt_gattc_service_read (struct pbl_bt_gattc_service *svc, uint8_t chr)
 Read the value of a characteristic, all of it however long.
 
bool pbl_bt_gattc_service_notify_rx (struct pbl_bt_gattc_service *svc, uint16_t conn_handle, uint16_t attr_handle, struct os_mbuf *om)
 Take a notification or indication if it is of a characteristic of the service.
 
bool pbl_bt_gattc_notify_rx (uint16_t conn_handle, uint16_t attr_handle, struct os_mbuf *om)
 Offer a notification or indication of a peer to the listeners.
 

Detailed Description

What clients of a peer's GATT service share: finding the service, and being handed its notifications.

A client finds the characteristics of the one service it is for, keeps their handles and uses them with the stack directly:

static const ble_uuid_t *const s_chrs[] = {&s_foo_uuid.u, &s_bar_uuid.u};
static void prv_found(uint16_t conn_handle, int status, const struct pbl_bt_gattc_chr *chrs,
void *arg) {
if (status == 0) {
uint16_t value = htole16(BLE_GATT_CCCD_NOTIFY);
ble_gattc_write_flat(conn_handle, chrs[0].cccd_handle, &value, sizeof(value), prv_cb, arg);
}
}
pbl_bt_gattc_discover(conn_handle, &s_svc_uuid.u, s_chrs, 2, prv_found, nullptr);
A characteristic found by pbl_bt_gattc_discover().
Definition gatt.h:41
int pbl_bt_gattc_discover(uint16_t conn_handle, const ble_uuid_t *svc_uuid, const ble_uuid_t *const *chr_uuids, uint8_t num_chrs, pbl_bt_gattc_discover_cb_t cb, void *arg)
Find a service of the peer and characteristics of it.

Data Structure Documentation

◆ pbl_bt_gattc_chr

struct pbl_bt_gattc_chr

A characteristic found by pbl_bt_gattc_discover().

Data Fields
uint16_t cccd_handle Handle of its Client Characteristic Configuration descriptor, 0 if it has none.
uint8_t properties Its properties (BLE_GATT_CHR_PROP_*).
uint16_t val_handle Handle of its value, 0 if the service does not have the characteristic.

◆ pbl_bt_gattc_service

struct pbl_bt_gattc_service

A client of one service of one connection at a time.

Define it with PBL_BT_GATTC_SERVICE_DEFINE(), and hand the notifications of the connection to pbl_bt_gattc_service_notify_rx() from a listener.

Data Fields
const ble_uuid_t *const * chr_uuids Its characteristics.
struct pbl_bt_gattc_chr * chrs What was found of them.
uint32_t notifying_chrs Which of them must have a CCCD, as a bit mask of indexes.
uint8_t num_chrs Number of characteristics.
uint32_t optional_chrs Which of them the service may lack, as a bit mask of indexes.
const ble_uuid_t * svc_uuid The service.

Macro Definition Documentation

◆ PBL_BT_GATTC_NOTIFY_LISTENER_DEFINE

#define PBL_BT_GATTC_NOTIFY_LISTENER_DEFINE (   _name,
  _fn 
)
Value:
static const struct pbl_bt_gattc_notify_listener pbl_bt_gattc_notify_##_name \
PBL_ITERABLE_SECTION(const struct pbl_bt_gattc_notify_listener, bt_gattc_ntf, \
#_name) = {.fn = (_fn)}
#define PBL_ITERABLE_SECTION(type, tag, key)
Add the object to an iterable section, a table gathered at link time from any file.
Definition section.h:124
A listener of the notifications and indications of peers.
Definition gatt.h:232
bool(* fn)(uint16_t conn_handle, uint16_t attr_handle, struct os_mbuf *om)
Take a notification or indication, on the host task.
Definition gatt.h:241

Define a listener of the notifications and indications of peers.

Listeners are offered each one in turn by pbl_bt_gattc_notify_rx(), until one takes it.

Parameters
_nameName of the listener.
_fnIts function, see struct pbl_bt_gattc_notify_listener.

◆ PBL_BT_GATTC_SERVICE_DEFINE

#define PBL_BT_GATTC_SERVICE_DEFINE (   _name,
  _svc_uuid,
  _chr_uuids,
  _optional,
  _notifying 
)
Value:
static struct pbl_bt_gattc_chr _name##_chrs[PBL_ARRAY_SIZE(_chr_uuids)]; \
static struct pbl_bt_gattc_service _name = { \
.svc_uuid = (_svc_uuid), \
.chr_uuids = (_chr_uuids), \
.optional_chrs = (_optional), \
.notifying_chrs = (_notifying), \
.num_chrs = PBL_ARRAY_SIZE(_chr_uuids), \
.chrs = _name##_chrs, \
}
const ble_uuid_t * svc_uuid
The service.
Definition gatt.h:121
const ble_uuid_t *const * chr_uuids
Its characteristics.
Definition gatt.h:123
uint32_t notifying_chrs
Which of them must have a CCCD, as a bit mask of indexes.
Definition gatt.h:127
A client of one service of one connection at a time.
Definition gatt.h:119
#define PBL_ARRAY_SIZE(array)
Get the number of elements of an array.
Definition size.h:40

Define a service client.

Parameters
_nameName of the struct pbl_bt_gattc_service.
_svc_uuidThe service, a ble_uuid_t pointer.
_chr_uuidsIts characteristics, an array of ble_uuid_t pointers.
_optionalBit mask of the characteristics the service may lack.
_notifyingBit mask of the characteristics that must have a CCCD.

Typedef Documentation

◆ pbl_bt_gattc_discover_cb_t

typedef void(* pbl_bt_gattc_discover_cb_t) (uint16_t conn_handle, int status, const struct pbl_bt_gattc_chr *chrs, void *arg)

Called when pbl_bt_gattc_discover() is done, on the host task.

Parameters
conn_handleConnection.
status0 if the service was found, BLE_HS_ENOENT if the peer does not have it, or what failed.
chrsThe characteristics, in the order they were asked for; valid during the call.
argAs passed to pbl_bt_gattc_discover().

Function Documentation

◆ pbl_bt_gattc_discover()

int pbl_bt_gattc_discover ( uint16_t  conn_handle,
const ble_uuid_t *  svc_uuid,
const ble_uuid_t *const *  chr_uuids,
uint8_t  num_chrs,
pbl_bt_gattc_discover_cb_t  cb,
void *  arg 
)

Find a service of the peer and characteristics of it.

Discoveries run one at a time, in the order asked for. May be called from any thread.

Parameters
conn_handleConnection.
svc_uuidThe service.
chr_uuidsThe characteristics; the array and the UUIDs must stay valid until cb is called.
num_chrsNumber of characteristics.
cbCalled with the outcome, exactly once if this returns 0.
argPassed to cb.
Returns
0 if queued, a BLE_HS_* code otherwise.

◆ pbl_bt_gattc_notify_rx()

bool pbl_bt_gattc_notify_rx ( uint16_t  conn_handle,
uint16_t  attr_handle,
struct os_mbuf *  om 
)

Offer a notification or indication of a peer to the listeners.

Call it for each BLE_GAP_EVENT_NOTIFY_RX of the connections whose GAP events the caller handles.

Parameters
conn_handleConnection.
attr_handleHandle of the characteristic value.
omThe value.
Returns
true if a listener took it.

◆ pbl_bt_gattc_service_notify_rx()

bool pbl_bt_gattc_service_notify_rx ( struct pbl_bt_gattc_service *  svc,
uint16_t  conn_handle,
uint16_t  attr_handle,
struct os_mbuf *  om 
)

Take a notification or indication if it is of a characteristic of the service.

Returns
true if it was, and notified was called.

◆ pbl_bt_gattc_service_read()

int pbl_bt_gattc_service_read ( struct pbl_bt_gattc_service *  svc,
uint8_t  chr 
)

Read the value of a characteristic, all of it however long.

Return values
0Asked, read follows.
-ENOTCONNThe characteristic was not found (yet).
-ENOMEMOut of memory.
-EIOThe stack refused.

◆ pbl_bt_gattc_service_rediscover()

int pbl_bt_gattc_service_rediscover ( struct pbl_bt_gattc_service *  svc)

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

What was found stays in use meanwhile. discovered is only called if the outcome differs: with 0 if the service is there now or has other handles, and its subscriptions are to be made again, or with why not if it is gone. What was asked of the service where it was is then not answered.

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

◆ pbl_bt_gattc_service_start()

int pbl_bt_gattc_service_start ( struct pbl_bt_gattc_service *  svc,
uint16_t  conn_handle,
const struct pbl_bt_gattc_service_cb *  cb 
)

Look for the service on a connection.

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

◆ pbl_bt_gattc_service_stop()

void pbl_bt_gattc_service_stop ( struct pbl_bt_gattc_service *  svc)

Forget the service and the connection.

◆ pbl_bt_gattc_service_subscribe()

int pbl_bt_gattc_service_subscribe ( struct pbl_bt_gattc_service *  svc,
uint8_t  chr,
bool  enable 
)

Subscribe to the notifications of a characteristic, or unsubscribe.

Return values
0Asked, subscribed follows.
-ENOTCONNThe characteristic, or its CCCD, was not found (yet).
-ENOMEMOut of memory.
-EIOThe stack refused.

◆ pbl_bt_gattc_service_write()

int pbl_bt_gattc_service_write ( struct pbl_bt_gattc_service *  svc,
uint8_t  chr,
const void *  data,
uint16_t  len 
)

Write the value of a characteristic.

Return values
0Written, written follows.
-ENOTCONNThe characteristic was not found (yet).
-ENOMEMOut of memory.
-EIOThe stack refused.