bta_hh_api.h revision 2e7fa68bfd9723b7ec7b6b0b128d89f31a2e06ee 
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
62typedef 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)
94typedef UINT8   tBTA_HH_PROTO_MODE;
95
96enum
97{
98    BTA_HH_KEYBD_RPT_ID  =               1,
99    BTA_HH_MOUSE_RPT_ID
100};
101typedef 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
115typedef UINT8  tBTA_HH_DEVT;
116
117enum
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};
138typedef 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
149typedef UINT16 tBTA_HH_ATTR_MASK;
150
151/* supported type of device and corresponding application ID */
152typedef 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 */
159typedef 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
166enum
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};
173typedef UINT8 tBTA_HH_RPT_TYPE;
174
175/* HID_CONTROL operation code used in BTA_HhSendCtrl()
176*/
177enum
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};
186typedef UINT8 tBTA_HH_TRANS_CTRL_TYPE;
187
188typedef 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 */
197typedef 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 */
215typedef 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
227typedef tBTA_HH_CONN tBTA_HH_DEV_INFO;
228
229/* callback event data */
230typedef struct
231{
232    tBTA_HH_STATUS              status;     /* operation status         */
233    UINT8                       handle;     /* device handle            */
234} tBTA_HH_CBDATA;
235
236enum
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 */
246typedef 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 */
260typedef 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 */
268typedef 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 */
279typedef 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 */
293typedef 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 */
312typedef void (tBTA_HH_CBACK) (tBTA_HH_EVT event, tBTA_HH *p_data);
313
314
315/*****************************************************************************
316**  External Function Declarations
317*****************************************************************************/
318#ifdef __cplusplus
319extern "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*******************************************************************************/
333BTA_API 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*******************************************************************************/
344BTA_API 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*******************************************************************************/
357BTA_API 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*******************************************************************************/
369BTA_API 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*******************************************************************************/
380BTA_API 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*******************************************************************************/
391BTA_API 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*******************************************************************************/
401BTA_API 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*******************************************************************************/
413BTA_API 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*******************************************************************************/
424BTA_API 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*******************************************************************************/
435BTA_API 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*******************************************************************************/
446BTA_API 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*******************************************************************************/
458BTA_API 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*******************************************************************************/
470BTA_API 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*******************************************************************************/
481BTA_API 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*******************************************************************************/
492BTA_API 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*******************************************************************************/
505BTA_API 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*******************************************************************************/
517BTA_API 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*******************************************************************************/
533BTA_API 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*******************************************************************************/
547BTA_API extern void BTA_HhUpdateLeScanParam(UINT8 dev_handle, UINT16 scan_int, UINT16 scan_win);
548#endif
549/* test commands */
550BTA_API 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