mirror of
https://github.com/bluekitchen/btstack.git
synced 2025-04-01 04:20:33 +00:00
hid_host: document API
This commit is contained in:
Milanka Ringwald
Matthias Ringwald
parent
57e682fe0b
commit
5f0d88b06f
@ -120,57 +120,145 @@ typedef struct {
|
||||
} hid_host_connection_t;
|
||||
|
||||
/* API_START */
|
||||
|
||||
/**
|
||||
* @brief Set up HID Host
|
||||
* @param boot_protocol_mode_supported
|
||||
* @param hid_descriptor_storage
|
||||
* @param hid_descriptor_storage_len
|
||||
*/
|
||||
void hid_host_init(uint8_t * hid_descriptor_storage, uint16_t hid_descriptor_storage_len);
|
||||
|
||||
/**
|
||||
* @brief Register callback for the HID Device Host.
|
||||
* @brief Register callback for the HID Host.
|
||||
* @param callback
|
||||
*/
|
||||
void hid_host_register_packet_handler(btstack_packet_handler_t callback);
|
||||
|
||||
/*
|
||||
* @brief Create HID connection to HID Host
|
||||
* @brief Create HID connection to HID Device and emit HID_SUBEVENT_CONNECTION_OPENED event with status code.
|
||||
* @note HID_PROTOCOL_MODE_REPORT_WITH_FALLBACK_TO_BOOT will try ti set up REPORT mode, but fallback to BOOT mode if necessary.
|
||||
* @note Reports from HID Device are received via HID_SUBEVENT_REPORT.
|
||||
* @param remote_addr
|
||||
* @param protocol_mode see hid_protocol_mode_t in hid.h
|
||||
* @param hid_cid to use for other commands
|
||||
* @result status
|
||||
* @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_COMMAND_DISALLOWED, BTSTACK_MEMORY_ALLOC_FAILED
|
||||
*/
|
||||
uint8_t hid_host_connect(bd_addr_t remote_addr, hid_protocol_mode_t protocol_mode, uint16_t * hid_cid);
|
||||
|
||||
|
||||
/*
|
||||
* @brief Accept incoming HID connection, this should be called upon receiving HID_SUBEVENT_INCOMING_CONNECTION event.
|
||||
* @param hid_cid
|
||||
* @param protocol_mode see hid_protocol_mode_t in hid.h
|
||||
* @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
|
||||
*/
|
||||
uint8_t hid_host_accept_connection(uint16_t hid_cid, hid_protocol_mode_t protocol_mode);
|
||||
|
||||
/*
|
||||
* @brief Decline incoming HID connection, this should be called upon receiving HID_SUBEVENT_INCOMING_CONNECTION event.
|
||||
* @param hid_cid
|
||||
* @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
|
||||
*/
|
||||
uint8_t hid_host_decline_connection(uint16_t hid_cid);
|
||||
|
||||
/*
|
||||
* @brief Disconnect from HID Host
|
||||
* @brief Disconnect from HID Device and emit HID_SUBEVENT_CONNECTION_CLOSED event.
|
||||
* @param hid_cid
|
||||
*/
|
||||
void hid_host_disconnect(uint16_t hid_cid);
|
||||
|
||||
// Control messages:
|
||||
|
||||
/*
|
||||
* @brief Send SUSPEND control signal to connected HID Device. A Bluetooth HID Device which receives a SUSPEND control signal
|
||||
* may optionally disconnect from the Bluetooth HID Host.
|
||||
* @param hid_cid
|
||||
* @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
|
||||
*/
|
||||
uint8_t hid_host_send_suspend(uint16_t hid_cid);
|
||||
|
||||
/*
|
||||
* @brief Order connected HID Device to exit suspend mode.
|
||||
* The Bluetooth HID Device shall send a report to the Bluetooth HID Host.
|
||||
* @param hid_cid
|
||||
* @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
|
||||
*/
|
||||
uint8_t hid_host_send_exit_suspend(uint16_t hid_cid);
|
||||
|
||||
/*
|
||||
* @brief Unplug connected HID Device.
|
||||
* @note This is the only command that can be also received from HID Device. It will be indicated by receiving
|
||||
* HID_SUBEVENT_VIRTUAL_CABLE_UNPLUG event, as well as disconnecting HID Host from device.
|
||||
* @param hid_cid
|
||||
* @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
|
||||
*/
|
||||
uint8_t hid_host_send_virtual_cable_unplug(uint16_t hid_cid);
|
||||
|
||||
/*
|
||||
* @brief Set Protocol Mode on the Bluetooth HID Device and emit HID_SUBEVENT_SET_PROTOCOL_RESPONSE event with handshake_status, see hid_handshake_param_type_t
|
||||
* @param hid_cid
|
||||
* @param protocol_mode see hid_protocol_mode_t in hid.h
|
||||
* @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
|
||||
*/
|
||||
uint8_t hid_host_send_set_protocol_mode(uint16_t hid_cid, hid_protocol_mode_t protocol_mode);
|
||||
|
||||
/*
|
||||
* @brief Retrieve the Protocol Mode of the Bluetooth HID Device and emit HID_SUBEVENT_GET_PROTOCOL_RESPONSE with handshake_status, see hid_handshake_param_type_t
|
||||
* @param hid_cid
|
||||
* @param protocol_mode see hid_protocol_mode_t in hid.h
|
||||
* @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
|
||||
*/
|
||||
uint8_t hid_host_send_get_protocol(uint16_t hid_cid);
|
||||
|
||||
/*
|
||||
|
||||
* @brief Send report to a Bluetooth HID Device and emit HID_SUBEVENT_SET_REPORT_RESPONSE with handshake_status, see hid_handshake_param_type_t. The Bluetooth HID Host shall send complete reports.
|
||||
* @param hid_cid
|
||||
* @param report_type see hid_report_type_t in hid.h
|
||||
* @param report_id
|
||||
* @param report
|
||||
* @param report_len
|
||||
* @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
|
||||
*/
|
||||
uint8_t hid_host_send_set_report(uint16_t hid_cid, hid_report_type_t report_type, uint8_t report_id, const uint8_t * report, uint8_t report_len);
|
||||
|
||||
/*
|
||||
* @brief Request a HID report from the Bluetooth HID Device and emit HID_SUBEVENT_GET_REPORT_RESPONSE event with with handshake_status, see hid_handshake_param_type_t.
|
||||
* Polling Bluetooth HID Devices using the GET_REPORT transfer is costly in terms of time and overhead,
|
||||
* and should be avoided whenever possible. The GET_REPORT transfer is typically only used by applications
|
||||
* to determine the initial state of a Bluetooth HID Device. If the state of a report changes frequently,
|
||||
* then the report should be reported over the more efficient Interrupt channel, see hid_host_send_report.
|
||||
* @param hid_cid
|
||||
* @param report_type see hid_report_type_t in hid.h
|
||||
* @param report_id
|
||||
* @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
|
||||
*/
|
||||
uint8_t hid_host_send_get_report(uint16_t hid_cid, hid_report_type_t report_type, uint8_t report_id);
|
||||
|
||||
/**
|
||||
* @brief Send HID message on interrupt channel
|
||||
* @brief Send HID output report on interrupt channel.
|
||||
* @param hid_cid
|
||||
* @param report_id
|
||||
* @param report
|
||||
* @param report_len
|
||||
* @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
|
||||
*/
|
||||
// on interrupt channel, allways output
|
||||
uint8_t hid_host_send_report(uint16_t hid_cid, uint8_t report_id, const uint8_t * report, uint8_t report_len);
|
||||
|
||||
/*
|
||||
* @brief Get descriptor data
|
||||
* @param hid_cid
|
||||
* @result data
|
||||
*/
|
||||
const uint8_t * hid_descriptor_storage_get_descriptor_data(uint16_t hid_cid);
|
||||
|
||||
/*
|
||||
* @brief Get descriptor length
|
||||
* @param hid_cid
|
||||
* @result length
|
||||
*/
|
||||
const uint16_t hid_descriptor_storage_get_descriptor_len(uint16_t hid_cid);
|
||||
|
||||
/* API_END */
|
||||
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user