What clients of a peer's GATT service share: finding the service, and being handed its notifications.
More...
|
| 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.
|
| |
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);
}
}
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.
◆ 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. |
◆ PBL_BT_GATTC_NOTIFY_LISTENER_DEFINE
| #define PBL_BT_GATTC_NOTIFY_LISTENER_DEFINE |
( |
|
_name, |
|
|
|
_fn |
|
) |
| |
Value:
#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
-
◆ PBL_BT_GATTC_SERVICE_DEFINE
| #define PBL_BT_GATTC_SERVICE_DEFINE |
( |
|
_name, |
|
|
|
_svc_uuid, |
|
|
|
_chr_uuids, |
|
|
|
_optional, |
|
|
|
_notifying |
|
) |
| |
Value:
.optional_chrs = (_optional), \
.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
-
| _name | Name of the struct pbl_bt_gattc_service. |
| _svc_uuid | The service, a ble_uuid_t pointer. |
| _chr_uuids | Its characteristics, an array of ble_uuid_t pointers. |
| _optional | Bit mask of the characteristics the service may lack. |
| _notifying | Bit mask of the characteristics that must have a CCCD. |
◆ 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_handle | Connection. |
| status | 0 if the service was found, BLE_HS_ENOENT if the peer does not have it, or what failed. |
| chrs | The characteristics, in the order they were asked for; valid during the call. |
| arg | As passed to pbl_bt_gattc_discover(). |
◆ 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_handle | Connection. |
| svc_uuid | The service. |
| chr_uuids | The characteristics; the array and the UUIDs must stay valid until cb is called. |
| num_chrs | Number of characteristics. |
| cb | Called with the outcome, exactly once if this returns 0. |
| arg | Passed 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_handle | Connection. |
| attr_handle | Handle of the characteristic value. |
| om | The 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()
Read the value of a characteristic, all of it however long.
- Return values
-
| 0 | Asked, read follows. |
| -ENOTCONN | The characteristic was not found (yet). |
| -ENOMEM | Out of memory. |
| -EIO | The stack refused. |
◆ pbl_bt_gattc_service_rediscover()
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
-
- Return values
-
| 0 | Looking for it. |
| -ENOTCONN | Not started. |
| -ENOMEM | Out of memory. |
◆ pbl_bt_gattc_service_start()
Look for the service on a connection.
- Parameters
-
| svc | Service client. |
| conn_handle | Connection. |
| cb | Callbacks, which must stay valid. |
- Return values
-
| 0 | Looking for it, discovered follows. |
| -EALREADY | Started already. |
| -ENOMEM | Out of memory. |
◆ pbl_bt_gattc_service_stop()
Forget the service and the connection.
◆ pbl_bt_gattc_service_subscribe()
Subscribe to the notifications of a characteristic, or unsubscribe.
- Return values
-
| 0 | Asked, subscribed follows. |
| -ENOTCONN | The characteristic, or its CCCD, was not found (yet). |
| -ENOMEM | Out of memory. |
| -EIO | The 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
-
| 0 | Written, written follows. |
| -ENOTCONN | The characteristic was not found (yet). |
| -ENOMEM | Out of memory. |
| -EIO | The stack refused. |