1 /******************************************************************************
2  *
3  *  Copyright (C) 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 (defined BTA_HH_LE_INCLUDED && 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 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 (defined BTA_HH_LE_INCLUDED && BTA_HH_LE_INCLUDED == TRUE)
81 /* GATT_MAX_PHY_CHANNEL can not exceed 14 for the design of BTA HH */
82 #define BTA_HH_LE_MAX_KNOWN     GATT_MAX_PHY_CHANNEL
83 #define BTA_HH_MAX_DEVICE        (HID_HOST_MAX_DEVICES + GATT_MAX_PHY_CHANNEL)
84 #else
85 #define BTA_HH_MAX_DEVICE       HID_HOST_MAX_DEVICES
86 #endif
87 /* invalid device handle */
88 #define BTA_HH_INVALID_HANDLE   0xff
89 
90 /* type of protocol mode */
91 #define BTA_HH_PROTO_RPT_MODE                   (0x00)
92 #define BTA_HH_PROTO_BOOT_MODE                  (0x01)
93 #define BTA_HH_PROTO_UNKNOWN                    (0xff)
94 typedef UINT8   tBTA_HH_PROTO_MODE;
95 
96 enum
97 {
98     BTA_HH_KEYBD_RPT_ID  =               1,
99     BTA_HH_MOUSE_RPT_ID
100 };
101 typedef UINT8 tBTA_HH_BOOT_RPT_ID;
102 
103 /* type of devices, bit mask */
104 #define BTA_HH_DEVT_UNKNOWN      0x00
105 #define BTA_HH_DEVT_JOS          0x01           /* joy stick */
106 #define BTA_HH_DEVT_GPD          0x02           /* game pad */
107 #define BTA_HH_DEVT_RMC          0x03           /* remote control */
108 #define BTA_HH_DEVT_SED          0x04           /* sensing device */
109 #define BTA_HH_DEVT_DGT          0x05           /* Digitizer tablet */
110 #define BTA_HH_DEVT_CDR          0x06           /* card reader */
111 #define BTA_HH_DEVT_KBD          0x10           /* keyboard */
112 #define BTA_HH_DEVT_MIC          0x20           /* pointing device */
113 #define BTA_HH_DEVT_COM          0x30           /* Combo keyboard/pointing */
114 #define BTA_HH_DEVT_OTHER        0x80
115 typedef UINT8  tBTA_HH_DEVT;
116 
117 enum
118 {
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 tBTA_HH_STATUS;
139 
140 
141 #define BTA_HH_VIRTUAL_CABLE           HID_VIRTUAL_CABLE
142 #define BTA_HH_NORMALLY_CONNECTABLE    HID_NORMALLY_CONNECTABLE
143 #define BTA_HH_RECONN_INIT             HID_RECONN_INIT
144 #define BTA_HH_SDP_DISABLE             HID_SDP_DISABLE
145 #define BTA_HH_BATTERY_POWER           HID_BATTERY_POWER
146 #define BTA_HH_REMOTE_WAKE             HID_REMOTE_WAKE
147 #define BTA_HH_SUP_TOUT_AVLBL          HID_SUP_TOUT_AVLBL
148 #define BTA_HH_SEC_REQUIRED             HID_SEC_REQUIRED
149 typedef UINT16 tBTA_HH_ATTR_MASK;
150 
151 /* supported type of device and corresponding application ID */
152 typedef struct
153 {
154     tBTA_HH_DEVT        tod;        /* type of device               */
155     UINT8               app_id;     /* corresponding application ID */
156 }tBTA_HH_SPT_TOD;
157 
158 /* configuration struct */
159 typedef struct
160 {
161     UINT8                max_devt_spt; /* max number of types of devices spt */
162     tBTA_HH_SPT_TOD     *p_devt_list;  /* supported types of device list     */
163     UINT16               sdp_db_size;
164 }tBTA_HH_CFG;
165 
166 enum
167 {
168     BTA_HH_RPTT_RESRV,      /* reserved         */
169     BTA_HH_RPTT_INPUT,      /* input report     */
170     BTA_HH_RPTT_OUTPUT,     /* output report    */
171     BTA_HH_RPTT_FEATURE     /* feature report   */
172 };
173 typedef UINT8 tBTA_HH_RPT_TYPE;
174 
175 /* HID_CONTROL operation code used in BTA_HhSendCtrl()
176 */
177 enum
178 {
179     BTA_HH_CTRL_NOP         = 0 + HID_PAR_CONTROL_NOP ,/* mapping from BTE */
180     BTA_HH_CTRL_HARD_RESET,                            /* hard reset       */
181     BTA_HH_CTRL_SOFT_RESET,                            /* soft reset       */
182     BTA_HH_CTRL_SUSPEND,                               /* enter suspend    */
183     BTA_HH_CTRL_EXIT_SUSPEND,                          /* exit suspend     */
184     BTA_HH_CTRL_VIRTUAL_CABLE_UNPLUG                   /* virtual unplug   */
185 };
186 typedef UINT8 tBTA_HH_TRANS_CTRL_TYPE;
187 
188 typedef tHID_DEV_DSCP_INFO tBTA_HH_DEV_DESCR;
189 
190 #define BTA_HH_SSR_PARAM_INVALID       HID_SSR_PARAM_INVALID
191 
192 /* id DI is not existing in remote device, vendor_id in tBTA_HH_DEV_DSCP_INFO will be set to 0xffff */
193 #define BTA_HH_VENDOR_ID_INVALID       0xffff
194 
195 
196 /* report descriptor information */
197 typedef struct
198 {
199     UINT16              vendor_id;      /* vendor ID */
200     UINT16              product_id;     /* product ID */
201     UINT16              version;        /* version */
202     UINT16              ssr_max_latency;    /* SSR max latency, BTA_HH_SSR_PARAM_INVALID if unknown */
203     UINT16              ssr_min_tout;       /* SSR min timeout, BTA_HH_SSR_PARAM_INVALID if unknown */
204     UINT8               ctry_code;      /*Country Code.*/
205 #if (defined BTA_HH_LE_INCLUDED && BTA_HH_LE_INCLUDED == TRUE)
206 #define BTA_HH_LE_REMOTE_WAKE       0x01
207 #define BTA_HH_LE_NORMAL_CONN       0x02
208 
209     UINT8               flag;
210 #endif
211     tBTA_HH_DEV_DESCR   descriptor;
212 }tBTA_HH_DEV_DSCP_INFO;
213 
214 /* callback event data for BTA_HH_OPEN_EVT */
215 typedef struct
216 {
217     BD_ADDR         bda;                /* HID device bd address    */
218     tBTA_HH_STATUS  status;             /* operation status         */
219     UINT8           handle;             /* device handle            */
220 #if (defined BTA_HH_LE_INCLUDED && BTA_HH_LE_INCLUDED == TRUE)
221     BOOLEAN         le_hid;             /* is LE devices? */
222     BOOLEAN         scps_supported;     /* scan parameter service supported */
223 #endif
224 
225 } tBTA_HH_CONN;
226 
227 typedef tBTA_HH_CONN tBTA_HH_DEV_INFO;
228 
229 /* callback event data */
230 typedef struct
231 {
232     tBTA_HH_STATUS              status;     /* operation status         */
233     UINT8                       handle;     /* device handle            */
234 } tBTA_HH_CBDATA;
235 
236 enum
237 {
238     BTA_HH_MOD_CTRL_KEY,
239     BTA_HH_MOD_SHFT_KEY,
240     BTA_HH_MOD_ALT_KEY,
241     BTA_HH_MOD_GUI_KEY,
242     BTA_HH_MOD_MAX_KEY
243 };
244 
245 /* parsed boot mode keyboard report */
246 typedef struct
247 {
248     UINT8               this_char[6];       /* virtual key code     */
249     BOOLEAN             mod_key[BTA_HH_MOD_MAX_KEY];
250                                             /* ctrl, shift, Alt, GUI */
251                                             /* modifier key: is Shift key pressed */
252                                             /* modifier key: is Ctrl key pressed  */
253                                             /* modifier key: is Alt key pressed   */
254                                             /* modifier key: GUI up/down */
255     BOOLEAN             caps_lock;          /* is caps locked       */
256     BOOLEAN             num_lock;           /* is Num key pressed   */
257 } tBTA_HH_KEYBD_RPT;
258 
259 /* parsed boot mode mouse report */
260 typedef struct
261 {
262     UINT8               mouse_button;       /* mouse button is clicked   */
263     INT8                delta_x;            /* displacement x            */
264     INT8                delta_y;            /* displacement y            */
265 }tBTA_HH_MICE_RPT;
266 
267 /* parsed Boot report */
268 typedef struct
269 {
270     tBTA_HH_BOOT_RPT_ID dev_type;           /* type of device report */
271     union
272     {
273         tBTA_HH_KEYBD_RPT   keybd_rpt;      /* keyboard report      */
274         tBTA_HH_MICE_RPT    mice_rpt;       /* mouse report         */
275     }                   data_rpt;
276 } tBTA_HH_BOOT_RPT;
277 
278 /* handshake data */
279 typedef struct
280 {
281     tBTA_HH_STATUS  status;                 /* handshake status */
282     UINT8           handle;                 /* device handle    */
283     union
284     {
285         tBTA_HH_PROTO_MODE      proto_mode; /* GET_PROTO_EVT :protocol mode */
286         BT_HDR                  *p_rpt_data;   /* GET_RPT_EVT   : report data  */
287         UINT8                   idle_rate;  /* GET_IDLE_EVT  : idle rate    */
288     }               rsp_data;
289 
290 }tBTA_HH_HSDATA;
291 
292 /* union of data associated with HD callback */
293 typedef union
294 {
295     tBTA_HH_DEV_INFO        dev_info;           /* BTA_HH_ADD_DEV_EVT, BTA_HH_RMV_DEV_EVT   */
296     tBTA_HH_CONN            conn;               /* BTA_HH_OPEN_EVT      */
297     tBTA_HH_CBDATA          dev_status;         /* BTA_HH_CLOSE_EVT,
298                                                    BTA_HH_SET_PROTO_EVT
299                                                    BTA_HH_SET_RPT_EVT
300                                                    BTA_HH_SET_IDLE_EVT
301                                                    BTA_HH_UPDATE_SCPP_EVT */
302 
303     tBTA_HH_STATUS          status;             /* BTA_HH_ENABLE_EVT */
304     tBTA_HH_DEV_DSCP_INFO   dscp_info;          /* BTA_HH_GET_DSCP_EVT */
305     tBTA_HH_HSDATA          hs_data;            /* GET_ transaction callback
306                                                    BTA_HH_GET_RPT_EVT
307                                                    BTA_HH_GET_PROTO_EVT
308                                                    BTA_HH_GET_IDLE_EVT */
309 } tBTA_HH;
310 
311 /* BTA HH callback function */
312 typedef void (tBTA_HH_CBACK) (tBTA_HH_EVT event, tBTA_HH *p_data);
313 
314 
315 /*****************************************************************************
316 **  External Function Declarations
317 *****************************************************************************/
318 #ifdef __cplusplus
319 extern "C"
320 {
321 #endif
322 
323 /*******************************************************************************
324 **
325 ** Function         BTA_HhRegister
326 **
327 ** Description      This function enable HID host and registers HID-Host with
328 **                  lower layers.
329 **
330 ** Returns          void
331 **
332 *******************************************************************************/
333 extern void BTA_HhEnable(tBTA_SEC sec_mask, tBTA_HH_CBACK *p_cback);
334 
335 /*******************************************************************************
336 **
337 ** Function         BTA_HhDeregister
338 **
339 ** Description      This function is called when the host is about power down.
340 **
341 ** Returns          void
342 **
343 *******************************************************************************/
344 extern void BTA_HhDisable(void);
345 
346 /*******************************************************************************
347 **
348 ** Function         BTA_HhOpen
349 **
350 ** Description      This function is called to start an inquiry and read SDP
351 **                  record of responding devices; connect to a device if only
352 **                  one active HID device is found.
353 **
354 ** Returns          void
355 **
356 *******************************************************************************/
357 extern void BTA_HhOpen (BD_ADDR dev_bda, tBTA_HH_PROTO_MODE mode,
358                         tBTA_SEC sec_mask);
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 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 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 device.
387 **
388 ** Returns          void
389 **
390 *******************************************************************************/
391 extern void BTA_HhGetProtoMode(UINT8 dev_handle);
392 /*******************************************************************************
393 **
394 ** Function         BTA_HhSetReport
395 **
396 ** Description      send SET_REPORT to device.
397 **
398 ** Returns          void
399 **
400 *******************************************************************************/
401 extern void BTA_HhSetReport(UINT8 dev_handle, tBTA_HH_RPT_TYPE r_type,
402                             BT_HDR *p_data);
403 
404 /*******************************************************************************
405 **
406 ** Function         BTA_HhGetReport
407 **
408 ** Description      Send a GET_REPORT to HID device.
409 **
410 ** Returns          void
411 **
412 *******************************************************************************/
413 extern void BTA_HhGetReport(UINT8 dev_handle, tBTA_HH_RPT_TYPE r_type,
414                             UINT8 rpt_id, UINT16 buf_size);
415 /*******************************************************************************
416 **
417 ** Function         BTA_HhSetIdle
418 **
419 ** Description      send SET_IDLE to device.
420 **
421 ** Returns          void
422 **
423 *******************************************************************************/
424 extern void BTA_HhSetIdle(UINT8 dev_handle, UINT16 idle_rate);
425 
426 /*******************************************************************************
427 **
428 ** Function         BTA_HhGetIdle
429 **
430 ** Description      Send a GET_IDLE to HID device.
431 **
432 ** Returns          void
433 **
434 *******************************************************************************/
435 extern void BTA_HhGetIdle(UINT8 dev_handle);
436 
437 /*******************************************************************************
438 **
439 ** Function         BTA_HhSendCtrl
440 **
441 ** Description      Send HID_CONTROL request to a HID device.
442 **
443 ** Returns          void
444 **
445 *******************************************************************************/
446 extern void BTA_HhSendCtrl(UINT8 dev_handle,
447                            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 dev_handle, UINT16 idle_rate);
459 
460 
461 /*******************************************************************************
462 **
463 ** Function         BTA_HhGetIdle
464 **
465 ** Description      Send a GET_IDLE from HID device.
466 **
467 ** Returns          void
468 **
469 *******************************************************************************/
470 extern void BTA_HhGetIdle(UINT8 dev_handle);
471 
472 /*******************************************************************************
473 **
474 ** Function         BTA_HhSendData
475 **
476 ** Description      Send DATA transaction to a HID device.
477 **
478 ** Returns          void
479 **
480 *******************************************************************************/
481 extern void BTA_HhSendData(UINT8 dev_handle, BD_ADDR dev_bda, 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 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(BD_ADDR bda, tBTA_HH_ATTR_MASK attr_mask,
506                          UINT8 sub_class, UINT8 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 dev_handle );
518 
519 /*******************************************************************************
520 **
521 **              Parsing Utility Functions
522 **
523 *******************************************************************************/
524 /*******************************************************************************
525 **
526 ** Function         BTA_HhParseBootRpt
527 **
528 ** Description      This utility function parse a boot mode report.
529 **
530 ** Returns          void
531 **
532 *******************************************************************************/
533 extern void BTA_HhParseBootRpt(tBTA_HH_BOOT_RPT *p_data, UINT8 *p_report,
534                                UINT16 report_len);
535 
536 #if BTA_HH_LE_INCLUDED == TRUE
537 /*******************************************************************************
538 **
539 ** Function         BTA_HhUpdateLeScanParam
540 **
541 ** Description      Update the scan paramteters if connected to a LE hid device as
542 **                  report host.
543 **
544 ** Returns          void
545 **
546 *******************************************************************************/
547 extern void BTA_HhUpdateLeScanParam(UINT8 dev_handle, UINT16 scan_int, UINT16 scan_win);
548 #endif
549 /* test commands */
550 extern void bta_hh_le_hid_read_rpt_clt_cfg(BD_ADDR bd_addr, UINT8 rpt_id);
551 
552 
553 
554 #ifdef __cplusplus
555 }
556 #endif
557 
558 #endif  /* BTA_HH_API_H */
559