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