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/bta_api.h" 22 #include "stack/hidh_api.h" 23 #if defined(BTA_HH_INCLUDED) && (BTA_HH_INCLUDED == TRUE) 24 25 #if (defined BTA_HH_LE_INCLUDED && BTA_HH_LE_INCLUDED == TRUE) 26 #include "stack/gatt_api.h" 27 #endif 28 29 /***************************************************************************** 30 ** Constants and Type Definitions 31 *****************************************************************************/ 32 #ifndef BTA_HH_DEBUG 33 #define BTA_HH_DEBUG TRUE 34 #endif 35 36 #ifndef BTA_HH_SSR_MAX_LATENCY_DEF 37 #define BTA_HH_SSR_MAX_LATENCY_DEF 800 /* 500 ms*/ 38 #endif 39 40 #ifndef BTA_HH_SSR_MIN_TOUT_DEF 41 #define BTA_HH_SSR_MIN_TOUT_DEF 2 42 #endif 43 44 /* BTA HID Host callback events */ 45 #define BTA_HH_ENABLE_EVT 0 /* HH enabled */ 46 #define BTA_HH_DISABLE_EVT 1 /* HH disabled */ 47 #define BTA_HH_OPEN_EVT 2 /* connection opened */ 48 #define BTA_HH_CLOSE_EVT 3 /* connection closed */ 49 #define BTA_HH_GET_RPT_EVT 4 /* BTA_HhGetReport callback */ 50 #define BTA_HH_SET_RPT_EVT 5 /* BTA_HhSetReport callback */ 51 #define BTA_HH_GET_PROTO_EVT 6 /* BTA_GetProtoMode callback */ 52 #define BTA_HH_SET_PROTO_EVT 7 /* BTA_HhSetProtoMode callback */ 53 #define BTA_HH_GET_IDLE_EVT 8 /* BTA_HhGetIdle comes callback */ 54 #define BTA_HH_SET_IDLE_EVT 9 /* BTA_HhSetIdle finish callback */ 55 #define BTA_HH_GET_DSCP_EVT 10 /* Get report descriptor */ 56 #define BTA_HH_ADD_DEV_EVT 11 /* Add Device callback */ 57 #define BTA_HH_RMV_DEV_EVT 12 /* remove device finished */ 58 #define BTA_HH_VC_UNPLUG_EVT 13 /* virtually unplugged */ 59 #define BTA_HH_DATA_EVT 15 60 #define BTA_HH_API_ERR_EVT 16 /* API error is caught */ 61 #define BTA_HH_UPDATE_SCPP_EVT 17 /* update scan paramter complete */ 62 #define BTA_HH_DATA_IND_EVT 18 /* Data on interrupt channel */ 63 64 typedef UINT16 tBTA_HH_EVT; 65 66 /* application ID(none-zero) for each type of device */ 67 #define BTA_HH_APP_ID_MI 1 68 #define BTA_HH_APP_ID_KB 2 69 #define BTA_HH_APP_ID_RMC 3 70 #define BTA_HH_APP_ID_3DSG 4 71 #define BTA_HH_APP_ID_JOY 5 72 #define BTA_HH_APP_ID_GPAD 6 73 #define BTA_HH_APP_ID_LE 0xff 74 75 /* defined the minimum offset */ 76 #define BTA_HH_MIN_OFFSET L2CAP_MIN_OFFSET+1 77 78 /* HID_HOST_MAX_DEVICES can not exceed 15 for th design of BTA HH */ 79 #define BTA_HH_IDX_INVALID 0xff 80 #define BTA_HH_MAX_KNOWN HID_HOST_MAX_DEVICES 81 82 #if (defined BTA_HH_LE_INCLUDED && BTA_HH_LE_INCLUDED == TRUE) 83 /* GATT_MAX_PHY_CHANNEL can not exceed 14 for the design of BTA HH */ 84 #define BTA_HH_LE_MAX_KNOWN GATT_MAX_PHY_CHANNEL 85 #define BTA_HH_MAX_DEVICE (HID_HOST_MAX_DEVICES + GATT_MAX_PHY_CHANNEL) 86 #else 87 #define BTA_HH_MAX_DEVICE HID_HOST_MAX_DEVICES 88 #endif 89 /* invalid device handle */ 90 #define BTA_HH_INVALID_HANDLE 0xff 91 92 /* type of protocol mode */ 93 #define BTA_HH_PROTO_RPT_MODE (0x00) 94 #define BTA_HH_PROTO_BOOT_MODE (0x01) 95 #define BTA_HH_PROTO_UNKNOWN (0xff) 96 typedef UINT8 tBTA_HH_PROTO_MODE; 97 98 enum { 99 BTA_HH_KEYBD_RPT_ID = 1, 100 BTA_HH_MOUSE_RPT_ID 101 }; 102 typedef UINT8 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 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, /* connection handle error */ 136 BTA_HH_ERR_SEC, /* encryption error */ 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 tBTA_HH_DEVT tod; /* type of device */ 154 UINT8 app_id; /* corresponding application ID */ 155 } tBTA_HH_SPT_TOD; 156 157 /* configuration struct */ 158 typedef struct { 159 UINT8 max_devt_spt; /* max number of types of devices spt */ 160 tBTA_HH_SPT_TOD *p_devt_list; /* supported types of device list */ 161 UINT16 sdp_db_size; 162 } tBTA_HH_CFG; 163 164 enum { 165 BTA_HH_RPTT_RESRV, /* reserved */ 166 BTA_HH_RPTT_INPUT, /* input report */ 167 BTA_HH_RPTT_OUTPUT, /* output report */ 168 BTA_HH_RPTT_FEATURE /* feature report */ 169 }; 170 typedef UINT8 tBTA_HH_RPT_TYPE; 171 172 /* HID_CONTROL operation code used in BTA_HhSendCtrl() 173 */ 174 enum { 175 BTA_HH_CTRL_NOP = 0 + HID_PAR_CONTROL_NOP ,/* mapping from BTE */ 176 BTA_HH_CTRL_HARD_RESET, /* hard reset */ 177 BTA_HH_CTRL_SOFT_RESET, /* soft reset */ 178 BTA_HH_CTRL_SUSPEND, /* enter suspend */ 179 BTA_HH_CTRL_EXIT_SUSPEND, /* exit suspend */ 180 BTA_HH_CTRL_VIRTUAL_CABLE_UNPLUG /* virtual unplug */ 181 }; 182 typedef UINT8 tBTA_HH_TRANS_CTRL_TYPE; 183 184 typedef tHID_DEV_DSCP_INFO tBTA_HH_DEV_DESCR; 185 186 #define BTA_HH_SSR_PARAM_INVALID HID_SSR_PARAM_INVALID 187 188 /* id DI is not existing in remote device, vendor_id in tBTA_HH_DEV_DSCP_INFO will be set to 0xffff */ 189 #define BTA_HH_VENDOR_ID_INVALID 0xffff 190 191 192 /* report descriptor information */ 193 typedef struct { 194 UINT16 vendor_id; /* vendor ID */ 195 UINT16 product_id; /* product ID */ 196 UINT16 version; /* version */ 197 UINT16 ssr_max_latency; /* SSR max latency, BTA_HH_SSR_PARAM_INVALID if unknown */ 198 UINT16 ssr_min_tout; /* SSR min timeout, BTA_HH_SSR_PARAM_INVALID if unknown */ 199 UINT8 ctry_code; /*Country Code.*/ 200 #if (defined BTA_HH_LE_INCLUDED && BTA_HH_LE_INCLUDED == TRUE) 201 #define BTA_HH_LE_REMOTE_WAKE 0x01 202 #define BTA_HH_LE_NORMAL_CONN 0x02 203 204 UINT8 flag; 205 #endif 206 tBTA_HH_DEV_DESCR descriptor; 207 } tBTA_HH_DEV_DSCP_INFO; 208 209 /* callback event data for BTA_HH_OPEN_EVT */ 210 typedef struct { 211 BD_ADDR bda; /* HID device bd address */ 212 tBTA_HH_STATUS status; /* operation status */ 213 UINT8 handle; /* device handle */ 214 BOOLEAN is_orig; /* indicate if host initiate connection */ 215 #if (defined BTA_HH_LE_INCLUDED && BTA_HH_LE_INCLUDED == TRUE) 216 BOOLEAN le_hid; /* is LE devices? */ 217 BOOLEAN 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 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 this_char[6]; /* virtual key code */ 241 BOOLEAN 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 BOOLEAN caps_lock; /* is caps locked */ 248 BOOLEAN num_lock; /* is Num key pressed */ 249 } tBTA_HH_KEYBD_RPT; 250 251 /* parsed boot mode mouse report */ 252 typedef struct { 253 UINT8 mouse_button; /* mouse button is clicked */ 254 INT8 delta_x; /* displacement x */ 255 INT8 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 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 idle_rate; /* GET_IDLE_EVT : idle rate */ 275 } rsp_data; 276 277 } tBTA_HH_HSDATA; 278 279 280 /* upper layer send data */ 281 typedef struct { 282 tBTA_HH_STATUS status; /* handshake status */ 283 UINT8 handle; /* device handle */ 284 UINT8 reason; /* send data failed reason */ 285 } tBTA_HH_API_SENDDATA; 286 287 /* interrupt channel data */ 288 typedef struct { 289 tBTA_HH_STATUS status; /* handshake status */ 290 UINT8 handle; /* device handle */ 291 tBTA_HH_PROTO_MODE proto_mode; /* protocol mode */ 292 BT_HDR *p_data; /* DATA_EVT : feature report data */ 293 } tBTA_HH_INTDATA; 294 295 /* union of data associated with HD callback */ 296 typedef union { 297 tBTA_HH_DEV_INFO dev_info; /* BTA_HH_ADD_DEV_EVT, BTA_HH_RMV_DEV_EVT */ 298 tBTA_HH_CONN conn; /* BTA_HH_OPEN_EVT */ 299 tBTA_HH_CBDATA dev_status; /* BTA_HH_CLOSE_EVT, 300 BTA_HH_SET_PROTO_EVT 301 BTA_HH_SET_RPT_EVT 302 BTA_HH_SET_IDLE_EVT 303 BTA_HH_UPDATE_SCPP_EVT */ 304 305 tBTA_HH_STATUS status; /* BTA_HH_ENABLE_EVT */ 306 tBTA_HH_DEV_DSCP_INFO dscp_info; /* BTA_HH_GET_DSCP_EVT */ 307 tBTA_HH_HSDATA hs_data; /* GET_ transaction callback 308 BTA_HH_GET_RPT_EVT 309 BTA_HH_GET_PROTO_EVT 310 BTA_HH_GET_IDLE_EVT */ 311 tBTA_HH_API_SENDDATA send_data; /* BTA_HH_DATA_EVT */ 312 tBTA_HH_INTDATA int_data; /* BTA_HH_DATA_IND_EVT */ 313 } tBTA_HH; 314 315 /* BTA HH callback function */ 316 typedef void (tBTA_HH_CBACK)(tBTA_HH_EVT event, tBTA_HH *p_data); 317 318 319 /***************************************************************************** 320 ** External Function Declarations 321 *****************************************************************************/ 322 #ifdef __cplusplus 323 extern "C" 324 { 325 #endif 326 327 /******************************************************************************* 328 ** 329 ** Function BTA_HhRegister 330 ** 331 ** Description This function enable HID host and registers HID-Host with 332 ** lower layers. 333 ** 334 ** Returns void 335 ** 336 *******************************************************************************/ 337 extern void BTA_HhEnable(tBTA_SEC sec_mask, tBTA_HH_CBACK *p_cback); 338 339 /******************************************************************************* 340 ** 341 ** Function BTA_HhDeregister 342 ** 343 ** Description This function is called when the host is about power down. 344 ** 345 ** Returns void 346 ** 347 *******************************************************************************/ 348 extern void BTA_HhDisable(void); 349 350 /******************************************************************************* 351 ** 352 ** Function BTA_HhOpen 353 ** 354 ** Description This function is called to start an inquiry and read SDP 355 ** record of responding devices; connect to a device if only 356 ** one active HID device is found. 357 ** 358 ** Returns void 359 ** 360 *******************************************************************************/ 361 extern void BTA_HhOpen (BD_ADDR dev_bda, tBTA_HH_PROTO_MODE mode, 362 tBTA_SEC sec_mask); 363 364 /******************************************************************************* 365 ** 366 ** Function BTA_HhClose 367 ** 368 ** Description This function disconnects the device. 369 ** 370 ** Returns void 371 ** 372 *******************************************************************************/ 373 extern void BTA_HhClose(UINT8 dev_handle); 374 375 /******************************************************************************* 376 ** 377 ** Function BTA_HhSetProtoMode 378 ** 379 ** Description This function set the protocol mode at specified HID handle 380 ** 381 ** Returns void 382 ** 383 *******************************************************************************/ 384 extern void BTA_HhSetProtoMode(UINT8 handle, tBTA_HH_PROTO_MODE t_type); 385 386 /******************************************************************************* 387 ** 388 ** Function BTA_HhGetProtoMode 389 ** 390 ** Description This function get the protocol mode of a specified HID device. 391 ** 392 ** Returns void 393 ** 394 *******************************************************************************/ 395 extern void BTA_HhGetProtoMode(UINT8 dev_handle); 396 /******************************************************************************* 397 ** 398 ** Function BTA_HhSetReport 399 ** 400 ** Description send SET_REPORT to device. 401 ** 402 ** Returns void 403 ** 404 *******************************************************************************/ 405 extern void BTA_HhSetReport(UINT8 dev_handle, tBTA_HH_RPT_TYPE r_type, 406 BT_HDR *p_data); 407 408 /******************************************************************************* 409 ** 410 ** Function BTA_HhGetReport 411 ** 412 ** Description Send a GET_REPORT to HID device. 413 ** 414 ** Returns void 415 ** 416 *******************************************************************************/ 417 extern void BTA_HhGetReport(UINT8 dev_handle, tBTA_HH_RPT_TYPE r_type, 418 UINT8 rpt_id, UINT16 buf_size); 419 /******************************************************************************* 420 ** 421 ** Function BTA_HhSetIdle 422 ** 423 ** Description send SET_IDLE to device. 424 ** 425 ** Returns void 426 ** 427 *******************************************************************************/ 428 extern void BTA_HhSetIdle(UINT8 dev_handle, UINT16 idle_rate); 429 430 /******************************************************************************* 431 ** 432 ** Function BTA_HhGetIdle 433 ** 434 ** Description Send a GET_IDLE to HID device. 435 ** 436 ** Returns void 437 ** 438 *******************************************************************************/ 439 extern void BTA_HhGetIdle(UINT8 dev_handle); 440 441 /******************************************************************************* 442 ** 443 ** Function BTA_HhSendCtrl 444 ** 445 ** Description Send HID_CONTROL request to a HID device. 446 ** 447 ** Returns void 448 ** 449 *******************************************************************************/ 450 extern void BTA_HhSendCtrl(UINT8 dev_handle, 451 tBTA_HH_TRANS_CTRL_TYPE c_type); 452 453 /******************************************************************************* 454 ** 455 ** Function BTA_HhSetIdle 456 ** 457 ** Description send SET_IDLE to device. 458 ** 459 ** Returns void 460 ** 461 *******************************************************************************/ 462 extern void BTA_HhSetIdle(UINT8 dev_handle, UINT16 idle_rate); 463 464 465 /******************************************************************************* 466 ** 467 ** Function BTA_HhGetIdle 468 ** 469 ** Description Send a GET_IDLE from HID device. 470 ** 471 ** Returns void 472 ** 473 *******************************************************************************/ 474 extern void BTA_HhGetIdle(UINT8 dev_handle); 475 476 /******************************************************************************* 477 ** 478 ** Function BTA_HhSendData 479 ** 480 ** Description Send DATA transaction to a HID device. 481 ** 482 ** Returns void 483 ** 484 *******************************************************************************/ 485 extern void BTA_HhSendData(UINT8 dev_handle, BD_ADDR dev_bda, BT_HDR *p_buf); 486 487 /******************************************************************************* 488 ** 489 ** Function BTA_HhGetDscpInfo 490 ** 491 ** Description Get report descriptor of the device 492 ** 493 ** Returns void 494 ** 495 *******************************************************************************/ 496 extern void BTA_HhGetDscpInfo(UINT8 dev_handle); 497 498 /******************************************************************************* 499 ** Function BTA_HhAddDev 500 ** 501 ** Description Add a virtually cabled device into HID-Host device list 502 ** to manage and assign a device handle for future API call, 503 ** host applciation call this API at start-up to initialize its 504 ** virtually cabled devices. 505 ** 506 ** Returns void 507 ** 508 *******************************************************************************/ 509 extern void BTA_HhAddDev(BD_ADDR bda, tBTA_HH_ATTR_MASK attr_mask, 510 UINT8 sub_class, UINT8 app_id, 511 tBTA_HH_DEV_DSCP_INFO dscp_info); 512 /******************************************************************************* 513 ** 514 ** Function BTA_HhRemoveDev 515 ** 516 ** Description Remove a device from the HID host devices list. 517 ** 518 ** Returns void 519 ** 520 *******************************************************************************/ 521 extern void BTA_HhRemoveDev(UINT8 dev_handle ); 522 523 /******************************************************************************* 524 ** 525 ** Parsing Utility Functions 526 ** 527 *******************************************************************************/ 528 /******************************************************************************* 529 ** 530 ** Function BTA_HhParseBootRpt 531 ** 532 ** Description This utility function parse a boot mode report. 533 ** 534 ** Returns void 535 ** 536 *******************************************************************************/ 537 extern void BTA_HhParseBootRpt(tBTA_HH_BOOT_RPT *p_data, UINT8 *p_report, 538 UINT16 report_len); 539 540 #if BTA_HH_LE_INCLUDED == TRUE 541 /******************************************************************************* 542 ** 543 ** Function BTA_HhUpdateLeScanParam 544 ** 545 ** Description Update the scan paramteters if connected to a LE hid device as 546 ** report host. 547 ** 548 ** Returns void 549 ** 550 *******************************************************************************/ 551 extern void BTA_HhUpdateLeScanParam(UINT8 dev_handle, UINT16 scan_int, UINT16 scan_win); 552 #endif 553 /* test commands */ 554 extern void bta_hh_le_hid_read_rpt_clt_cfg(BD_ADDR bd_addr, UINT8 rpt_id); 555 556 557 558 #ifdef __cplusplus 559 } 560 #endif 561 562 #endif ///defined(BTA_HH_INCLUDED) && (BTA_HH_INCLUDED == TRUE) 563 564 565 #endif /* BTA_HH_API_H */ 566
