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