bt_hid_host_cb Struct Reference

Callbacks supplied by the HID Host application. More...

#include <hid_host.h>

Data Fields
void(*	connected )(struct bt_hid_host *hid)
	HID connection established.
void(*	disconnected )(struct bt_hid_host *hid)
	HID connection terminated.
void(*	input_report )(struct bt_hid_host *hid, struct net_buf *buf)
	Input report received on the interrupt channel.
void(*	get_report )(struct bt_hid_host *hid, uint8_t result_code, uint8_t type, struct net_buf *buf)
	GET_REPORT result.
void(*	set_report )(struct bt_hid_host *hid, uint8_t result_code)
	SET_REPORT result.
void(*	get_protocol )(struct bt_hid_host *hid, uint8_t result_code, uint8_t protocol)
	GET_PROTOCOL result.
void(*	set_protocol )(struct bt_hid_host *hid, uint8_t result_code)
	SET_PROTOCOL result.
void(*	vc_unplug )(struct bt_hid_host *hid)
	Virtual Cable Unplug received from Device.

Detailed Description

Callbacks supplied by the HID Host application.

Register via bt_hid_host_register() to receive events from connected HID Devices.

Only one control channel transaction may be outstanding at a time (HID spec v1.1.2 Section 3.2.1); further requests return -EBUSY until the response arrives. Each request has its own result callback, which reports the HANDSHAKE result code supplied by the device and is therefore only invoked when the device answers. A transaction that is never answered is treated as a lost connection per HID spec v1.1.2 Section 5.2.6: the HID association is torn down and the disconnected callback is invoked instead. Since at most one transaction is outstanding, an application that sees disconnected after issuing a request knows that request was lost.

Field Documentation

connected

void(* bt_hid_host_cb::connected) (struct bt_hid_host *hid)

HID connection established.

Called when both control and interrupt L2CAP channels are open and the HID association is ready for traffic. This is called for both outgoing (Host-initiated) and incoming (Device-initiated reconnection) connections.

Parameters

hid	HID Host instance.

disconnected

void(* bt_hid_host_cb::disconnected) (struct bt_hid_host *hid)

HID connection terminated.

Called when the HID association is fully torn down.

Parameters

hid	HID Host instance.

get_protocol

void(* bt_hid_host_cb::get_protocol) (struct bt_hid_host *hid, uint8_t result_code, uint8_t protocol)

GET_PROTOCOL result.

Called for every GET_PROTOCOL transaction, whether the device answered with a DATA message carrying the protocol mode octet or rejected the request with a HANDSHAKE (HID spec v1.1.2 Section 3.2.1.5).

Parameters

hid	HID Host instance.
result_code	BT_HID_HS_RSP_SUCCESS, or the BT_HID_HS_RSP_ERR_* code the device replied with.
protocol	Protocol mode of the device (BT_HID_PROTOCOL_BOOT_MODE or BT_HID_PROTOCOL_REPORT_MODE), undefined when result_code is not BT_HID_HS_RSP_SUCCESS.

get_report

void(* bt_hid_host_cb::get_report) (struct bt_hid_host *hid, uint8_t result_code, uint8_t type, struct net_buf *buf)

GET_REPORT result.

Called for every GET_REPORT transaction, whether the device answered with a DATA message or rejected the request with a HANDSHAKE (HID spec v1.1.2 Section 3.2.1.1), so the outcome is handled in one place.

The payload is delivered as received, starting with the Report ID when one is in use.

Parameters

hid	HID Host instance.
result_code	BT_HID_HS_RSP_SUCCESS, or the BT_HID_HS_RSP_ERR_* code the device replied with.
type	Report type (INPUT/OUTPUT/FEATURE), undefined when result_code is not BT_HID_HS_RSP_SUCCESS.
buf	Report payload (ownership retained by stack), NULL when a DATA message is not received.

input_report

void(* bt_hid_host_cb::input_report) (struct bt_hid_host *hid, struct net_buf *buf)

Input report received on the interrupt channel.

Asynchronous input report data sent by the HID Device.

The payload is delivered as received. It starts with the Report ID when the report descriptor declares Report IDs or the device is in Boot Protocol Mode, which only the application can tell.

Parameters

hid	HID Host instance.
buf	Report payload (ownership retained by stack).

set_protocol

void(* bt_hid_host_cb::set_protocol) (struct bt_hid_host *hid, uint8_t result_code)

SET_PROTOCOL result.

Called when the device answers a SET_PROTOCOL request with a HANDSHAKE, which is the only reply a SET request gets (HID spec v1.1.2 Section 3.2.1.6). The requested mode is in use only when result_code is BT_HID_HS_RSP_SUCCESS.

Parameters

hid	HID Host instance.
result_code	BT_HID_HS_RSP_SUCCESS, or the BT_HID_HS_RSP_ERR_* code the device replied with.

set_report

void(* bt_hid_host_cb::set_report) (struct bt_hid_host *hid, uint8_t result_code)

SET_REPORT result.

Called when the device answers a SET_REPORT request with a HANDSHAKE, which is the only reply a SET request gets (HID spec v1.1.2 Section 3.2.1.2).

Parameters

hid	HID Host instance.
result_code	BT_HID_HS_RSP_SUCCESS, or the BT_HID_HS_RSP_ERR_* code the device replied with.

vc_unplug

void(* bt_hid_host_cb::vc_unplug) (struct bt_hid_host *hid)

Virtual Cable Unplug received from Device.

The remote HID Device has sent a VIRTUAL_CABLE_UNPLUG control message and the stack disconnects the HID association. HID spec v1.1.2 Section 3.1.2.2.3 also requires the bonding to be destroyed; this is left to the application because bt_br_unpair() would drop the whole ACL and with it any co-located profile.

A control transaction that was still outstanding when the unplug arrived is discarded, so its result callback is never invoked: per Section 3.1.2.2.3 the recipient discards any pending control transfer. An application waiting for such a reply has to treat this callback as the outcome.

Parameters

hid	HID Host instance.

---

The documentation for this struct was generated from the following file:

• include/zephyr/bluetooth/classic/hid_host.h