bt_hid_device_cb Struct Reference

Callbacks supplied by the HID application. More...

#include <hid_device.h>

Data Fields
void(*	connected )(struct bt_hid_device *hid)
	connected callback to application
void(*	disconnected )(struct bt_hid_device *hid)
	disconnected callback to application
int(*	set_report )(struct bt_hid_device *hid, uint8_t type, struct net_buf *buf)
	Set_Report request callback.
int(*	get_report )(struct bt_hid_device *hid, uint8_t type, bool size_present, struct net_buf *req, struct net_buf *rsp)
	Get_Report request callback.
int(*	set_protocol )(struct bt_hid_device *hid, uint8_t protocol)
	Set_Protocol request callback.
void(*	output_report )(struct bt_hid_device *hid, struct net_buf *buf)
	Output report callback.
void(*	vc_unplug )(struct bt_hid_device *hid)
	Virtual Cable Unplug notification callback.
void(*	suspend )(struct bt_hid_device *hid, bool suspended)
	Suspend/Exit-Suspend notification callback.

Detailed Description

Callbacks supplied by the HID application.

Applications should register one instance of this callback table via bt_hid_device_register() to receive events and requests from the HID host. Only the callbacks the application needs must be provided; unimplemented callbacks should be set to NULL.

Field Documentation

connected

void(* bt_hid_device_cb::connected) (struct bt_hid_device *hid)

connected callback to application

If this callback is provided it will be called whenever the HID association completes. Both control and interrupt channels are established and the device is ready for HID traffic.

Parameters

hid	HID device object.

disconnected

void(* bt_hid_device_cb::disconnected) (struct bt_hid_device *hid)

disconnected callback to application

If this callback is provided it will be called whenever the HID association gets disconnected, including rejected or cancelled connections and errors during setup. The HID device object remains valid until this callback returns.

Parameters

hid	HID device object.

get_report

int(* bt_hid_device_cb::get_report) (struct bt_hid_device *hid, uint8_t type, bool size_present, struct net_buf *req, struct net_buf *rsp)

Get_Report request callback.

Called synchronously when the host sends a GET_REPORT request. This callback is mandatory (GET_REPORT must be supported per HID spec v1.1.2) and must be provided at registration.

The application responds from within the callback by appending the report payload to rsp (including the Report ID byte if the report descriptor declares Report IDs) and returning 0. The stack then prepends the HIDP DATA header and sends the response.

If no data is available yet, return -EAGAIN; the stack replies with a NOT_READY handshake and the host may retry (HID spec v1.1.2 Section 3.2.1.1). Any other negative errno triggers the matching handshake error response.

req contains the remaining GET_REPORT parameters after the HIDP header: an optional Report ID (present per the report descriptor) followed, when size_present is true, by a 2-byte little-endian BufferSize (the maximum response length the host expects). When size_present is false no BufferSize is present.

Parameters

hid	HID device object.
type	Report type (see BT_HID_REPORT_TYPE_*).
size_present	true if the request's Size bit is set, meaning a 2-byte BufferSize follows the optional Report ID in req.
req	Remaining request parameters (ownership retained by stack).
rsp	Response buffer to fill with the report payload (ownership retained by stack; sent by the stack on a 0 return).

Returns

0 if rsp was filled with the response, -EAGAIN to reply with NOT_READY, or another negative errno for a handshake error.

output_report

void(* bt_hid_device_cb::output_report) (struct bt_hid_device *hid, struct net_buf *buf)

Output report callback.

This callback provides output report data received on the interrupt channel from the HID host. The buffer contains the raw report payload including Report ID if declared in the descriptor.

Parameters

hid	HID device object.
buf	Report payload buffer (ownership retained by stack).

set_protocol

int(* bt_hid_device_cb::set_protocol) (struct bt_hid_device *hid, uint8_t protocol)

Set_Protocol request callback.

Called when the host sends a SET_PROTOCOL request. The application should return 0 if the protocol mode is supported, or a negative errno if it is not. The driver updates the internal protocol mode flag and sends the appropriate HANDSHAKE response based on the return value.

Parameters

hid	HID device object.
protocol	Requested protocol mode (BT_HID_PROTOCOL_BOOT_MODE or BT_HID_PROTOCOL_REPORT_MODE).

Returns

0 if the protocol mode is accepted, negative errno otherwise.

set_report

int(* bt_hid_device_cb::set_report) (struct bt_hid_device *hid, uint8_t type, struct net_buf *buf)

Set_Report request callback.

This callback provides report data sent by the HID host. This callback is mandatory (SET_REPORT must be supported per HID spec v1.1.2) and must be provided at registration.

The buffer contains the raw Report Data Payload as received, including the Report ID byte if declared in the descriptor. Return 0 to accept the report. Return a negative errno to trigger a corresponding handshake error response.

Parameters

hid	HID device object.
type	Report type (see BT_HID_REPORT_TYPE_*).
buf	Report payload buffer (ownership retained by stack).

Returns

0 on success or a negative errno on failure.

suspend

void(* bt_hid_device_cb::suspend) (struct bt_hid_device *hid, bool suspended)

Suspend/Exit-Suspend notification callback.

SUSPEND and EXIT_SUSPEND are unidirectional HID_CONTROL messages owned by the HID host. This callback simply relays each such message to the application as it is received; the device does not maintain any suspend state machine of its own. Per the HID profile, a suspended device that detects local user activity wakes the host by reconnecting, after which the host (optionally) issues EXIT_SUSPEND. Note EXIT_SUSPEND is not mandatory, so the application must not rely on it to leave the suspended state.

Because the messages are relayed verbatim, the callback may fire on every SUSPEND/EXIT_SUSPEND the host sends, including duplicates. If the application needs idempotent or per-peer suspend behaviour across reconnect (e.g. HID DRE/BV-09-C), it tracks that itself, keyed on the peer identity it obtains from the ACL connection.

Parameters

hid	HID device object.
suspended	true if entering suspend, false if exiting.

vc_unplug

void(* bt_hid_device_cb::vc_unplug) (struct bt_hid_device *hid)

Virtual Cable Unplug notification callback.

Invoked when the HID host sends a VIRTUAL_CABLE_UNPLUG HID_CONTROL message. Per HID spec v1.1.2 Section 3.1.2.2.3, the recipient shall destroy all bonding and Virtual Cable information stored for the peer.

The stack tears down the INTR and CTRL channels on the application's behalf, but does not clear bonding: doing so requires dropping the link key (and conditionally the ACL), which may affect other profiles sharing the same ACL. The application is therefore responsible for clearing the bonding information when appropriate, for example:

struct bt_conn *conn = bt_hid_device_get_conn(hid);
 
if (conn != NULL) {
        bt_br_unpair(bt_conn_get_dst_br(conn));
        bt_conn_unref(conn);
}

Parameters

hid	HID device object.

---

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

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