1 /* 2 * Copyright 1999-2012 Broadcom Corporation 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at: 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 * 16 ******************************************************************************/ 17 18 /****************************************************************************** 19 * 20 * This file contains the Bluetooth Manager (BTM) API function external 21 * definitions. 22 * 23 ******************************************************************************/ 24 #ifndef BTM_API_H 25 #define BTM_API_H 26 27 #include <cstdint> 28 29 #include "device/include/esco_parameters.h" 30 #include "stack/btm/neighbor_inquiry.h" 31 #include "stack/include/btm_api_types.h" 32 #include "stack/include/btm_status.h" 33 #include "stack/rnr/remote_name_request.h" 34 #include "types/bt_transport.h" 35 #include "types/raw_address.h" 36 37 void btm_init(); 38 void btm_free(); 39 40 /***************************************************************************** 41 * DEVICE CONTROL and COMMON 42 ****************************************************************************/ 43 44 /***************************************************************************** 45 * EXTERNAL FUNCTION DECLARATIONS 46 ****************************************************************************/ 47 48 /***************************************************************************** 49 * DEVICE CONTROL and COMMON FUNCTIONS 50 ****************************************************************************/ 51 52 void BTM_db_reset(void); 53 void BTM_reset_complete(); 54 55 /******************************************************************************* 56 * 57 * Function BTM_IsDeviceUp 58 * 59 * Description This function is called to check if the device is up. 60 * 61 * Returns true if device is up, else false 62 * 63 ******************************************************************************/ 64 [[nodiscard]] bool BTM_IsDeviceUp(void); 65 66 /******************************************************************************* 67 * 68 * Function BTM_SetLocalDeviceName 69 * 70 * Description This function is called to set the local device name. 71 * 72 * Returns tBTM_STATUS::BTM_CMD_STARTED if successful, otherwise an error 73 * 74 ******************************************************************************/ 75 [[nodiscard]] tBTM_STATUS BTM_SetLocalDeviceName(const char* p_name); 76 77 /******************************************************************************* 78 * 79 * Function BTM_SetDeviceClass 80 * 81 * Description This function is called to set the local device class 82 * 83 * Returns tBTM_STATUS::BTM_SUCCESS if successful, otherwise an error 84 * 85 ******************************************************************************/ 86 [[nodiscard]] tBTM_STATUS BTM_SetDeviceClass(DEV_CLASS dev_class); 87 88 /******************************************************************************* 89 * 90 * Function BTM_ReadLocalDeviceName 91 * 92 * Description This function is called to read the local device name. 93 * 94 * Returns status of the operation 95 * If success, tBTM_STATUS::BTM_SUCCESS is returned and p_name points stored 96 * local device name 97 * If BTM doesn't store local device name, tBTM_STATUS::BTM_NO_RESOURCES is 98 * is returned and p_name is set to NULL 99 * 100 ******************************************************************************/ 101 [[nodiscard]] tBTM_STATUS BTM_ReadLocalDeviceName(const char** p_name); 102 103 /******************************************************************************* 104 * 105 * Function BTM_ReadDeviceClass 106 * 107 * Description This function is called to read the local device class 108 * 109 * Returns the device class 110 * 111 ******************************************************************************/ 112 [[nodiscard]] DEV_CLASS BTM_ReadDeviceClass(void); 113 114 /******************************************************************************* 115 * 116 * Function BTM_VendorSpecificCommand 117 * 118 * Description Send a vendor specific HCI command to the controller. 119 * 120 ******************************************************************************/ 121 void BTM_VendorSpecificCommand(uint16_t opcode, uint8_t param_len, uint8_t* p_param_buf, 122 tBTM_VSC_CMPL_CB* p_cb); 123 124 /******************************************************************************* 125 * 126 * Function BTM_WritePageTimeout 127 * 128 * Description Send HCI Wite Page Timeout. 129 * 130 ******************************************************************************/ 131 void BTM_WritePageTimeout(uint16_t timeout); 132 133 /******************************************************************************* 134 * 135 * Function BTM_WriteVoiceSettings 136 * 137 * Description Send HCI Write Voice Settings command. 138 * See hcidefs.h for settings bitmask values. 139 * 140 ******************************************************************************/ 141 void BTM_WriteVoiceSettings(uint16_t settings); 142 143 /******************************************************************************* 144 * 145 * Function BTM_EnableTestMode 146 * 147 * Description Send HCI the enable device under test command. 148 * 149 * Note: Controller can only be taken out of this mode by 150 * resetting the controller. 151 * 152 * Returns 153 * tBTM_STATUS::BTM_SUCCESS Command sent. 154 * tBTM_STATUS::BTM_NO_RESOURCES If out of resources to send the command. 155 * 156 * 157 ******************************************************************************/ 158 [[nodiscard]] tBTM_STATUS BTM_EnableTestMode(void); 159 160 /******************************************************************************* 161 * 162 * Function BTM_IsRemoteVersionReceived 163 * 164 * Returns Returns true if "LE Read remote version info" was already 165 * received on LE transport for this device. 166 * 167 ******************************************************************************/ 168 [[nodiscard]] bool BTM_IsRemoteVersionReceived(const RawAddress& remote_bda); 169 170 /******************************************************************************* 171 * 172 * Function BTM_ReadRemoteVersion 173 * 174 * Description This function is called to read a remote device's version 175 * 176 * Returns true if data valid, false otherwise 177 * 178 ******************************************************************************/ 179 [[nodiscard]] bool BTM_ReadRemoteVersion(const RawAddress& addr, uint8_t* lmp_version, 180 uint16_t* manufacturer, uint16_t* lmp_sub_version); 181 182 /******************************************************************************* 183 * 184 * Function BTM_ReadRemoteFeatures 185 * 186 * Description This function is called to read a remote device's 187 * supported features mask (features mask located at page 0) 188 * 189 * Returns pointer to the remote supported features mask 190 * The size of device features mask page is 191 * HCI_FEATURE_BYTES_PER_PAGE bytes. 192 * 193 ******************************************************************************/ 194 [[nodiscard]] uint8_t* BTM_ReadRemoteFeatures(const RawAddress& addr); 195 196 /******************************************************************************* 197 * 198 * Function BTM_InqDbRead 199 * 200 * Description This function looks through the inquiry database for a match 201 * based on Bluetooth Device Address. This is the application's 202 * interface to get the inquiry details of a specific BD 203 * address. 204 * 205 * Returns pointer to entry, or NULL if not found 206 * 207 ******************************************************************************/ 208 [[nodiscard]] tBTM_INQ_INFO* BTM_InqDbRead(const RawAddress& p_bda); 209 210 /******************************************************************************* 211 * 212 * Function BTM_InqDbFirst 213 * 214 * Description This function looks through the inquiry database for the 215 * first used entry, and returns that. This is used in 216 * conjunction with BTM_InqDbNext by applications as a way to 217 * walk through the inquiry database. 218 * 219 * Returns pointer to first in-use entry, or NULL if DB is empty 220 * 221 ******************************************************************************/ 222 [[nodiscard]] tBTM_INQ_INFO* BTM_InqDbFirst(void); 223 224 /******************************************************************************* 225 * 226 * Function BTM_InqDbNext 227 * 228 * Description This function looks through the inquiry database for the 229 * next used entry, and returns that. If the input parameter 230 * is NULL, the first entry is returned. 231 * 232 * Returns pointer to next in-use entry, or NULL if no more found. 233 * 234 ******************************************************************************/ 235 [[nodiscard]] tBTM_INQ_INFO* BTM_InqDbNext(tBTM_INQ_INFO* p_cur); 236 237 /******************************************************************************* 238 * 239 * Function BTM_ClearInqDb 240 * 241 * Description This function is called to clear out a device or all devices 242 * from the inquiry database. 243 * 244 * Parameter p_bda - (input) BD_ADDR -> Address of device to clear 245 * (NULL clears all entries) 246 * 247 * Returns tBTM_STATUS::BTM_BUSY if an inquiry, get remote name, or event filter 248 * is active, otherwise tBTM_STATUS::BTM_SUCCESS 249 * 250 ******************************************************************************/ 251 [[nodiscard]] tBTM_STATUS BTM_ClearInqDb(const RawAddress* p_bda); 252 253 /***************************************************************************** 254 * (e)SCO CHANNEL MANAGEMENT FUNCTIONS 255 ****************************************************************************/ 256 /******************************************************************************* 257 * 258 * Function BTM_CreateSco 259 * 260 * Description This function is called to create an SCO connection. If the 261 * "is_orig" flag is true, the connection will be originated, 262 * otherwise BTM will wait for the other side to connect. 263 * 264 * Returns tBTM_STATUS::BTM_UNKNOWN_ADDR if the ACL connection is not up 265 * tBTM_STATUS::BTM_BUSY if another SCO being set up to 266 * the same BD address 267 * tBTM_STATUS::BTM_NO_RESOURCES if the max SCO limit has been reached 268 * tBTM_STATUS::BTM_CMD_STARTED if the connection establishment is started. 269 * In this case, "*p_sco_inx" is filled in 270 * with the sco index used for the connection. 271 * 272 ******************************************************************************/ 273 [[nodiscard]] tBTM_STATUS BTM_CreateSco(const RawAddress* remote_bda, bool is_orig, 274 uint16_t pkt_types, uint16_t* p_sco_inx, 275 tBTM_SCO_CB* p_conn_cb, tBTM_SCO_CB* p_disc_cb); 276 277 /******************************************************************************* 278 * 279 * Function BTM_RemoveSco 280 * 281 * Description This function is called to remove a specific SCO connection. 282 * 283 * Returns tBTM_STATUS::BTM_CMD_STARTED if successfully initiated, otherwise error 284 * 285 ******************************************************************************/ 286 [[nodiscard]] tBTM_STATUS BTM_RemoveSco(uint16_t sco_inx); 287 288 /******************************************************************************* 289 * 290 * Function BTM_RemoveScoByBdaddr 291 * 292 * Description This function is called to remove a specific SCO connection. 293 * but using the bluetooth device addess typically used 294 * for ACL termination. 295 * 296 * Returns void 297 * 298 ******************************************************************************/ 299 void BTM_RemoveScoByBdaddr(const RawAddress& bda); 300 301 /******************************************************************************* 302 * 303 * Function BTM_ReadScoBdAddr 304 * 305 * Description This function is read the remote BD Address for a specific 306 * SCO connection, 307 * 308 * Returns pointer to BD address or NULL if not known 309 * 310 ******************************************************************************/ 311 [[nodiscard]] const RawAddress* BTM_ReadScoBdAddr(uint16_t sco_inx); 312 313 /******************************************************************************* 314 * 315 * Function BTM_SetEScoMode 316 * 317 * Description This function sets up the negotiated parameters for SCO or 318 * eSCO, and sets as the default mode used for calls to 319 * BTM_CreateSco. It can be called only when there are no 320 * active (e)SCO links. 321 * 322 * Returns tBTM_STATUS::BTM_SUCCESS if the successful. 323 * tBTM_STATUS::BTM_BUSY if there are one or more active (e)SCO links. 324 * 325 ******************************************************************************/ 326 [[nodiscard]] tBTM_STATUS BTM_SetEScoMode(enh_esco_params_t* p_parms); 327 328 /******************************************************************************* 329 * 330 * Function BTM_RegForEScoEvts 331 * 332 * Description This function registers a SCO event callback with the 333 * specified instance. It should be used to received 334 * connection indication events and change of link parameter 335 * events. 336 * 337 * Returns tBTM_STATUS::BTM_SUCCESS if the successful. 338 * tBTM_STATUS::BTM_ILLEGAL_VALUE if there is an illegal sco_inx 339 * 340 ******************************************************************************/ 341 [[nodiscard]] tBTM_STATUS BTM_RegForEScoEvts(uint16_t sco_inx, tBTM_ESCO_CBACK* p_esco_cback); 342 343 /******************************************************************************* 344 * 345 * Function BTM_EScoConnRsp 346 * 347 * Description This function is called upon receipt of an (e)SCO connection 348 * request event (BTM_ESCO_CONN_REQ_EVT) to accept or reject 349 * the request. Parameters used to negotiate eSCO links. 350 * If p_parms is NULL, then values set through BTM_SetEScoMode 351 * are used. 352 * If the link type of the incoming request is SCO, then only 353 * the tx_bw, max_latency, content format, and packet_types are 354 * valid. The hci_status parameter should be 355 * ([0x0] to accept, [0x0d..0x0f] to reject) 356 * 357 * 358 * Returns void 359 * 360 ******************************************************************************/ 361 void BTM_EScoConnRsp(uint16_t sco_inx, tHCI_STATUS hci_status, enh_esco_params_t* p_parms); 362 363 /******************************************************************************* 364 * 365 * Function BTM_GetNumScoLinks 366 * 367 * Description This function returns the number of active SCO links. 368 * 369 * Returns uint8_t 370 * 371 ******************************************************************************/ 372 [[nodiscard]] uint8_t BTM_GetNumScoLinks(void); 373 374 /******************************************************************************* 375 * 376 * Function BTM_GetScoDebugDump 377 * 378 * Description Get the status of SCO. This function is only used for 379 * testing and debugging purposes. 380 * 381 * Returns Data with SCO related debug dump. 382 * 383 ******************************************************************************/ 384 [[nodiscard]] tBTM_SCO_DEBUG_DUMP BTM_GetScoDebugDump(void); 385 386 /******************************************************************************* 387 * 388 * Function BTM_GetPeerDeviceTypeFromFeatures 389 * 390 * Description This function is called to retrieve the peer device type 391 * by referencing the remote features. 392 * 393 * Parameters: bd_addr - address of the peer 394 * 395 * Returns BT_DEVICE_TYPE_DUMO if both BR/EDR and BLE transports are 396 * supported by the peer, 397 * BT_DEVICE_TYPE_BREDR if only BR/EDR transport is supported, 398 * BT_DEVICE_TYPE_BLE if only BLE transport is supported. 399 * 400 ******************************************************************************/ 401 [[nodiscard]] tBT_DEVICE_TYPE BTM_GetPeerDeviceTypeFromFeatures(const RawAddress& bd_addr); 402 403 /******************************************************************************* 404 * 405 * Function BTM_GetHCIConnHandle 406 * 407 * Description This function is called to get the handle for an ACL 408 * connection to a specific remote BD Address. 409 * 410 * Returns the handle of the connection, or 0xFFFF if none. 411 * 412 ******************************************************************************/ 413 [[nodiscard]] uint16_t BTM_GetHCIConnHandle(const RawAddress& remote_bda, tBT_TRANSPORT transport); 414 415 /******************************************************************************* 416 * 417 * Function BTM_IsPhy2mSupported 418 * 419 * Description This function is called to check PHY 2M support 420 * from peer device 421 * Returns True when PHY 2M supported false otherwise 422 * 423 ******************************************************************************/ 424 [[nodiscard]] bool BTM_IsPhy2mSupported(const RawAddress& remote_bda, tBT_TRANSPORT transport); 425 426 /******************************************************************************* 427 * 428 * Function BTM_RequestPeerSCA 429 * 430 * Description This function is called to request sleep clock accuracy 431 * from peer device 432 * 433 ******************************************************************************/ 434 void BTM_RequestPeerSCA(const RawAddress& remote_bda, tBT_TRANSPORT transport); 435 436 /******************************************************************************* 437 * 438 * Function BTM_GetPeerSCA 439 * 440 * Description This function is called to get peer sleep clock accuracy 441 * 442 * Returns SCA or 0xFF if SCA was never previously requested, request 443 * is not supported by peer device or ACL does not exist 444 * 445 ******************************************************************************/ 446 [[nodiscard]] uint8_t BTM_GetPeerSCA(const RawAddress& remote_bda, tBT_TRANSPORT transport); 447 448 /******************************************************************************* 449 * 450 * Function BTM_WriteEIR 451 * 452 * Description This function is called to write EIR data to controller. 453 * 454 * Parameters p_buff - allocated HCI command buffer including extended 455 * inquriry response 456 * 457 * Returns tBTM_STATUS::BTM_SUCCESS - if successful 458 * tBTM_STATUS::BTM_MODE_UNSUPPORTED - if local device cannot support it 459 * 460 ******************************************************************************/ 461 [[nodiscard]] tBTM_STATUS BTM_WriteEIR(BT_HDR* p_buff); 462 463 /******************************************************************************* 464 * 465 * Function BTM_HasEirService 466 * 467 * Description This function is called to know if UUID in bit map of UUID. 468 * 469 * Parameters p_eir_uuid - bit map of UUID list 470 * uuid16 - UUID 16-bit 471 * 472 * Returns true - if found 473 * false - if not found 474 * 475 ******************************************************************************/ 476 [[nodiscard]] bool BTM_HasEirService(const uint32_t* p_eir_uuid, uint16_t uuid16); 477 478 /******************************************************************************* 479 * 480 * Function BTM_AddEirService 481 * 482 * Description This function is called to add a service in the bit map UUID 483 * list. 484 * 485 * Parameters p_eir_uuid - bit mask of UUID list for EIR 486 * uuid16 - UUID 16-bit 487 * 488 * Returns None 489 * 490 ******************************************************************************/ 491 void BTM_AddEirService(uint32_t* p_eir_uuid, uint16_t uuid16); 492 493 /******************************************************************************* 494 * 495 * Function BTM_RemoveEirService 496 * 497 * Description This function is called to remove a service from the bit map 498 * UUID list. 499 * 500 * Parameters p_eir_uuid - bit mask of UUID list for EIR 501 * uuid16 - UUID 16-bit 502 * 503 * Returns None 504 * 505 ******************************************************************************/ 506 void BTM_RemoveEirService(uint32_t* p_eir_uuid, uint16_t uuid16); 507 508 /******************************************************************************* 509 * 510 * Function BTM_GetEirSupportedServices 511 * 512 * Description This function is called to get UUID list from bit map UUID 513 * list. 514 * 515 * Parameters p_eir_uuid - bit mask of UUID list for EIR 516 * p - reference of current pointer of EIR 517 * max_num_uuid16 - max number of UUID can be written in EIR 518 * num_uuid16 - number of UUID have been written in EIR 519 * 520 * Returns HCI_EIR_MORE_16BITS_UUID_TYPE, if it has more than max 521 * HCI_EIR_COMPLETE_16BITS_UUID_TYPE, otherwise 522 * 523 ******************************************************************************/ 524 [[nodiscard]] uint8_t BTM_GetEirSupportedServices(uint32_t* p_eir_uuid, uint8_t** p, 525 uint8_t max_num_uuid16, uint8_t* p_num_uuid16); 526 527 /******************************************************************************* 528 * 529 * Function BTM_GetEirUuidList 530 * 531 * Description This function parses EIR and returns UUID list. 532 * 533 * Parameters p_eir - EIR 534 * eirl_len - EIR len 535 * uuid_size - Uuid::kNumBytes16, Uuid::kNumBytes32, 536 * Uuid::kNumBytes128 537 * p_num_uuid - return number of UUID in found list 538 * p_uuid_list - return UUID 16-bit list 539 * max_num_uuid - maximum number of UUID to be returned 540 * 541 * Returns 0 - if not found 542 * HCI_EIR_COMPLETE_16BITS_UUID_TYPE 543 * HCI_EIR_MORE_16BITS_UUID_TYPE 544 * HCI_EIR_COMPLETE_32BITS_UUID_TYPE 545 * HCI_EIR_MORE_32BITS_UUID_TYPE 546 * HCI_EIR_COMPLETE_128BITS_UUID_TYPE 547 * HCI_EIR_MORE_128BITS_UUID_TYPE 548 * 549 ******************************************************************************/ 550 [[nodiscard]] uint8_t BTM_GetEirUuidList(const uint8_t* p_eir, size_t eir_len, uint8_t uuid_size, 551 uint8_t* p_num_uuid, uint8_t* p_uuid_list, 552 uint8_t max_num_uuid); 553 554 [[nodiscard]] bool BTM_IsScoActiveByBdaddr(const RawAddress& remote_bda); 555 556 /* Read maximum data packet that can be sent over current connection */ 557 [[nodiscard]] uint16_t BTM_GetMaxPacketSize(const RawAddress& addr); 558 559 typedef void(BTM_CONSOLIDATION_CB)(const RawAddress& identity_addr, const RawAddress& rpa); 560 void BTM_SetConsolidationCallback(BTM_CONSOLIDATION_CB* cb); 561 562 #endif /* BTM_API_H */ 563