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