hid_host.h (f3a32fdcb9900fa034530ba569b2421a14983887) hid_host.h (3cbedd4337c5f865d4c28535558ba1f75f168a17)
1/*
2 * Copyright (C) 2020 BlueKitchen GmbH
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 *
8 * 1. Redistributions of source code must retain the above copyright

--- 27 unchanged lines hidden (view full) ---

36 */
37
38#ifndef HID_HOST_H
39#define HID_HOST_H
40
41#include <stdint.h>
42#include "btstack_defines.h"
43#include "bluetooth.h"
1/*
2 * Copyright (C) 2020 BlueKitchen GmbH
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 *
8 * 1. Redistributions of source code must retain the above copyright

--- 27 unchanged lines hidden (view full) ---

36 */
37
38#ifndef HID_HOST_H
39#define HID_HOST_H
40
41#include <stdint.h>
42#include "btstack_defines.h"
43#include "bluetooth.h"
44#include "btstack_hid.h"
44#include "btstack_hid_parser.h"
45#include "btstack_hid_parser.h"
45#include "hid.h"
46
47#if defined __cplusplus
48extern "C" {
49#endif
50
51
52typedef enum {
53 HID_HOST_IDLE,

--- 89 unchanged lines hidden (view full) ---

143 * may already come via HID_SUBEVENT_REPORT event. It is up to the application code if
144 * these reports should be buffered or ignored until the descriptor is available.
145 * @note HID_PROTOCOL_MODE_REPORT_WITH_FALLBACK_TO_BOOT will try ti set up REPORT mode, but fallback to BOOT mode if necessary.
146 * @note HID_SUBEVENT_DESCRIPTOR_AVAILABLE possible status values are:
147 * - ERROR_CODE_SUCCESS if descriptor available,
148 * - ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if not, and
149 * - ERROR_CODE_MEMORY_CAPACITY_EXCEEDED if descriptor is larger then the available space
150 * @param remote_addr
46
47#if defined __cplusplus
48extern "C" {
49#endif
50
51
52typedef enum {
53 HID_HOST_IDLE,

--- 89 unchanged lines hidden (view full) ---

143 * may already come via HID_SUBEVENT_REPORT event. It is up to the application code if
144 * these reports should be buffered or ignored until the descriptor is available.
145 * @note HID_PROTOCOL_MODE_REPORT_WITH_FALLBACK_TO_BOOT will try ti set up REPORT mode, but fallback to BOOT mode if necessary.
146 * @note HID_SUBEVENT_DESCRIPTOR_AVAILABLE possible status values are:
147 * - ERROR_CODE_SUCCESS if descriptor available,
148 * - ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if not, and
149 * - ERROR_CODE_MEMORY_CAPACITY_EXCEEDED if descriptor is larger then the available space
150 * @param remote_addr
151 * @param protocol_mode see hid_protocol_mode_t in hid.h
151 * @param protocol_mode see hid_protocol_mode_t in btstack_hid.h
152 * @param hid_cid to use for other commands
153 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_COMMAND_DISALLOWED, BTSTACK_MEMORY_ALLOC_FAILED
154 */
155uint8_t hid_host_connect(bd_addr_t remote_addr, hid_protocol_mode_t protocol_mode, uint16_t * hid_cid);
156
157
158/*
159 * @brief Accept incoming HID connection, this should be called upon receiving HID_SUBEVENT_INCOMING_CONNECTION event.
160 * @param hid_cid
152 * @param hid_cid to use for other commands
153 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_COMMAND_DISALLOWED, BTSTACK_MEMORY_ALLOC_FAILED
154 */
155uint8_t hid_host_connect(bd_addr_t remote_addr, hid_protocol_mode_t protocol_mode, uint16_t * hid_cid);
156
157
158/*
159 * @brief Accept incoming HID connection, this should be called upon receiving HID_SUBEVENT_INCOMING_CONNECTION event.
160 * @param hid_cid
161 * @param protocol_mode see hid_protocol_mode_t in hid.h
161 * @param protocol_mode see hid_protocol_mode_t in btstack_hid.h
162 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
163 */
164uint8_t hid_host_accept_connection(uint16_t hid_cid, hid_protocol_mode_t protocol_mode);
165
166/*
167 * @brief Decline incoming HID connection, this should be called upon receiving HID_SUBEVENT_INCOMING_CONNECTION event.
168 * @param hid_cid
169 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED

--- 31 unchanged lines hidden (view full) ---

201 * @param hid_cid
202 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
203 */
204uint8_t hid_host_send_virtual_cable_unplug(uint16_t hid_cid);
205
206/*
207 * @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
208 * @param hid_cid
162 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
163 */
164uint8_t hid_host_accept_connection(uint16_t hid_cid, hid_protocol_mode_t protocol_mode);
165
166/*
167 * @brief Decline incoming HID connection, this should be called upon receiving HID_SUBEVENT_INCOMING_CONNECTION event.
168 * @param hid_cid
169 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED

--- 31 unchanged lines hidden (view full) ---

201 * @param hid_cid
202 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
203 */
204uint8_t hid_host_send_virtual_cable_unplug(uint16_t hid_cid);
205
206/*
207 * @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
208 * @param hid_cid
209 * @param protocol_mode see hid_protocol_mode_t in hid.h
209 * @param protocol_mode see hid_protocol_mode_t in btstack_hid.h
210 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
211 */
212uint8_t hid_host_send_set_protocol_mode(uint16_t hid_cid, hid_protocol_mode_t protocol_mode);
213
214/*
215 * @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
216 * @param hid_cid
210 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
211 */
212uint8_t hid_host_send_set_protocol_mode(uint16_t hid_cid, hid_protocol_mode_t protocol_mode);
213
214/*
215 * @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
216 * @param hid_cid
217 * @param protocol_mode see hid_protocol_mode_t in hid.h
217 * @param protocol_mode see hid_protocol_mode_t in btstack_hid.h
218 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
219 */
220uint8_t hid_host_send_get_protocol(uint16_t hid_cid);
221
222/*
223
224 * @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.
225 * @param hid_cid
218 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
219 */
220uint8_t hid_host_send_get_protocol(uint16_t hid_cid);
221
222/*
223
224 * @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.
225 * @param hid_cid
226 * @param report_type see hid_report_type_t in hid.h
226 * @param report_type see hid_report_type_t in btstack_hid.h
227 * @param report_id
228 * @param report
229 * @param report_len
230 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
231 */
232uint8_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);
233
234/*
235 * @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.
236 * Polling Bluetooth HID Devices using the GET_REPORT transfer is costly in terms of time and overhead,
237 * and should be avoided whenever possible. The GET_REPORT transfer is typically only used by applications
238 * to determine the initial state of a Bluetooth HID Device. If the state of a report changes frequently,
239 * then the report should be reported over the more efficient Interrupt channel, see hid_host_send_report.
240 * @param hid_cid
227 * @param report_id
228 * @param report
229 * @param report_len
230 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
231 */
232uint8_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);
233
234/*
235 * @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.
236 * Polling Bluetooth HID Devices using the GET_REPORT transfer is costly in terms of time and overhead,
237 * and should be avoided whenever possible. The GET_REPORT transfer is typically only used by applications
238 * to determine the initial state of a Bluetooth HID Device. If the state of a report changes frequently,
239 * then the report should be reported over the more efficient Interrupt channel, see hid_host_send_report.
240 * @param hid_cid
241 * @param report_type see hid_report_type_t in hid.h
241 * @param report_type see hid_report_type_t in btstack_hid.h
242 * @param report_id
243 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
244 */
245uint8_t hid_host_send_get_report(uint16_t hid_cid, hid_report_type_t report_type, uint8_t report_id);
246
247/**
248 * @brief Send HID output report on interrupt channel.
249 * @param hid_cid

--- 29 unchanged lines hidden --- 		242 * @param report_id
243 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
244 */
245uint8_t hid_host_send_get_report(uint16_t hid_cid, hid_report_type_t report_type, uint8_t report_id);
246
247/**
248 * @brief Send HID output report on interrupt channel.
249 * @param hid_cid

--- 29 unchanged lines hidden ---