HID Service Client - HIDS Host API
#include "src/ble/gatt-service/hids_host.h"
hids_host_init
void hids_host_init(uint8_t * hid_descriptor_storage, uint16_t hid_descriptor_storage_len);
Initialize HID Service Host. The HID Descriptor storage is shared between all connections.
Parameters
- hid_descriptor_storage
- hid_descriptor_storage_len
hids_host_connect
uint8_t hids_host_connect(hci_con_handle_t con_handle, btstack_packet_handler_t packet_handler, hid_protocol_mode_t protocol_mode, uint16_t * hids_cid);
Connect to HID Services of remote device. Event GATTSERVICE_SUBEVENT_HID_SERVICE_CONNECTED will be emitted after all remote HID services and characteristics are found, and notifications for all input reports are enabled. Status code can be ERROR_CODE_SUCCES if at least one HID service is found, otherwise either ATT errors or ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if no service or report map or report are found. It also contains the number of individual HIDS Services.
Connection state is stored in hids_host_t objects provided via memory pool Max number of connections is limited by MAX_NR_HIDS_HOSTS unless HAVE_MALLOC is used
Parameters
- con_handle
- packet_handler
- protocol_mode: see hid_protocol_mode_t in btstack_hid.h
- hids_cid: (out) to use for other functions
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_COMMAND_DISALLOWED if there is already a client associated with con_handle, or BTSTACK_MEMORY_ALLOC_FAILED.
hids_host_send_write_report
uint8_t hids_host_send_write_report(uint16_t hids_cid, uint8_t report_id, hid_report_type_t report_type, const uint8_t * report, uint8_t report_len);
Send HID report. Event GATTSERVICE_SUBEVENT_HID_REPORT_WRITTEN is emitted.
Parameters
- hids_cid
- report_id
- report_type
- report
- report_len
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED if client is in wrong state, ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if no report with given type and ID is found, or ERROR_CODE_PARAMETER_OUT_OF_MANDATORY_RANGE if report length exceeds MTU.
hids_host_send_get_report
uint8_t hids_host_send_get_report(uint16_t hids_cid, uint8_t report_id, hid_report_type_t report_type);
Get HID report. Event GATTSERVICE_SUBEVENT_HID_REPORT is emitted.
Parameters
- hids_cid
- report_id
- report_type
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED if client is in wrong state, ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if no report with given type and ID is found, or ERROR_CODE_PARAMETER_OUT_OF_MANDATORY_RANGE if report length exceeds MTU.
hids_host_get_hid_information
uint8_t hids_host_get_hid_information(uint16_t hids_cid, uint8_t service_index);
Get HID Information. Event GATTSERVICE_SUBEVENT_HID_INFORMATION is emitted.
Parameters
- hids_cid
- service_index
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED if client is in wrong state, or ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if no report with given type and ID is found.
hids_host_get_protocol_mode
uint8_t hids_host_get_protocol_mode(uint16_t hids_cid, uint8_t service_index);
Get Protocol Mode. Event GATTSERVICE_SUBEVENT_HID_PROTOCOL_MODE is emitted.
Parameters
- hids_cid
- service_index
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED if client is in wrong state, or ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if no report with given type and ID is found.
hids_host_send_set_protocol_mode
uint8_t hids_host_send_set_protocol_mode(uint16_t hids_cid, uint8_t service_index, hid_protocol_mode_t protocol_mode);
Set Protocol Mode.
Parameters
- hids_cid
- service_index
- protocol_mode
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED if client is in wrong state, or ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if no report with given type and ID is found.
hids_host_send_suspend
uint8_t hids_host_send_suspend(uint16_t hids_cid, uint8_t service_index);
Send Suspend to remote HID service.
Parameters
- hids_cid
- service_index
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED if client is in wrong state, or ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if no report with given type and ID is found.
hids_host_send_exit_suspend
uint8_t hids_host_send_exit_suspend(uint16_t hids_cid, uint8_t service_index);
Send Exit Suspend to remote HID service.
Parameters
- hids_cid
- service_index
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED if client is in wrong state, or ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if no report with given type and ID is found.
hids_host_enable_notifications
uint8_t hids_host_enable_notifications(uint16_t hids_cid);
Enable all notifications. Event GATTSERVICE_SUBEVENT_HID_SERVICE_REPORTS_NOTIFICATION reports current configuration.
Parameters
- hids_cid
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, or ERROR_CODE_COMMAND_DISALLOWED if client is in wrong state.
hids_host_disable_notifications
uint8_t hids_host_disable_notifications(uint16_t hids_cid);
Disable all notifications. Event GATTSERVICE_SUBEVENT_HID_SERVICE_REPORTS_NOTIFICATION reports current configuration.
Parameters
- hids_cid
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, or ERROR_CODE_COMMAND_DISALLOWED if client is in wrong state.
hids_host_disconnect
uint8_t hids_host_disconnect(uint16_t hids_cid);
Disconnect from HID Service.
Parameters
- hids_cid
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER
hids_host_descriptor_storage_get_descriptor_data
const uint8_t * hids_host_descriptor_storage_get_descriptor_data(uint16_t hids_cid, uint8_t service_index);
Disconnect from HID Service.
Get descriptor data. For services in boot mode without a Report Map, a default HID Descriptor for Keyboard/Mouse is provided.
Parameters
- hids_cid
- hid_cid
Returns
- const uint8_t : status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER / uint8_t hids_host_disconnect(uint16_t hids_cid); / data
hids_host_descriptor_storage_get_descriptor_len
uint16_t hids_host_descriptor_storage_get_descriptor_len(uint16_t hids_cid, uint8_t service_index);
Disconnect from HID Service.
Get descriptor data. For services in boot mode without a Report Map, a default HID Descriptor for Keyboard/Mouse is provided.
Get descriptor length
Parameters
- hids_cid
- hid_cid
- hid_cid
Returns
- uint16_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER / uint8_t hids_host_disconnect(uint16_t hids_cid); /* data / const uint8_t * hids_host_descriptor_storage_get_descriptor_data(uint16_t hids_cid, uint8_t service_index); /* length
hids_host_deinit
void hids_host_deinit(void);
De-initialize HID Service Client.