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