1 /****************************************************************************** 2 * 3 * Copyright 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 (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_t 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 (BTA_HH_LE_INCLUDED == TRUE) 81 /* GATT_MAX_PHY_CHANNEL can not exceed 14 for the design of BTA HH */ 82 #if GATT_MAX_PHY_CHANNEL > 14 83 #define BTA_HH_LE_MAX_KNOWN 14 84 #else 85 #define BTA_HH_LE_MAX_KNOWN GATT_MAX_PHY_CHANNEL 86 #endif 87 88 #define BTA_HH_MAX_DEVICE (HID_HOST_MAX_DEVICES + BTA_HH_LE_MAX_KNOWN) 89 #else 90 #define BTA_HH_MAX_DEVICE HID_HOST_MAX_DEVICES 91 #endif 92 /* invalid device handle */ 93 #define BTA_HH_INVALID_HANDLE 0xff 94 95 /* type of protocol mode */ 96 #define BTA_HH_PROTO_RPT_MODE (0x00) 97 #define BTA_HH_PROTO_BOOT_MODE (0x01) 98 #define BTA_HH_PROTO_UNKNOWN (0xff) 99 typedef uint8_t tBTA_HH_PROTO_MODE; 100 101 enum { BTA_HH_KEYBD_RPT_ID = 1, BTA_HH_MOUSE_RPT_ID }; 102 typedef uint8_t 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_t 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, 136 BTA_HH_ERR_SEC 137 }; 138 typedef uint8_t tBTA_HH_STATUS; 139 140 #define BTA_HH_VIRTUAL_CABLE HID_VIRTUAL_CABLE 141 #define BTA_HH_NORMALLY_CONNECTABLE HID_NORMALLY_CONNECTABLE 142 #define BTA_HH_RECONN_INIT HID_RECONN_INIT 143 #define BTA_HH_SDP_DISABLE HID_SDP_DISABLE 144 #define BTA_HH_BATTERY_POWER HID_BATTERY_POWER 145 #define BTA_HH_REMOTE_WAKE HID_REMOTE_WAKE 146 #define BTA_HH_SUP_TOUT_AVLBL HID_SUP_TOUT_AVLBL 147 #define BTA_HH_SEC_REQUIRED HID_SEC_REQUIRED 148 typedef uint16_t tBTA_HH_ATTR_MASK; 149 150 /* supported type of device and corresponding application ID */ 151 typedef struct { 152 tBTA_HH_DEVT tod; /* type of device */ 153 uint8_t app_id; /* corresponding application ID */ 154 } tBTA_HH_SPT_TOD; 155 156 /* configuration struct */ 157 typedef struct { 158 uint8_t max_devt_spt; /* max number of types of devices spt */ 159 tBTA_HH_SPT_TOD* p_devt_list; /* supported types of device list */ 160 uint16_t sdp_db_size; 161 } tBTA_HH_CFG; 162 163 enum { 164 BTA_HH_RPTT_RESRV, /* reserved */ 165 BTA_HH_RPTT_INPUT, /* input report */ 166 BTA_HH_RPTT_OUTPUT, /* output report */ 167 BTA_HH_RPTT_FEATURE /* feature report */ 168 }; 169 typedef uint8_t tBTA_HH_RPT_TYPE; 170 171 /* HID_CONTROL operation code used in BTA_HhSendCtrl() 172 */ 173 enum { 174 BTA_HH_CTRL_NOP = 0 + HID_PAR_CONTROL_NOP, /* mapping from BTE */ 175 BTA_HH_CTRL_HARD_RESET, /* hard reset */ 176 BTA_HH_CTRL_SOFT_RESET, /* soft reset */ 177 BTA_HH_CTRL_SUSPEND, /* enter suspend */ 178 BTA_HH_CTRL_EXIT_SUSPEND, /* exit suspend */ 179 BTA_HH_CTRL_VIRTUAL_CABLE_UNPLUG /* virtual unplug */ 180 }; 181 typedef uint8_t tBTA_HH_TRANS_CTRL_TYPE; 182 183 typedef tHID_DEV_DSCP_INFO tBTA_HH_DEV_DESCR; 184 185 #define BTA_HH_SSR_PARAM_INVALID HID_SSR_PARAM_INVALID 186 187 /* id DI is not existing in remote device, vendor_id in tBTA_HH_DEV_DSCP_INFO 188 * will be set to 0xffff */ 189 #define BTA_HH_VENDOR_ID_INVALID 0xffff 190 191 /* report descriptor information */ 192 typedef struct { 193 uint16_t vendor_id; /* vendor ID */ 194 uint16_t product_id; /* product ID */ 195 uint16_t version; /* version */ 196 uint16_t ssr_max_latency; /* SSR max latency, BTA_HH_SSR_PARAM_INVALID if 197 unknown */ 198 uint16_t 199 ssr_min_tout; /* SSR min timeout, BTA_HH_SSR_PARAM_INVALID if unknown */ 200 uint8_t ctry_code; /*Country Code.*/ 201 #if (BTA_HH_LE_INCLUDED == TRUE) 202 #define BTA_HH_LE_REMOTE_WAKE 0x01 203 #define BTA_HH_LE_NORMAL_CONN 0x02 204 205 uint8_t flag; 206 #endif 207 tBTA_HH_DEV_DESCR descriptor; 208 } tBTA_HH_DEV_DSCP_INFO; 209 210 /* callback event data for BTA_HH_OPEN_EVT */ 211 typedef struct { 212 RawAddress bda; /* HID device bd address */ 213 tBTA_HH_STATUS status; /* operation status */ 214 uint8_t handle; /* device handle */ 215 #if (BTA_HH_LE_INCLUDED == TRUE) 216 bool le_hid; /* is LE devices? */ 217 bool 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_t 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_t this_char[6]; /* virtual key code */ 241 bool 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 bool caps_lock; /* is caps locked */ 248 bool num_lock; /* is Num key pressed */ 249 } tBTA_HH_KEYBD_RPT; 250 251 /* parsed boot mode mouse report */ 252 typedef struct { 253 uint8_t mouse_button; /* mouse button is clicked */ 254 int8_t delta_x; /* displacement x */ 255 int8_t 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_t 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_t idle_rate; /* GET_IDLE_EVT : idle rate */ 275 } rsp_data; 276 277 } tBTA_HH_HSDATA; 278 279 /* union of data associated with HD callback */ 280 typedef union { 281 tBTA_HH_DEV_INFO dev_info; /* BTA_HH_ADD_DEV_EVT, BTA_HH_RMV_DEV_EVT */ 282 tBTA_HH_CONN conn; /* BTA_HH_OPEN_EVT */ 283 tBTA_HH_CBDATA dev_status; /* BTA_HH_CLOSE_EVT, 284 BTA_HH_SET_PROTO_EVT 285 BTA_HH_SET_RPT_EVT 286 BTA_HH_SET_IDLE_EVT 287 BTA_HH_UPDATE_SCPP_EVT */ 288 289 tBTA_HH_STATUS status; /* BTA_HH_ENABLE_EVT */ 290 tBTA_HH_DEV_DSCP_INFO dscp_info; /* BTA_HH_GET_DSCP_EVT */ 291 tBTA_HH_HSDATA hs_data; /* GET_ transaction callback 292 BTA_HH_GET_RPT_EVT 293 BTA_HH_GET_PROTO_EVT 294 BTA_HH_GET_IDLE_EVT */ 295 } tBTA_HH; 296 297 /* BTA HH callback function */ 298 typedef void(tBTA_HH_CBACK)(tBTA_HH_EVT event, tBTA_HH* p_data); 299 300 /***************************************************************************** 301 * External Function Declarations 302 ****************************************************************************/ 303 304 /******************************************************************************* 305 * 306 * Function BTA_HhRegister 307 * 308 * Description This function enable HID host and registers HID-Host with 309 * lower layers. 310 * 311 * Returns void 312 * 313 ******************************************************************************/ 314 extern void BTA_HhEnable(tBTA_SEC sec_mask, tBTA_HH_CBACK* p_cback); 315 316 /******************************************************************************* 317 * 318 * Function BTA_HhDeregister 319 * 320 * Description This function is called when the host is about power down. 321 * 322 * Returns void 323 * 324 ******************************************************************************/ 325 extern void BTA_HhDisable(void); 326 327 /******************************************************************************* 328 * 329 * Function BTA_HhOpen 330 * 331 * Description This function is called to start an inquiry and read SDP 332 * record of responding devices; connect to a device if only 333 * one active HID device is found. 334 * 335 * Returns void 336 * 337 ******************************************************************************/ 338 extern void BTA_HhOpen(const RawAddress& dev_bda, tBTA_HH_PROTO_MODE mode, 339 tBTA_SEC sec_mask); 340 341 /******************************************************************************* 342 * 343 * Function BTA_HhClose 344 * 345 * Description This function disconnects the device. 346 * 347 * Returns void 348 * 349 ******************************************************************************/ 350 extern void BTA_HhClose(uint8_t dev_handle); 351 352 /******************************************************************************* 353 * 354 * Function BTA_HhSetProtoMode 355 * 356 * Description This function set the protocol mode at specified HID handle 357 * 358 * Returns void 359 * 360 ******************************************************************************/ 361 extern void BTA_HhSetProtoMode(uint8_t handle, tBTA_HH_PROTO_MODE t_type); 362 363 /******************************************************************************* 364 * 365 * Function BTA_HhGetProtoMode 366 * 367 * Description This function get the protocol mode of a specified HID 368 * device. 369 * 370 * Returns void 371 * 372 ******************************************************************************/ 373 extern void BTA_HhGetProtoMode(uint8_t dev_handle); 374 /******************************************************************************* 375 * 376 * Function BTA_HhSetReport 377 * 378 * Description send SET_REPORT to device. 379 * 380 * Returns void 381 * 382 ******************************************************************************/ 383 extern void BTA_HhSetReport(uint8_t dev_handle, tBTA_HH_RPT_TYPE r_type, 384 BT_HDR* p_data); 385 386 /******************************************************************************* 387 * 388 * Function BTA_HhGetReport 389 * 390 * Description Send a GET_REPORT to HID device. 391 * 392 * Returns void 393 * 394 ******************************************************************************/ 395 extern void BTA_HhGetReport(uint8_t dev_handle, tBTA_HH_RPT_TYPE r_type, 396 uint8_t rpt_id, uint16_t buf_size); 397 /******************************************************************************* 398 * 399 * Function BTA_HhSetIdle 400 * 401 * Description send SET_IDLE to device. 402 * 403 * Returns void 404 * 405 ******************************************************************************/ 406 extern void BTA_HhSetIdle(uint8_t dev_handle, uint16_t idle_rate); 407 408 /******************************************************************************* 409 * 410 * Function BTA_HhGetIdle 411 * 412 * Description Send a GET_IDLE to HID device. 413 * 414 * Returns void 415 * 416 ******************************************************************************/ 417 extern void BTA_HhGetIdle(uint8_t dev_handle); 418 419 /******************************************************************************* 420 * 421 * Function BTA_HhSendCtrl 422 * 423 * Description Send HID_CONTROL request to a HID device. 424 * 425 * Returns void 426 * 427 ******************************************************************************/ 428 extern void BTA_HhSendCtrl(uint8_t dev_handle, tBTA_HH_TRANS_CTRL_TYPE c_type); 429 430 /******************************************************************************* 431 * 432 * Function BTA_HhSetIdle 433 * 434 * Description send SET_IDLE to device. 435 * 436 * Returns void 437 * 438 ******************************************************************************/ 439 extern void BTA_HhSetIdle(uint8_t dev_handle, uint16_t idle_rate); 440 441 /******************************************************************************* 442 * 443 * Function BTA_HhGetIdle 444 * 445 * Description Send a GET_IDLE from HID device. 446 * 447 * Returns void 448 * 449 ******************************************************************************/ 450 extern void BTA_HhGetIdle(uint8_t dev_handle); 451 452 /******************************************************************************* 453 * 454 * Function BTA_HhSendData 455 * 456 * Description Send DATA transaction to a HID device. 457 * 458 * Returns void 459 * 460 ******************************************************************************/ 461 extern void BTA_HhSendData(uint8_t dev_handle, const RawAddress& dev_bda, 462 BT_HDR* p_buf); 463 464 /******************************************************************************* 465 * 466 * Function BTA_HhGetDscpInfo 467 * 468 * Description Get report descriptor of the device 469 * 470 * Returns void 471 * 472 ******************************************************************************/ 473 extern void BTA_HhGetDscpInfo(uint8_t dev_handle); 474 475 /******************************************************************************* 476 * Function BTA_HhAddDev 477 * 478 * Description Add a virtually cabled device into HID-Host device list 479 * to manage and assign a device handle for future API call, 480 * host applciation call this API at start-up to initialize its 481 * virtually cabled devices. 482 * 483 * Returns void 484 * 485 ******************************************************************************/ 486 extern void BTA_HhAddDev(const RawAddress& bda, tBTA_HH_ATTR_MASK attr_mask, 487 uint8_t sub_class, uint8_t app_id, 488 tBTA_HH_DEV_DSCP_INFO dscp_info); 489 /******************************************************************************* 490 * 491 * Function BTA_HhRemoveDev 492 * 493 * Description Remove a device from the HID host devices list. 494 * 495 * Returns void 496 * 497 ******************************************************************************/ 498 extern void BTA_HhRemoveDev(uint8_t dev_handle); 499 500 /******************************************************************************* 501 * 502 * Parsing Utility Functions 503 * 504 ******************************************************************************/ 505 /******************************************************************************* 506 * 507 * Function BTA_HhParseBootRpt 508 * 509 * Description This utility function parse a boot mode report. 510 * 511 * Returns void 512 * 513 ******************************************************************************/ 514 extern void BTA_HhParseBootRpt(tBTA_HH_BOOT_RPT* p_data, uint8_t* p_report, 515 uint16_t report_len); 516 517 /* test commands */ 518 extern void bta_hh_le_hid_read_rpt_clt_cfg(const RawAddress& bd_addr, 519 uint8_t rpt_id); 520 521 #endif /* BTA_HH_API_H */ 522