1 /****************************************************************************** 2 * 3 * Copyright 1999-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 19 /****************************************************************************** 20 * 21 * This file contains the Bluetooth Manager (BTM) API function external 22 * definitions. 23 * 24 ******************************************************************************/ 25 #ifndef BTM_BLE_API_H 26 #define BTM_BLE_API_H 27 28 #include <base/callback_forward.h> 29 #include <hardware/bt_common_types.h> 30 #include <memory> 31 #include "bt_common.h" 32 #include "btm_api.h" 33 #include "btm_ble_api_types.h" 34 #include "osi/include/alarm.h" 35 36 /***************************************************************************** 37 * EXTERNAL FUNCTION DECLARATIONS 38 ****************************************************************************/ 39 /******************************************************************************* 40 * 41 * Function BTM_SecAddBleDevice 42 * 43 * Description Add/modify device. This function will be normally called 44 * during host startup to restore all required information 45 * for a LE device stored in the NVRAM. 46 * 47 * Parameters: bd_addr - BD address of the peer 48 * bd_name - Name of the peer device. NULL if unknown. 49 * dev_type - Remote device's device type. 50 * addr_type - LE device address type. 51 * 52 * Returns true if added OK, else false 53 * 54 ******************************************************************************/ 55 extern bool BTM_SecAddBleDevice(const RawAddress& bd_addr, BD_NAME bd_name, 56 tBT_DEVICE_TYPE dev_type, 57 tBLE_ADDR_TYPE addr_type); 58 59 /******************************************************************************* 60 * 61 * Function BTM_SecAddBleKey 62 * 63 * Description Add/modify LE device information. This function will be 64 * normally called during host startup to restore all required 65 * information stored in the NVRAM. 66 * 67 * Parameters: bd_addr - BD address of the peer 68 * p_le_key - LE key values. 69 * key_type - LE SMP key type. 70 * 71 * Returns true if added OK, else false 72 * 73 ******************************************************************************/ 74 extern bool BTM_SecAddBleKey(const RawAddress& bd_addr, 75 tBTM_LE_KEY_VALUE* p_le_key, 76 tBTM_LE_KEY_TYPE key_type); 77 78 /** 79 * This function is called to set scan parameters. |cb| is called with operation 80 * status 81 **/ 82 extern void BTM_BleSetScanParams(uint32_t scan_interval, uint32_t scan_window, 83 tBLE_SCAN_MODE scan_type, 84 base::Callback<void(uint8_t)> cb); 85 86 /******************************************************************************* 87 * 88 * Function BTM_BleGetVendorCapabilities 89 * 90 * Description This function reads local LE features 91 * 92 * Parameters p_cmn_vsc_cb : Locala LE capability structure 93 * 94 * Returns void 95 * 96 ******************************************************************************/ 97 extern void BTM_BleGetVendorCapabilities(tBTM_BLE_VSC_CB* p_cmn_vsc_cb); 98 /******************************************************************************* 99 * 100 * Function BTM_BleSetStorageConfig 101 * 102 * Description This function is called to setup storage configuration and 103 * setup callbacks. 104 * 105 * Parameters uint8_t batch_scan_full_max -Batch scan full maximum 106 uint8_t batch_scan_trunc_max - Batch scan truncated value 107 maximum 108 uint8_t batch_scan_notify_threshold - Threshold value 109 cb - Setup callback 110 tBTM_BLE_SCAN_THRESHOLD_CBACK *p_thres_cback -Threshold 111 callback 112 void *p_ref - Reference value 113 * 114 * 115 ******************************************************************************/ 116 extern void BTM_BleSetStorageConfig( 117 uint8_t batch_scan_full_max, uint8_t batch_scan_trunc_max, 118 uint8_t batch_scan_notify_threshold, 119 base::Callback<void(uint8_t /* status */)> cb, 120 tBTM_BLE_SCAN_THRESHOLD_CBACK* p_thres_cback, tBTM_BLE_REF_VALUE ref_value); 121 122 /* This function is called to enable batch scan */ 123 extern void BTM_BleEnableBatchScan( 124 tBTM_BLE_BATCH_SCAN_MODE scan_mode, uint32_t scan_interval, 125 uint32_t scan_window, tBTM_BLE_DISCARD_RULE discard_rule, 126 tBLE_ADDR_TYPE addr_type, base::Callback<void(uint8_t /* status */)> cb); 127 128 /* This function is called to disable batch scanning */ 129 extern void BTM_BleDisableBatchScan( 130 base::Callback<void(uint8_t /* status */)> cb); 131 132 /* This function is called to read batch scan reports */ 133 extern void BTM_BleReadScanReports(tBLE_SCAN_MODE scan_mode, 134 tBTM_BLE_SCAN_REP_CBACK cb); 135 136 /* This function is called to setup the callback for tracking */ 137 extern void BTM_BleTrackAdvertiser(tBTM_BLE_TRACK_ADV_CBACK* p_track_cback, 138 tBTM_BLE_REF_VALUE ref_value); 139 140 /******************************************************************************* 141 * 142 * Function BTM_BleObserve 143 * 144 * Description This procedure keep the device listening for advertising 145 * events from a broadcast device. 146 * 147 * Parameters start: start or stop observe. 148 * 149 * Returns void 150 * 151 ******************************************************************************/ 152 extern tBTM_STATUS BTM_BleObserve(bool start, uint8_t duration, 153 tBTM_INQ_RESULTS_CB* p_results_cb, 154 tBTM_CMPL_CB* p_cmpl_cb); 155 156 /** Returns local device encryption root (ER) */ 157 const Octet16& BTM_GetDeviceEncRoot(); 158 159 /** Returns local device identity root (IR) */ 160 extern const Octet16& BTM_GetDeviceIDRoot(); 161 162 /** Return local device DHK. */ 163 extern const Octet16& BTM_GetDeviceDHK(); 164 165 /******************************************************************************* 166 * 167 * Function BTM_SecurityGrant 168 * 169 * Description This function is called to grant security process. 170 * 171 * Parameters bd_addr - peer device bd address. 172 * res - result of the operation BTM_SUCCESS if success. 173 * Otherwise, BTM_REPEATED_ATTEMPTS is too many 174 * attempts. 175 * 176 * Returns None 177 * 178 ******************************************************************************/ 179 extern void BTM_SecurityGrant(const RawAddress& bd_addr, uint8_t res); 180 181 /******************************************************************************* 182 * 183 * Function BTM_BlePasskeyReply 184 * 185 * Description This function is called after Security Manager submitted 186 * passkey request to the application. 187 * 188 * Parameters: bd_addr - Address of the device for which passkey was 189 * requested 190 * res - result of the operation SMP_SUCCESS if success 191 * passkey - numeric value in the range of 192 * BTM_MIN_PASSKEY_VAL(0) - 193 * BTM_MAX_PASSKEY_VAL(999999(0xF423F)). 194 * 195 ******************************************************************************/ 196 extern void BTM_BlePasskeyReply(const RawAddress& bd_addr, uint8_t res, 197 uint32_t passkey); 198 199 /******************************************************************************* 200 * 201 * Function BTM_BleConfirmReply 202 * 203 * Description This function is called after Security Manager submitted 204 * numeric comparison request to the application. 205 * 206 * Parameters: bd_addr - Address of the device with which numeric 207 * comparison was requested 208 * res - comparison result BTM_SUCCESS if success 209 * 210 ******************************************************************************/ 211 extern void BTM_BleConfirmReply(const RawAddress& bd_addr, uint8_t res); 212 213 /******************************************************************************* 214 * 215 * Function BTM_LeOobDataReply 216 * 217 * Description This function is called to provide the OOB data for 218 * SMP in response to BTM_LE_OOB_REQ_EVT 219 * 220 * Parameters: bd_addr - Address of the peer device 221 * res - result of the operation SMP_SUCCESS if success 222 * p_data - simple pairing Randomizer C. 223 * 224 ******************************************************************************/ 225 extern void BTM_BleOobDataReply(const RawAddress& bd_addr, uint8_t res, 226 uint8_t len, uint8_t* p_data); 227 228 /******************************************************************************* 229 * 230 * Function BTM_BleSecureConnectionOobDataReply 231 * 232 * Description This function is called to provide the OOB data for 233 * SMP in response to BTM_LE_OOB_REQ_EVT when secure connection 234 * data is available 235 * 236 * Parameters: bd_addr - Address of the peer device 237 * p_c - pointer to Confirmation 238 * p_r - pointer to Randomizer. 239 * 240 ******************************************************************************/ 241 extern void BTM_BleSecureConnectionOobDataReply(const RawAddress& bd_addr, 242 uint8_t* p_c, uint8_t* p_r); 243 244 /******************************************************************************* 245 * 246 * Function BTM_BleDataSignature 247 * 248 * Description This function is called to sign the data using AES128 CMAC 249 * algorith. 250 * 251 * Parameter bd_addr: target device the data to be signed for. 252 * p_text: singing data 253 * len: length of the signing data 254 * signature: output parameter where data signature is going to 255 * be stored. 256 * 257 * Returns true if signing sucessul, otherwise false. 258 * 259 ******************************************************************************/ 260 extern bool BTM_BleDataSignature(const RawAddress& bd_addr, uint8_t* p_text, 261 uint16_t len, BLE_SIGNATURE signature); 262 263 /******************************************************************************* 264 * 265 * Function BTM_BleVerifySignature 266 * 267 * Description This function is called to verify the data signature 268 * 269 * Parameter bd_addr: target device the data to be signed for. 270 * p_orig: original data before signature. 271 * len: length of the signing data 272 * counter: counter used when doing data signing 273 * p_comp: signature to be compared against. 274 275 * Returns true if signature verified correctly; otherwise false. 276 * 277 ******************************************************************************/ 278 extern bool BTM_BleVerifySignature(const RawAddress& bd_addr, uint8_t* p_orig, 279 uint16_t len, uint32_t counter, 280 uint8_t* p_comp); 281 282 /******************************************************************************* 283 * 284 * Function BTM_ReadConnectionAddr 285 * 286 * Description Read the local device random address. 287 * 288 * Returns void 289 * 290 ******************************************************************************/ 291 extern void BTM_ReadConnectionAddr(const RawAddress& remote_bda, 292 RawAddress& local_conn_addr, 293 tBLE_ADDR_TYPE* p_addr_type); 294 295 /******************************************************************************* 296 * 297 * Function BTM_IsBleConnection 298 * 299 * Description This function is called to check if the connection handle 300 * for an LE link 301 * 302 * Returns true if connection is LE link, otherwise false. 303 * 304 ******************************************************************************/ 305 extern bool BTM_IsBleConnection(uint16_t conn_handle); 306 307 /******************************************************************************* 308 * 309 * Function BTM_ReadRemoteConnectionAddr 310 * 311 * Description Read the remote device address currently used. 312 * 313 * Returns void 314 * 315 ******************************************************************************/ 316 extern bool BTM_ReadRemoteConnectionAddr(const RawAddress& pseudo_addr, 317 RawAddress& conn_addr, 318 tBLE_ADDR_TYPE* p_addr_type); 319 320 /******************************************************************************* 321 * 322 * Function BTM_BleLoadLocalKeys 323 * 324 * Description Local local identity key, encryption root or sign counter. 325 * 326 * Parameters: key_type: type of key, can be BTM_BLE_KEY_TYPE_ID, 327 * BTM_BLE_KEY_TYPE_ER 328 * or BTM_BLE_KEY_TYPE_COUNTER. 329 * p_key: pointer to the key. 330 * 331 * Returns non2. 332 * 333 ******************************************************************************/ 334 extern void BTM_BleLoadLocalKeys(uint8_t key_type, tBTM_BLE_LOCAL_KEYS* p_key); 335 336 #include "stack/btm/btm_ble_bgconn.h" 337 338 /******************************************************** 339 * 340 * Function BTM_BleSetPrefConnParams 341 * 342 * Description Set a peripheral's preferred connection parameters. When 343 * any of the value does not want to be updated while others 344 * do, use BTM_BLE_CONN_PARAM_UNDEF for the ones want to 345 * leave untouched. 346 * 347 * Parameters: bd_addr - BD address of the peripheral 348 * min_conn_int - minimum preferred connection interval 349 * max_conn_int - maximum preferred connection interval 350 * slave_latency - preferred slave latency 351 * supervision_tout - preferred supervision timeout 352 * 353 * Returns void 354 * 355 ******************************************************************************/ 356 extern void BTM_BleSetPrefConnParams(const RawAddress& bd_addr, 357 uint16_t min_conn_int, 358 uint16_t max_conn_int, 359 uint16_t slave_latency, 360 uint16_t supervision_tout); 361 362 /****************************************************************************** 363 * 364 * Function BTM_BleReadControllerFeatures 365 * 366 * Description Reads BLE specific controller features 367 * 368 * Parameters: tBTM_BLE_CTRL_FEATURES_CBACK : Callback to notify when 369 * features are read 370 * 371 * Returns void 372 * 373 ******************************************************************************/ 374 extern void BTM_BleReadControllerFeatures( 375 tBTM_BLE_CTRL_FEATURES_CBACK* p_vsc_cback); 376 377 /******************************************************************************* 378 * 379 * Function BTM__BLEReadDiscoverability 380 * 381 * Description This function is called to read the current LE 382 * discoverability mode of the device. 383 * 384 * Returns BTM_BLE_NON_DISCOVERABLE ,BTM_BLE_LIMITED_DISCOVERABLE or 385 * BTM_BLE_GENRAL_DISCOVERABLE 386 * 387 ******************************************************************************/ 388 uint16_t BTM_BleReadDiscoverability(); 389 390 /******************************************************************************* 391 * 392 * Function BTM__BLEReadConnectability 393 * 394 * Description This function is called to read the current LE 395 * connectibility mode of the device. 396 * 397 * Returns BTM_BLE_NON_CONNECTABLE or BTM_BLE_CONNECTABLE 398 * 399 ******************************************************************************/ 400 extern uint16_t BTM_BleReadConnectability(); 401 402 /******************************************************************************* 403 * 404 * Function BTM_ReadDevInfo 405 * 406 * Description This function is called to read the device/address type 407 * of BD address. 408 * 409 * Parameter remote_bda: remote device address 410 * p_dev_type: output parameter to read the device type. 411 * p_addr_type: output parameter to read the address type. 412 * 413 ******************************************************************************/ 414 extern void BTM_ReadDevInfo(const RawAddress& remote_bda, 415 tBT_DEVICE_TYPE* p_dev_type, 416 tBLE_ADDR_TYPE* p_addr_type); 417 418 /******************************************************************************* 419 * 420 * Function BTM_ReadConnectedTransportAddress 421 * 422 * Description This function is called to read the paired device/address 423 * type of other device paired corresponding to the BD_address 424 * 425 * Parameter remote_bda: remote device address, carry out the transport 426 * address 427 * transport: active transport 428 * 429 * Return true if an active link is identified; false otherwise 430 * 431 ******************************************************************************/ 432 extern bool BTM_ReadConnectedTransportAddress(RawAddress* remote_bda, 433 tBT_TRANSPORT transport); 434 435 /******************************************************************************* 436 * 437 * Function BTM_BleConfigPrivacy 438 * 439 * Description This function is called to enable or disable the privacy in 440 * the local device. 441 * 442 * Parameters enable: true to enable it; false to disable it. 443 * 444 * Returns bool privacy mode set success; otherwise failed. 445 * 446 ******************************************************************************/ 447 extern bool BTM_BleConfigPrivacy(bool enable); 448 449 /******************************************************************************* 450 * 451 * Function BTM_BleLocalPrivacyEnabled 452 * 453 * Description Checks if local device supports private address 454 * 455 * Returns Return true if local privacy is enabled else false 456 * 457 ******************************************************************************/ 458 extern bool BTM_BleLocalPrivacyEnabled(void); 459 460 /******************************************************************************* 461 * 462 * Function BTM_BleMaxMultiAdvInstanceCount 463 * 464 * Description Returns the maximum number of multi adv instances supported 465 * by the controller. 466 * 467 * Returns Max multi adv instance count 468 * 469 ******************************************************************************/ 470 extern uint8_t BTM_BleMaxMultiAdvInstanceCount(); 471 472 /******************************************************************************* 473 * 474 * Function BTM_BleReceiverTest 475 * 476 * Description This function is called to start the LE Receiver test 477 * 478 * Parameter rx_freq - Frequency Range 479 * p_cmd_cmpl_cback - Command Complete callback 480 * 481 ******************************************************************************/ 482 void BTM_BleReceiverTest(uint8_t rx_freq, tBTM_CMPL_CB* p_cmd_cmpl_cback); 483 484 /******************************************************************************* 485 * 486 * Function BTM_BleTransmitterTest 487 * 488 * Description This function is called to start the LE Transmitter test 489 * 490 * Parameter tx_freq - Frequency Range 491 * test_data_len - Length in bytes of payload data in each 492 * packet 493 * packet_payload - Pattern to use in the payload 494 * p_cmd_cmpl_cback - Command Complete callback 495 * 496 ******************************************************************************/ 497 void BTM_BleTransmitterTest(uint8_t tx_freq, uint8_t test_data_len, 498 uint8_t packet_payload, 499 tBTM_CMPL_CB* p_cmd_cmpl_cback); 500 501 /******************************************************************************* 502 * 503 * Function BTM_BleTestEnd 504 * 505 * Description This function is called to stop the in-progress TX or RX test 506 * 507 * Parameter p_cmd_cmpl_cback - Command complete callback 508 * 509 ******************************************************************************/ 510 void BTM_BleTestEnd(tBTM_CMPL_CB* p_cmd_cmpl_cback); 511 512 /******************************************************************************* 513 * 514 * Function BTM_UseLeLink 515 * 516 * Description Select the underlying physical link to use. 517 * 518 * Returns true to use LE, false use BR/EDR. 519 * 520 ******************************************************************************/ 521 extern bool BTM_UseLeLink(const RawAddress& bd_addr); 522 523 /******************************************************************************* 524 * 525 * Function BTM_BleAdvFilterParamSetup 526 * 527 * Description This function is called to setup the adv data payload filter 528 * condition. 529 * 530 ******************************************************************************/ 531 extern void BTM_BleAdvFilterParamSetup( 532 int action, tBTM_BLE_PF_FILT_INDEX filt_index, 533 std::unique_ptr<btgatt_filt_param_setup_t> p_filt_params, 534 tBTM_BLE_PF_PARAM_CB cb); 535 536 /** 537 * This functions are called to configure the adv data payload filter condition 538 */ 539 extern void BTM_LE_PF_set(tBTM_BLE_PF_FILT_INDEX filt_index, 540 std::vector<ApcfCommand> commands, 541 tBTM_BLE_PF_CFG_CBACK cb); 542 extern void BTM_LE_PF_clear(tBTM_BLE_PF_FILT_INDEX filt_index, 543 tBTM_BLE_PF_CFG_CBACK cb); 544 545 /******************************************************************************* 546 * 547 * Function BTM_BleEnableDisableFilterFeature 548 * 549 * Description Enable or disable the APCF feature 550 * 551 * Parameters enable - true - enables APCF, false - disables APCF 552 * 553 ******************************************************************************/ 554 extern void BTM_BleEnableDisableFilterFeature( 555 uint8_t enable, tBTM_BLE_PF_STATUS_CBACK p_stat_cback); 556 557 /******************************************************************************* 558 * 559 * Function BTM_BleGetEnergyInfo 560 * 561 * Description This function obtains the energy info 562 * 563 * Parameters p_ener_cback - Callback pointer 564 * 565 * Returns status 566 * 567 ******************************************************************************/ 568 extern tBTM_STATUS BTM_BleGetEnergyInfo( 569 tBTM_BLE_ENERGY_INFO_CBACK* p_ener_cback); 570 571 /******************************************************************************* 572 * 573 * Function BTM_SetBleDataLength 574 * 575 * Description Set the maximum BLE transmission packet size 576 * 577 * Returns BTM_SUCCESS if success; otherwise failed. 578 * 579 ******************************************************************************/ 580 extern tBTM_STATUS BTM_SetBleDataLength(const RawAddress& bd_addr, 581 uint16_t tx_pdu_length); 582 583 /******************************************************************************* 584 * 585 * Function BTM_BleReadPhy 586 * 587 * Description To read the current PHYs for specified LE connection 588 * 589 * 590 * Returns BTM_SUCCESS if success; otherwise failed. 591 * 592 ******************************************************************************/ 593 extern void BTM_BleReadPhy( 594 const RawAddress& bd_addr, 595 base::Callback<void(uint8_t tx_phy, uint8_t rx_phy, uint8_t status)> cb); 596 597 /******************************************************************************* 598 * 599 * Function BTM_BleSetPhy 600 * 601 * Description To set PHY preferences for specified LE connection 602 * 603 * 604 * Returns BTM_SUCCESS if success; otherwise failed. 605 * 606 ******************************************************************************/ 607 extern void BTM_BleSetPhy(const RawAddress& bd_addr, uint8_t tx_phys, 608 uint8_t rx_phys, uint16_t phy_options); 609 610 extern void btm_ble_multi_adv_cleanup(void); 611 612 #endif 613