GATT service discovery

Discover the GATT database of a connected peer. More...

Typedefs
typedef struct GAPLEConnection	GAPLEConnection
	LE connection state kept by the firmware (see comm/ble/gap_le_connection.h).
typedef struct GATTServiceNode	GATTServiceNode
	List node of a discovered service kept by the firmware.

Functions
enum pbl_bt_errno	pbl_bt_gatt_start_discovery_range (const GAPLEConnection *connection, const struct pbl_bt_att_handle_range *data)
	Start discovering the services of a peer.
enum pbl_bt_errno	pbl_bt_gatt_stop_discovery (GAPLEConnection *connection)
	Stop an ongoing discovery.
void	pbl_bt_gatt_handle_discovery_abandoned (void)
	Notify the stack that a discovery was abandoned.
bool	pbl_bt_cb_gatt_client_discovery_complete (GAPLEConnection *connection, enum pbl_bt_errno errno)
	Called when a discovery finished.
void	pbl_bt_cb_gatt_client_discovery_handle_indication (GAPLEConnection *connection, struct pbl_bt_gatt_service *service_discovered, enum pbl_bt_errno error)
	Called for each discovered service.

Detailed Description

Discover the GATT database of a connected peer.

Discovery is queued behind other GATT client procedures. Each primary service found within the requested handle range is reported with pbl_bt_cb_gatt_client_discovery_handle_indication(), followed by one pbl_bt_cb_gatt_client_discovery_complete(). Errors, including a failure to start, are only reported through the latter. After a successful discovery the stack also subscribes to the peer's Service Changed indications.

const struct pbl_bt_att_handle_range range = { .start = 0x0001, .end = 0xFFFF };
 
pbl_bt_gatt_start_discovery_range(connection, &range);
 
void pbl_bt_cb_gatt_client_discovery_handle_indication(GAPLEConnection *connection,
                                                       struct pbl_bt_gatt_service *service,
                                                       enum pbl_bt_errno error) {
  // Takes ownership of service, kernel_free() it when done.
}
 
bool pbl_bt_cb_gatt_client_discovery_complete(GAPLEConnection *connection,
                                              enum pbl_bt_errno errno) {
  return true;
}

Typedef Documentation

GAPLEConnection

typedef struct GAPLEConnection GAPLEConnection

LE connection state kept by the firmware (see comm/ble/gap_le_connection.h).

GATTServiceNode

typedef struct GATTServiceNode GATTServiceNode

List node of a discovered service kept by the firmware.

Function Documentation

pbl_bt_cb_gatt_client_discovery_complete()

bool pbl_bt_cb_gatt_client_discovery_complete ( GAPLEConnection *  connection, enum pbl_bt_errno  errno  )

extern

Called when a discovery finished.

Parameters

connection	The connection.
errno	PBL_BT_ERRNO_OK on success, PBL_BT_ERRNO_SERVICE_DISCOVERY_TIMEOUT, PBL_BT_ERRNO_SERVICE_DISCOVERY_DISCONNECTED, or another error.

Returns

true if the discovery is finished, false if the firmware started a retry.

pbl_bt_cb_gatt_client_discovery_handle_indication()

void pbl_bt_cb_gatt_client_discovery_handle_indication ( GAPLEConnection *  connection, struct pbl_bt_gatt_service *  service_discovered, enum pbl_bt_errno  error  )

extern

Called for each discovered service.

Parameters

connection	The connection.
service_discovered	The service, heap allocated. Ownership passes to the callee.
error	PBL_BT_ERRNO_OK, or an error converting the service.

pbl_bt_gatt_handle_discovery_abandoned()

void pbl_bt_gatt_handle_discovery_abandoned

(

void

)

Notify the stack that a discovery was abandoned.

Called by the firmware when the connection or the stack goes away in the middle of a discovery, so the stack can drop any state waiting for it to complete. Does nothing in the NimBLE backend.

pbl_bt_gatt_start_discovery_range()

enum pbl_bt_errno pbl_bt_gatt_start_discovery_range	(	const GAPLEConnection *	connection,
		const struct pbl_bt_att_handle_range *	data
	)

Start discovering the services of a peer.

Parameters

connection	The connection.
data	Handle range to discover. Services not fully inside it are skipped.

Returns

PBL_BT_ERRNO_OK. Start failures are reported through pbl_bt_cb_gatt_client_discovery_complete().

pbl_bt_gatt_stop_discovery()

enum pbl_bt_errno pbl_bt_gatt_stop_discovery

(

GAPLEConnection *

connection

)

Stop an ongoing discovery.

Blocks until the discovery has stopped. Must not be called from the NimBLE host task.

Parameters

connection

The connection.

Return values

PBL_BT_ERRNO_OK	Stopped, or no discovery was in progress.
PBL_BT_ERRNO_INVALID_STATE	connection is not connected.