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