1 /******************************************************************************
2 *
3 * Copyright 2002-2012 Broadcom Corporation
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at:
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *
17 ******************************************************************************/
18 #ifndef BTA_HH_API_H
19 #define BTA_HH_API_H
20
21 #include <base/strings/stringprintf.h>
22
23 #include <cstdint>
24 #include <string>
25
26 #include "bta/include/bta_api.h"
27 #include "stack/include/bt_hdr.h"
28 #include "stack/include/hiddefs.h"
29 #include "types/raw_address.h"
30
31 /*****************************************************************************
32 * Constants and Type Definitions
33 ****************************************************************************/
34 #ifndef BTA_HH_DEBUG
35 #define BTA_HH_DEBUG TRUE
36 #endif
37
38 #ifndef BTA_HH_SSR_MAX_LATENCY_DEF
39 #define BTA_HH_SSR_MAX_LATENCY_DEF 800 /* 500 ms*/
40 #endif
41
42 #ifndef BTA_HH_SSR_MIN_TOUT_DEF
43 #define BTA_HH_SSR_MIN_TOUT_DEF 2
44 #endif
45
46 #ifndef CASE_RETURN_TEXT
47 #define CASE_RETURN_TEXT(code) \
48 case code: \
49 return #code
50 #endif
51
52 /* BTA HID Host callback events */
53 #define BTA_HH_ENABLE_EVT 0 /* HH enabled */
54 #define BTA_HH_DISABLE_EVT 1 /* HH disabled */
55 #define BTA_HH_OPEN_EVT 2 /* connection opened */
56 #define BTA_HH_CLOSE_EVT 3 /* connection closed */
57 #define BTA_HH_GET_RPT_EVT 4 /* BTA_HhGetReport callback */
58 #define BTA_HH_SET_RPT_EVT 5 /* BTA_HhSetReport callback */
59 #define BTA_HH_GET_PROTO_EVT 6 /* BTA_GetProtoMode callback */
60 #define BTA_HH_SET_PROTO_EVT 7 /* BTA_HhSetProtoMode callback */
61 #define BTA_HH_GET_IDLE_EVT 8 /* BTA_HhGetIdle comes callback */
62 #define BTA_HH_SET_IDLE_EVT 9 /* BTA_HhSetIdle finish callback */
63 #define BTA_HH_GET_DSCP_EVT 10 /* Get report descriptor */
64 #define BTA_HH_ADD_DEV_EVT 11 /* Add Device callback */
65 #define BTA_HH_RMV_DEV_EVT 12 /* remove device finished */
66 #define BTA_HH_VC_UNPLUG_EVT 13 /* virtually unplugged */
67 #define BTA_HH_DATA_EVT 15
68 #define BTA_HH_API_ERR_EVT 16 /* API error is caught */
69 #define BTA_HH_UPDATE_SCPP_EVT 17 /* update scan paramter complete */
70
71 typedef uint16_t tBTA_HH_EVT;
72
73 /* application ID(none-zero) for each type of device */
74 #define BTA_HH_APP_ID_MI 1
75 #define BTA_HH_APP_ID_KB 2
76 #define BTA_HH_APP_ID_RMC 3
77 #define BTA_HH_APP_ID_3DSG 4
78 #define BTA_HH_APP_ID_JOY 5
79 #define BTA_HH_APP_ID_GPAD 6
80 #define BTA_HH_APP_ID_LE 0xff
81
82 /* defined the minimum offset */
83 #define BTA_HH_MIN_OFFSET (L2CAP_MIN_OFFSET + 1)
84
85 /* HID_HOST_MAX_DEVICES can not exceed 15 for th design of BTA HH */
86 #define BTA_HH_IDX_INVALID 0xff
87 #define BTA_HH_MAX_KNOWN HID_HOST_MAX_DEVICES
88
89 /* GATT_MAX_PHY_CHANNEL can not exceed 14 for the design of BTA HH */
90 #if GATT_MAX_PHY_CHANNEL > 14
91 #define BTA_HH_LE_MAX_KNOWN 14
92 #else
93 #define BTA_HH_LE_MAX_KNOWN GATT_MAX_PHY_CHANNEL
94 #endif
95
96 #define BTA_HH_MAX_DEVICE (HID_HOST_MAX_DEVICES + BTA_HH_LE_MAX_KNOWN)
97 /* invalid device handle */
98 #define BTA_HH_INVALID_HANDLE 0xff
99
100 /* type of protocol mode */
101 #define BTA_HH_PROTO_RPT_MODE (0x00)
102 #define BTA_HH_PROTO_BOOT_MODE (0x01)
103 #define BTA_HH_PROTO_UNKNOWN (0xff)
104 typedef uint8_t tBTA_HH_PROTO_MODE;
105
106 enum { BTA_HH_KEYBD_RPT_ID = 1, BTA_HH_MOUSE_RPT_ID };
107 typedef uint8_t tBTA_HH_BOOT_RPT_ID;
108
109 /* type of devices, bit mask */
110 #define BTA_HH_DEVT_UNKNOWN 0x00
111 #define BTA_HH_DEVT_JOS 0x01 /* joy stick */
112 #define BTA_HH_DEVT_GPD 0x02 /* game pad */
113 #define BTA_HH_DEVT_RMC 0x03 /* remote control */
114 #define BTA_HH_DEVT_SED 0x04 /* sensing device */
115 #define BTA_HH_DEVT_DGT 0x05 /* Digitizer tablet */
116 #define BTA_HH_DEVT_CDR 0x06 /* card reader */
117 #define BTA_HH_DEVT_KBD 0x10 /* keyboard */
118 #define BTA_HH_DEVT_MIC 0x20 /* pointing device */
119 #define BTA_HH_DEVT_COM 0x30 /* Combo keyboard/pointing */
120 #define BTA_HH_DEVT_OTHER 0x80
121 typedef uint8_t tBTA_HH_DEVT;
122
123 typedef enum : uint8_t {
124 BTA_HH_OK = 0,
125 BTA_HH_HS_HID_NOT_READY, /* handshake error : device not ready */
126 BTA_HH_HS_INVALID_RPT_ID, /* handshake error : invalid report ID */
127 BTA_HH_HS_TRANS_NOT_SPT, /* handshake error : transaction not spt */
128 BTA_HH_HS_INVALID_PARAM, /* handshake error : invalid paremter */
129 BTA_HH_HS_ERROR, /* handshake error : unspecified HS error */
130 BTA_HH_ERR, /* general BTA HH error */
131 BTA_HH_ERR_SDP, /* SDP error */
132 BTA_HH_ERR_PROTO, /* SET_Protocol error,
133 only used in BTA_HH_OPEN_EVT callback */
134
135 BTA_HH_ERR_DB_FULL, /* device database full error, used in
136 BTA_HH_OPEN_EVT/BTA_HH_ADD_DEV_EVT */
137 BTA_HH_ERR_TOD_UNSPT, /* type of device not supported */
138 BTA_HH_ERR_NO_RES, /* out of system resources */
139 BTA_HH_ERR_AUTH_FAILED, /* authentication fail */
140 BTA_HH_ERR_HDL,
141 BTA_HH_ERR_SEC,
142 BTA_HH_HS_SERVICE_CHANGED /* GATT service changed on the peer */
143 } tBTA_HH_STATUS;
144
to_bta_hh_status(uint32_t status)145 inline tBTA_HH_STATUS to_bta_hh_status(uint32_t status) {
146 return static_cast<tBTA_HH_STATUS>(status);
147 }
148
bta_hh_status_text(const tBTA_HH_STATUS & status)149 inline std::string bta_hh_status_text(const tBTA_HH_STATUS& status) {
150 switch (status) {
151 CASE_RETURN_TEXT(BTA_HH_OK);
152 CASE_RETURN_TEXT(BTA_HH_HS_HID_NOT_READY);
153 CASE_RETURN_TEXT(BTA_HH_HS_INVALID_RPT_ID);
154 CASE_RETURN_TEXT(BTA_HH_HS_TRANS_NOT_SPT);
155 CASE_RETURN_TEXT(BTA_HH_HS_INVALID_PARAM);
156 CASE_RETURN_TEXT(BTA_HH_HS_ERROR);
157 CASE_RETURN_TEXT(BTA_HH_ERR);
158 CASE_RETURN_TEXT(BTA_HH_ERR_SDP);
159 CASE_RETURN_TEXT(BTA_HH_ERR_PROTO);
160 CASE_RETURN_TEXT(BTA_HH_ERR_DB_FULL);
161 CASE_RETURN_TEXT(BTA_HH_ERR_TOD_UNSPT);
162 CASE_RETURN_TEXT(BTA_HH_ERR_NO_RES);
163 CASE_RETURN_TEXT(BTA_HH_ERR_AUTH_FAILED);
164 CASE_RETURN_TEXT(BTA_HH_ERR_HDL);
165 CASE_RETURN_TEXT(BTA_HH_ERR_SEC);
166 default:
167 return base::StringPrintf("UNKNOWN[%hhu]", status);
168 }
169 }
170
171 typedef uint16_t tBTA_HH_ATTR_MASK;
172
173 /* supported type of device and corresponding application ID */
174 typedef struct {
175 tBTA_HH_DEVT tod; /* type of device */
176 uint8_t app_id; /* corresponding application ID */
177 } tBTA_HH_SPT_TOD;
178
179 /* configuration struct */
180 typedef struct {
181 uint8_t max_devt_spt; /* max number of types of devices spt */
182 tBTA_HH_SPT_TOD* p_devt_list; /* supported types of device list */
183 uint16_t sdp_db_size;
184 } tBTA_HH_CFG;
185
186 enum {
187 BTA_HH_RPTT_RESRV, /* reserved */
188 BTA_HH_RPTT_INPUT, /* input report */
189 BTA_HH_RPTT_OUTPUT, /* output report */
190 BTA_HH_RPTT_FEATURE /* feature report */
191 };
192 typedef uint8_t tBTA_HH_RPT_TYPE;
193
194 /* HID_CONTROL operation code used in BTA_HhSendCtrl()
195 */
196 enum {
197 BTA_HH_CTRL_NOP = 0 + HID_PAR_CONTROL_NOP, /* mapping from BTE */
198 BTA_HH_CTRL_HARD_RESET, /* hard reset */
199 BTA_HH_CTRL_SOFT_RESET, /* soft reset */
200 BTA_HH_CTRL_SUSPEND, /* enter suspend */
201 BTA_HH_CTRL_EXIT_SUSPEND, /* exit suspend */
202 BTA_HH_CTRL_VIRTUAL_CABLE_UNPLUG /* virtual unplug */
203 };
204 typedef uint8_t tBTA_HH_TRANS_CTRL_TYPE;
205
206 typedef tHID_DEV_DSCP_INFO tBTA_HH_DEV_DESCR;
207
208 #define BTA_HH_SSR_PARAM_INVALID HID_SSR_PARAM_INVALID
209
210 /* id DI is not existing in remote device, vendor_id in tBTA_HH_DEV_DSCP_INFO
211 * will be set to 0xffff */
212 #define BTA_HH_VENDOR_ID_INVALID 0xffff
213
214 /* report descriptor information */
215 typedef struct {
216 uint16_t vendor_id; /* vendor ID */
217 uint16_t product_id; /* product ID */
218 uint16_t version; /* version */
219 uint16_t ssr_max_latency; /* SSR max latency, BTA_HH_SSR_PARAM_INVALID if
220 unknown */
221 uint16_t
222 ssr_min_tout; /* SSR min timeout, BTA_HH_SSR_PARAM_INVALID if unknown */
223 uint8_t ctry_code; /*Country Code.*/
224 #define BTA_HH_LE_REMOTE_WAKE 0x01
225 #define BTA_HH_LE_NORMAL_CONN 0x02
226
227 uint8_t flag;
228 tBTA_HH_DEV_DESCR descriptor;
229 uint8_t hid_handle;
230
ToString__anon4573e4610708231 std::string ToString() const {
232 return base::StringPrintf("%04x::%04x::%04x", vendor_id, product_id,
233 version);
234 }
235 } tBTA_HH_DEV_DSCP_INFO;
236
237 /* callback event data for BTA_HH_OPEN_EVT */
238 typedef struct {
239 RawAddress bda; /* HID device bd address */
240 tBTA_HH_STATUS status; /* operation status */
241 uint8_t handle; /* device handle */
242 bool le_hid; /* is LE devices? */
243 bool scps_supported; /* scan parameter service supported */
244 uint8_t sub_class; /* Cod sub class */
245 uint16_t attr_mask; /* attribute mask */
246 uint8_t app_id;
247 } tBTA_HH_CONN;
248
249 typedef tBTA_HH_CONN tBTA_HH_DEV_INFO;
250
251 /* callback event data */
252 typedef struct {
253 tBTA_HH_STATUS status; /* operation status */
254 uint8_t handle; /* device handle */
255 } tBTA_HH_CBDATA;
256
257 enum {
258 BTA_HH_MOD_CTRL_KEY,
259 BTA_HH_MOD_SHFT_KEY,
260 BTA_HH_MOD_ALT_KEY,
261 BTA_HH_MOD_GUI_KEY,
262 BTA_HH_MOD_MAX_KEY
263 };
264
265 /* parsed boot mode keyboard report */
266 typedef struct {
267 uint8_t this_char[6]; /* virtual key code */
268 bool mod_key[BTA_HH_MOD_MAX_KEY];
269 /* ctrl, shift, Alt, GUI */
270 /* modifier key: is Shift key pressed */
271 /* modifier key: is Ctrl key pressed */
272 /* modifier key: is Alt key pressed */
273 /* modifier key: GUI up/down */
274 bool caps_lock; /* is caps locked */
275 bool num_lock; /* is Num key pressed */
276 } tBTA_HH_KEYBD_RPT;
277
278 /* parsed boot mode mouse report */
279 typedef struct {
280 uint8_t mouse_button; /* mouse button is clicked */
281 int8_t delta_x; /* displacement x */
282 int8_t delta_y; /* displacement y */
283 } tBTA_HH_MICE_RPT;
284
285 /* parsed Boot report */
286 typedef struct {
287 tBTA_HH_BOOT_RPT_ID dev_type; /* type of device report */
288 union {
289 tBTA_HH_KEYBD_RPT keybd_rpt; /* keyboard report */
290 tBTA_HH_MICE_RPT mice_rpt; /* mouse report */
291 } data_rpt;
292 } tBTA_HH_BOOT_RPT;
293
294 /* handshake data */
295 typedef struct {
296 tBTA_HH_STATUS status; /* handshake status */
297 uint8_t handle; /* device handle */
298 union {
299 tBTA_HH_PROTO_MODE proto_mode; /* GET_PROTO_EVT :protocol mode */
300 BT_HDR* p_rpt_data; /* GET_RPT_EVT : report data */
301 uint8_t idle_rate; /* GET_IDLE_EVT : idle rate */
302 } rsp_data;
303
304 } tBTA_HH_HSDATA;
305
306 /* union of data associated with HD callback */
307 typedef union {
308 tBTA_HH_DEV_INFO dev_info; /* BTA_HH_ADD_DEV_EVT, BTA_HH_RMV_DEV_EVT */
309 tBTA_HH_CONN conn; /* BTA_HH_OPEN_EVT */
310 tBTA_HH_CBDATA dev_status; /* BTA_HH_CLOSE_EVT,
311 BTA_HH_SET_PROTO_EVT
312 BTA_HH_SET_RPT_EVT
313 BTA_HH_SET_IDLE_EVT
314 BTA_HH_UPDATE_SCPP_EVT */
315
316 tBTA_HH_STATUS status; /* BTA_HH_ENABLE_EVT */
317 tBTA_HH_DEV_DSCP_INFO dscp_info; /* BTA_HH_GET_DSCP_EVT */
318 tBTA_HH_HSDATA hs_data; /* GET_ transaction callback
319 BTA_HH_GET_RPT_EVT
320 BTA_HH_GET_PROTO_EVT
321 BTA_HH_GET_IDLE_EVT */
322 } tBTA_HH;
323
324 /* BTA HH callback function */
325 typedef void(tBTA_HH_CBACK)(tBTA_HH_EVT event, tBTA_HH* p_data);
326
327 /*****************************************************************************
328 * External Function Declarations
329 ****************************************************************************/
330
331 /*******************************************************************************
332 *
333 * Function BTA_HhEnable
334 *
335 * Description This function enable HID host and registers HID-Host with
336 * lower layers.
337 *
338 * Returns void
339 *
340 ******************************************************************************/
341 void BTA_HhEnable(tBTA_HH_CBACK* p_cback, bool enable_hid, bool enable_hogp);
342
343 /*******************************************************************************
344 *
345 * Function BTA_HhDisable
346 *
347 * Description This function is called when the host is about power down.
348 *
349 * Returns void
350 *
351 ******************************************************************************/
352 void BTA_HhDisable(void);
353
354 /*******************************************************************************
355 *
356 * Function BTA_HhOpen
357 *
358 * Description This function is called to start an inquiry and read SDP
359 * record of responding devices; connect to a device if only
360 * one active HID device is found.
361 *
362 * Returns void
363 *
364 ******************************************************************************/
365 void BTA_HhOpen(const RawAddress& dev_bda);
366
367 /*******************************************************************************
368 *
369 * Function BTA_HhClose
370 *
371 * Description This function disconnects the device.
372 *
373 * Returns void
374 *
375 ******************************************************************************/
376 void BTA_HhClose(uint8_t dev_handle);
377
378 /*******************************************************************************
379 *
380 * Function BTA_HhSetProtoMode
381 *
382 * Description This function set the protocol mode at specified HID handle
383 *
384 * Returns void
385 *
386 ******************************************************************************/
387 void BTA_HhSetProtoMode(uint8_t handle, tBTA_HH_PROTO_MODE t_type);
388
389 /*******************************************************************************
390 *
391 * Function BTA_HhGetProtoMode
392 *
393 * Description This function get the protocol mode of a specified HID
394 * device.
395 *
396 * Returns void
397 *
398 ******************************************************************************/
399 void BTA_HhGetProtoMode(uint8_t dev_handle);
400 /*******************************************************************************
401 *
402 * Function BTA_HhSetReport
403 *
404 * Description send SET_REPORT to device.
405 *
406 * Returns void
407 *
408 ******************************************************************************/
409 void BTA_HhSetReport(uint8_t dev_handle, tBTA_HH_RPT_TYPE r_type,
410 BT_HDR* p_data);
411
412 /*******************************************************************************
413 *
414 * Function BTA_HhGetReport
415 *
416 * Description Send a GET_REPORT to HID device.
417 *
418 * Returns void
419 *
420 ******************************************************************************/
421 void BTA_HhGetReport(uint8_t dev_handle, tBTA_HH_RPT_TYPE r_type,
422 uint8_t rpt_id, uint16_t buf_size);
423 /*******************************************************************************
424 *
425 * Function BTA_HhSetIdle
426 *
427 * Description send SET_IDLE to device.
428 *
429 * Returns void
430 *
431 ******************************************************************************/
432 void BTA_HhSetIdle(uint8_t dev_handle, uint16_t idle_rate);
433
434 /*******************************************************************************
435 *
436 * Function BTA_HhGetIdle
437 *
438 * Description Send a GET_IDLE to HID device.
439 *
440 * Returns void
441 *
442 ******************************************************************************/
443 void BTA_HhGetIdle(uint8_t dev_handle);
444
445 /*******************************************************************************
446 *
447 * Function BTA_HhSendCtrl
448 *
449 * Description Send HID_CONTROL request to a HID device.
450 *
451 * Returns void
452 *
453 ******************************************************************************/
454 void BTA_HhSendCtrl(uint8_t dev_handle, tBTA_HH_TRANS_CTRL_TYPE c_type);
455
456 /*******************************************************************************
457 *
458 * Function BTA_HhSetIdle
459 *
460 * Description send SET_IDLE to device.
461 *
462 * Returns void
463 *
464 ******************************************************************************/
465 void BTA_HhSetIdle(uint8_t dev_handle, uint16_t idle_rate);
466
467 /*******************************************************************************
468 *
469 * Function BTA_HhGetIdle
470 *
471 * Description Send a GET_IDLE from HID device.
472 *
473 * Returns void
474 *
475 ******************************************************************************/
476 void BTA_HhGetIdle(uint8_t dev_handle);
477
478 /*******************************************************************************
479 *
480 * Function BTA_HhSendData
481 *
482 * Description Send DATA transaction to a HID device.
483 *
484 * Returns void
485 *
486 ******************************************************************************/
487 void BTA_HhSendData(uint8_t dev_handle, const RawAddress& dev_bda,
488 BT_HDR* p_buf);
489
490 /*******************************************************************************
491 *
492 * Function BTA_HhGetDscpInfo
493 *
494 * Description Get report descriptor of the device
495 *
496 * Returns void
497 *
498 ******************************************************************************/
499 void BTA_HhGetDscpInfo(uint8_t dev_handle);
500
501 /*******************************************************************************
502 * Function BTA_HhAddDev
503 *
504 * Description Add a virtually cabled device into HID-Host device list
505 * to manage and assign a device handle for future API call,
506 * host applciation call this API at start-up to initialize its
507 * virtually cabled devices.
508 *
509 * Returns void
510 *
511 ******************************************************************************/
512 void BTA_HhAddDev(const RawAddress& bda, tBTA_HH_ATTR_MASK attr_mask,
513 uint8_t sub_class, uint8_t app_id,
514 tBTA_HH_DEV_DSCP_INFO dscp_info);
515 /*******************************************************************************
516 *
517 * Function BTA_HhRemoveDev
518 *
519 * Description Remove a device from the HID host devices list.
520 *
521 * Returns void
522 *
523 ******************************************************************************/
524 void BTA_HhRemoveDev(uint8_t dev_handle);
525
526 #endif /* BTA_HH_API_H */
527