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 BTA_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 *******************************************************************************/ 344 BTA_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 *******************************************************************************/ 357 BTA_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 *******************************************************************************/ 369 BTA_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 *******************************************************************************/ 380 BTA_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 *******************************************************************************/ 391 BTA_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 *******************************************************************************/ 401 BTA_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 *******************************************************************************/ 413 BTA_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 *******************************************************************************/ 424 BTA_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 *******************************************************************************/ 435 BTA_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 *******************************************************************************/ 446 BTA_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 *******************************************************************************/ 458 BTA_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 *******************************************************************************/ 470 BTA_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 *******************************************************************************/ 481 BTA_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 *******************************************************************************/ 492 BTA_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 *******************************************************************************/ 505 BTA_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 *******************************************************************************/ 517 BTA_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 *******************************************************************************/ 533 BTA_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 *******************************************************************************/ 547 BTA_API extern void BTA_HhUpdateLeScanParam(UINT8 dev_handle, UINT16 scan_int, UINT16 scan_win); 548 #endif 549 /* test commands */ 550 BTA_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