btm_api.h revision 415d1120561ba38c7cd00f0e41d8fb69cda97601
1/****************************************************************************** 2 * 3 * Copyright (C) 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_API_H 26#define BTM_API_H 27 28#include "bt_target.h" 29#include "sdp_api.h" 30#include "hcidefs.h" 31 32#include "smp_api.h" 33 34#include "btm_api_types.h" 35 36#ifdef __cplusplus 37extern "C" { 38#endif 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/******************************************************************************* 53** 54** Function BTM_DeviceReset 55** 56** Description This function is called to reset the controller.The Callback function 57** if provided is called when startup of the device has 58** completed. 59** 60** Returns void 61** 62*******************************************************************************/ 63extern void BTM_DeviceReset (tBTM_CMPL_CB *p_cb); 64 65 66/******************************************************************************* 67** 68** Function BTM_IsDeviceUp 69** 70** Description This function is called to check if the device is up. 71** 72** Returns true if device is up, else false 73** 74*******************************************************************************/ 75extern bool BTM_IsDeviceUp (void); 76 77 78/******************************************************************************* 79** 80** Function BTM_SetLocalDeviceName 81** 82** Description This function is called to set the local device name. 83** 84** Returns BTM_CMD_STARTED if successful, otherwise an error 85** 86*******************************************************************************/ 87extern tBTM_STATUS BTM_SetLocalDeviceName (char *p_name); 88 89/******************************************************************************* 90** 91** Function BTM_SetDeviceClass 92** 93** Description This function is called to set the local device class 94** 95** Returns BTM_SUCCESS if successful, otherwise an error 96** 97*******************************************************************************/ 98extern tBTM_STATUS BTM_SetDeviceClass (DEV_CLASS dev_class); 99 100 101/******************************************************************************* 102** 103** Function BTM_ReadLocalDeviceName 104** 105** Description This function is called to read the local device name. 106** 107** Returns status of the operation 108** If success, BTM_SUCCESS is returned and p_name points stored 109** local device name 110** If BTM doesn't store local device name, BTM_NO_RESOURCES is 111** is returned and p_name is set to NULL 112** 113*******************************************************************************/ 114extern tBTM_STATUS BTM_ReadLocalDeviceName (char **p_name); 115 116/******************************************************************************* 117** 118** Function BTM_ReadLocalDeviceNameFromController 119** 120** Description Get local device name from controller. Do not use cached 121** name (used to get chip-id prior to btm reset complete). 122** 123** Returns BTM_CMD_STARTED if successful, otherwise an error 124** 125*******************************************************************************/ 126extern tBTM_STATUS BTM_ReadLocalDeviceNameFromController (tBTM_CMPL_CB *p_rln_cmpl_cback); 127 128/******************************************************************************* 129** 130** Function BTM_ReadDeviceClass 131** 132** Description This function is called to read the local device class 133** 134** Returns pointer to the device class 135** 136*******************************************************************************/ 137extern uint8_t *BTM_ReadDeviceClass (void); 138 139 140/******************************************************************************* 141** 142** Function BTM_ReadLocalFeatures 143** 144** Description This function is called to read the local features 145** 146** Returns pointer to the local features string 147** 148*******************************************************************************/ 149extern uint8_t *BTM_ReadLocalFeatures (void); 150 151/******************************************************************************* 152** 153** Function BTM_RegisterForDeviceStatusNotif 154** 155** Description This function is called to register for device status 156** change notifications. 157** 158** Returns pointer to previous caller's callback function or NULL if first 159** registration. 160** 161*******************************************************************************/ 162extern tBTM_DEV_STATUS_CB *BTM_RegisterForDeviceStatusNotif (tBTM_DEV_STATUS_CB *p_cb); 163 164 165/******************************************************************************* 166** 167** Function BTM_RegisterForVSEvents 168** 169** Description This function is called to register/deregister for vendor 170** specific HCI events. 171** 172** If is_register=true, then the function will be registered; 173** if is_register=false, then the function will be deregistered. 174** 175** Returns BTM_SUCCESS if successful, 176** BTM_BUSY if maximum number of callbacks have already been 177** registered. 178** 179*******************************************************************************/ 180extern tBTM_STATUS BTM_RegisterForVSEvents (tBTM_VS_EVT_CB *p_cb, bool is_register); 181 182 183/******************************************************************************* 184** 185** Function BTM_VendorSpecificCommand 186** 187** Description Send a vendor specific HCI command to the controller. 188** 189*******************************************************************************/ 190extern void BTM_VendorSpecificCommand(uint16_t opcode, 191 uint8_t param_len, 192 uint8_t *p_param_buf, 193 tBTM_VSC_CMPL_CB *p_cb); 194 195 196/******************************************************************************* 197** 198** Function BTM_AllocateSCN 199** 200** Description Look through the Server Channel Numbers for a free one to be 201** used with an RFCOMM connection. 202** 203** Returns Allocated SCN number or 0 if none. 204** 205*******************************************************************************/ 206extern uint8_t BTM_AllocateSCN(void); 207 208/******************************************************************************* 209** 210** Function BTM_TryAllocateSCN 211** 212** Description Try to allocate a fixed server channel 213** 214** Returns Returns true if server channel was available 215** 216*******************************************************************************/ 217extern bool BTM_TryAllocateSCN(uint8_t scn); 218 219 220/******************************************************************************* 221** 222** Function BTM_FreeSCN 223** 224** Description Free the specified SCN. 225** 226** Returns true if successful, false if SCN is not in use or invalid 227** 228*******************************************************************************/ 229extern bool BTM_FreeSCN(uint8_t scn); 230 231 232/******************************************************************************* 233** 234** Function BTM_SetTraceLevel 235** 236** Description This function sets the trace level for BTM. If called with 237** a value of 0xFF, it simply returns the current trace level. 238** 239** Returns The new or current trace level 240** 241*******************************************************************************/ 242extern uint8_t BTM_SetTraceLevel (uint8_t new_level); 243 244 245/******************************************************************************* 246** 247** Function BTM_WritePageTimeout 248** 249** Description Send HCI Wite Page Timeout. 250** 251*******************************************************************************/ 252extern void BTM_WritePageTimeout(uint16_t timeout); 253 254/******************************************************************************* 255** 256** Function BTM_WriteVoiceSettings 257** 258** Description Send HCI Write Voice Settings command. 259** See hcidefs.h for settings bitmask values. 260** 261*******************************************************************************/ 262extern void BTM_WriteVoiceSettings(uint16_t settings); 263 264/******************************************************************************* 265** 266** Function BTM_EnableTestMode 267** 268** Description Send HCI the enable device under test command. 269** 270** Note: Controller can only be taken out of this mode by 271** resetting the controller. 272** 273** Returns 274** BTM_SUCCESS Command sent. 275** BTM_NO_RESOURCES If out of resources to send the command. 276** 277** 278*******************************************************************************/ 279extern tBTM_STATUS BTM_EnableTestMode(void); 280 281 282/***************************************************************************** 283** DEVICE DISCOVERY FUNCTIONS - Inquiry, Remote Name, Discovery, Class of Device 284*****************************************************************************/ 285 286/******************************************************************************* 287** 288** Function BTM_SetDiscoverability 289** 290** Description This function is called to set the device into or out of 291** discoverable mode. Discoverable mode means inquiry 292** scans are enabled. If a value of '0' is entered for window or 293** interval, the default values are used. 294** 295** Returns BTM_SUCCESS if successful 296** BTM_BUSY if a setting of the filter is already in progress 297** BTM_NO_RESOURCES if couldn't get a memory pool buffer 298** BTM_ILLEGAL_VALUE if a bad parameter was detected 299** BTM_WRONG_MODE if the device is not up. 300** 301*******************************************************************************/ 302extern tBTM_STATUS BTM_SetDiscoverability (uint16_t inq_mode, uint16_t window, 303 uint16_t interval); 304 305 306/******************************************************************************* 307** 308** Function BTM_ReadDiscoverability 309** 310** Description This function is called to read the current discoverability 311** mode of the device. 312** 313** Output Params: p_window - current inquiry scan duration 314** p_interval - current inquiry scan interval 315** 316** Returns BTM_NON_DISCOVERABLE, BTM_LIMITED_DISCOVERABLE, or 317** BTM_GENERAL_DISCOVERABLE 318** 319*******************************************************************************/ 320extern uint16_t BTM_ReadDiscoverability (uint16_t *p_window, 321 uint16_t *p_interval); 322 323 324/******************************************************************************* 325** 326** Function BTM_SetPeriodicInquiryMode 327** 328** Description This function is called to set the device periodic inquiry mode. 329** If the duration is zero, the periodic inquiry mode is cancelled. 330** 331** Parameters: p_inqparms - pointer to the inquiry information 332** mode - GENERAL or LIMITED inquiry 333** duration - length in 1.28 sec intervals (If '0', the inquiry is CANCELLED) 334** max_resps - maximum amount of devices to search for before ending the inquiry 335** filter_cond_type - BTM_CLR_INQUIRY_FILTER, BTM_FILTER_COND_DEVICE_CLASS, or 336** BTM_FILTER_COND_BD_ADDR 337** filter_cond - value for the filter (based on filter_cond_type) 338** 339** max_delay - maximum amount of time between successive inquiries 340** min_delay - minimum amount of time between successive inquiries 341** p_results_cb - callback returning pointer to results (tBTM_INQ_RESULTS) 342** 343** Returns BTM_CMD_STARTED if successfully started 344** BTM_ILLEGAL_VALUE if a bad parameter is detected 345** BTM_NO_RESOURCES if could not allocate a message buffer 346** BTM_SUCCESS - if cancelling the periodic inquiry 347** BTM_BUSY - if an inquiry is already active 348** BTM_WRONG_MODE if the device is not up. 349** 350*******************************************************************************/ 351extern tBTM_STATUS BTM_SetPeriodicInquiryMode (tBTM_INQ_PARMS *p_inqparms, 352 uint16_t max_delay, uint16_t min_delay, 353 tBTM_INQ_RESULTS_CB *p_results_cb); 354 355 356/******************************************************************************* 357** 358** Function BTM_StartInquiry 359** 360** Description This function is called to start an inquiry. 361** 362** Parameters: p_inqparms - pointer to the inquiry information 363** mode - GENERAL or LIMITED inquiry 364** duration - length in 1.28 sec intervals (If '0', the inquiry is CANCELLED) 365** max_resps - maximum amount of devices to search for before ending the inquiry 366** filter_cond_type - BTM_CLR_INQUIRY_FILTER, BTM_FILTER_COND_DEVICE_CLASS, or 367** BTM_FILTER_COND_BD_ADDR 368** filter_cond - value for the filter (based on filter_cond_type) 369** 370** p_results_cb - Pointer to the callback routine which gets called 371** upon receipt of an inquiry result. If this field is 372** NULL, the application is not notified. 373** 374** p_cmpl_cb - Pointer to the callback routine which gets called 375** upon completion. If this field is NULL, the 376** application is not notified when completed. 377** Returns tBTM_STATUS 378** BTM_CMD_STARTED if successfully initiated 379** BTM_BUSY if already in progress 380** BTM_ILLEGAL_VALUE if parameter(s) are out of range 381** BTM_NO_RESOURCES if could not allocate resources to start the command 382** BTM_WRONG_MODE if the device is not up. 383** 384*******************************************************************************/ 385extern tBTM_STATUS BTM_StartInquiry (tBTM_INQ_PARMS *p_inqparms, 386 tBTM_INQ_RESULTS_CB *p_results_cb, 387 tBTM_CMPL_CB *p_cmpl_cb); 388 389 390/******************************************************************************* 391** 392** Function BTM_IsInquiryActive 393** 394** Description This function returns a bit mask of the current inquiry state 395** 396** Returns BTM_INQUIRY_INACTIVE if inactive (0) 397** BTM_LIMITED_INQUIRY_ACTIVE if a limted inquiry is active 398** BTM_GENERAL_INQUIRY_ACTIVE if a general inquiry is active 399** BTM_PERIODIC_INQUIRY_ACTIVE if a periodic inquiry is active 400** 401*******************************************************************************/ 402extern uint16_t BTM_IsInquiryActive (void); 403 404 405/******************************************************************************* 406** 407** Function BTM_CancelInquiry 408** 409** Description This function cancels an inquiry if active 410** 411** Returns BTM_SUCCESS if successful 412** BTM_NO_RESOURCES if could not allocate a message buffer 413** BTM_WRONG_MODE if the device is not up. 414** 415*******************************************************************************/ 416extern tBTM_STATUS BTM_CancelInquiry(void); 417 418 419/******************************************************************************* 420** 421** Function BTM_CancelPeriodicInquiry 422** 423** Description This function cancels a periodic inquiry 424** 425** Returns 426** BTM_NO_RESOURCES if could not allocate a message buffer 427** BTM_SUCCESS - if cancelling the periodic inquiry 428** BTM_WRONG_MODE if the device is not up. 429** 430*******************************************************************************/ 431extern tBTM_STATUS BTM_CancelPeriodicInquiry(void); 432 433 434/******************************************************************************* 435** 436** Function BTM_SetConnectability 437** 438** Description This function is called to set the device into or out of 439** connectable mode. Discoverable mode means page scans enabled. 440** 441** Returns BTM_SUCCESS if successful 442** BTM_ILLEGAL_VALUE if a bad parameter is detected 443** BTM_NO_RESOURCES if could not allocate a message buffer 444** BTM_WRONG_MODE if the device is not up. 445** 446*******************************************************************************/ 447extern tBTM_STATUS BTM_SetConnectability (uint16_t page_mode, uint16_t window, 448 uint16_t interval); 449 450 451/******************************************************************************* 452** 453** Function BTM_ReadConnectability 454** 455** Description This function is called to read the current discoverability 456** mode of the device. 457** Output Params p_window - current page scan duration 458** p_interval - current time between page scans 459** 460** Returns BTM_NON_CONNECTABLE or BTM_CONNECTABLE 461** 462*******************************************************************************/ 463extern uint16_t BTM_ReadConnectability (uint16_t *p_window, uint16_t *p_interval); 464 465 466/******************************************************************************* 467** 468** Function BTM_SetInquiryMode 469** 470** Description This function is called to set standard, with RSSI 471** mode or extended of the inquiry for local device. 472** 473** Input Params: BTM_INQ_RESULT_STANDARD, BTM_INQ_RESULT_WITH_RSSI or 474** BTM_INQ_RESULT_EXTENDED 475** 476** Returns BTM_SUCCESS if successful 477** BTM_NO_RESOURCES if couldn't get a memory pool buffer 478** BTM_ILLEGAL_VALUE if a bad parameter was detected 479** BTM_WRONG_MODE if the device is not up. 480** 481*******************************************************************************/ 482extern tBTM_STATUS BTM_SetInquiryMode (uint8_t mode); 483 484/******************************************************************************* 485** 486** Function BTM_SetInquiryScanType 487** 488** Description This function is called to set the iquiry scan-type to 489** standard or interlaced. 490** 491** Input Params: BTM_SCAN_TYPE_STANDARD or BTM_SCAN_TYPE_INTERLACED 492** 493** Returns BTM_SUCCESS if successful 494** BTM_MODE_UNSUPPORTED if not a 1.2 device 495** BTM_WRONG_MODE if the device is not up. 496** 497*******************************************************************************/ 498extern tBTM_STATUS BTM_SetInquiryScanType (uint16_t scan_type); 499 500/******************************************************************************* 501** 502** Function BTM_SetPageScanType 503** 504** Description This function is called to set the page scan-type to 505** standard or interlaced. 506** 507** Input Params: BTM_SCAN_TYPE_STANDARD or BTM_SCAN_TYPE_INTERLACED 508** 509** Returns BTM_SUCCESS if successful 510** BTM_MODE_UNSUPPORTED if not a 1.2 device 511** BTM_WRONG_MODE if the device is not up. 512** 513*******************************************************************************/ 514 515extern tBTM_STATUS BTM_SetPageScanType (uint16_t scan_type); 516 517/******************************************************************************* 518** 519** Function BTM_ReadRemoteDeviceName 520** 521** Description This function initiates a remote device HCI command to the 522** controller and calls the callback when the process has completed. 523** 524** Input Params: remote_bda - device address of name to retrieve 525** p_cb - callback function called when BTM_CMD_STARTED 526** is returned. 527** A pointer to tBTM_REMOTE_DEV_NAME is passed to the 528** callback. 529** 530** Returns 531** BTM_CMD_STARTED is returned if the request was successfully sent 532** to HCI. 533** BTM_BUSY if already in progress 534** BTM_UNKNOWN_ADDR if device address is bad 535** BTM_NO_RESOURCES if could not allocate resources to start the command 536** BTM_WRONG_MODE if the device is not up. 537** 538*******************************************************************************/ 539extern tBTM_STATUS BTM_ReadRemoteDeviceName (BD_ADDR remote_bda, 540 tBTM_CMPL_CB *p_cb, 541 tBT_TRANSPORT transport); 542 543 544/******************************************************************************* 545** 546** Function BTM_CancelRemoteDeviceName 547** 548** Description This function initiates the cancel request for the specified 549** remote device. 550** 551** Input Params: None 552** 553** Returns 554** BTM_CMD_STARTED is returned if the request was successfully sent 555** to HCI. 556** BTM_NO_RESOURCES if could not allocate resources to start the command 557** BTM_WRONG_MODE if there is not an active remote name request. 558** 559*******************************************************************************/ 560extern tBTM_STATUS BTM_CancelRemoteDeviceName (void); 561 562/******************************************************************************* 563** 564** Function BTM_ReadRemoteVersion 565** 566** Description This function is called to read a remote device's version 567** 568** Returns BTM_SUCCESS if successful, otherwise an error 569** 570*******************************************************************************/ 571extern tBTM_STATUS BTM_ReadRemoteVersion (BD_ADDR addr, 572 uint8_t *lmp_version, 573 uint16_t *manufacturer, 574 uint16_t *lmp_sub_version); 575 576/******************************************************************************* 577** 578** Function BTM_ReadRemoteFeatures 579** 580** Description This function is called to read a remote device's 581** supported features mask (features mask located at page 0) 582** 583** Note: The size of device features mask page is 584** BTM_FEATURE_BYTES_PER_PAGE bytes. 585** 586** Returns pointer to the remote supported features mask 587** 588*******************************************************************************/ 589extern uint8_t *BTM_ReadRemoteFeatures (BD_ADDR addr); 590 591/******************************************************************************* 592** 593** Function BTM_ReadRemoteExtendedFeatures 594** 595** Description This function is called to read a specific extended features 596** page of the remote device 597** 598** Note1: The size of device features mask page is 599** BTM_FEATURE_BYTES_PER_PAGE bytes. 600** Note2: The valid device features mask page number depends on 601** the remote device capabilities. It is expected to be in the 602** range [0 - BTM_EXT_FEATURES_PAGE_MAX]. 603 604** Returns pointer to the remote extended features mask 605** or NULL if page_number is not valid 606** 607*******************************************************************************/ 608extern uint8_t *BTM_ReadRemoteExtendedFeatures (BD_ADDR addr, uint8_t page_number); 609 610/******************************************************************************* 611** 612** Function BTM_ReadNumberRemoteFeaturesPages 613** 614** Description This function is called to retrieve the number of feature pages 615** read from the remote device 616** 617** Returns number of features pages read from the remote device 618** 619*******************************************************************************/ 620extern uint8_t BTM_ReadNumberRemoteFeaturesPages (BD_ADDR addr); 621 622/******************************************************************************* 623** 624** Function BTM_ReadAllRemoteFeatures 625** 626** Description This function is called to read all features of the remote device 627** 628** Returns pointer to the byte[0] of the page[0] of the remote device 629** feature mask. 630** 631** Note: the function returns the pointer to the array of the size 632** BTM_FEATURE_BYTES_PER_PAGE * (BTM_EXT_FEATURES_PAGE_MAX + 1). 633** 634*******************************************************************************/ 635extern uint8_t *BTM_ReadAllRemoteFeatures (BD_ADDR addr); 636 637/******************************************************************************* 638** 639** Function BTM_InqDbRead 640** 641** Description This function looks through the inquiry database for a match 642** based on Bluetooth Device Address. This is the application's 643** interface to get the inquiry details of a specific BD address. 644** 645** Returns pointer to entry, or NULL if not found 646** 647*******************************************************************************/ 648extern tBTM_INQ_INFO *BTM_InqDbRead (const BD_ADDR p_bda); 649 650 651/******************************************************************************* 652** 653** Function BTM_InqDbFirst 654** 655** Description This function looks through the inquiry database for the first 656** used entry, and returns that. This is used in conjunction with 657** BTM_InqDbNext by applications as a way to walk through the 658** inquiry database. 659** 660** Returns pointer to first in-use entry, or NULL if DB is empty 661** 662*******************************************************************************/ 663extern tBTM_INQ_INFO *BTM_InqDbFirst (void); 664 665 666/******************************************************************************* 667** 668** Function BTM_InqDbNext 669** 670** Description This function looks through the inquiry database for the next 671** used entry, and returns that. If the input parameter is NULL, 672** the first entry is returned. 673** 674** Returns pointer to next in-use entry, or NULL if no more found. 675** 676*******************************************************************************/ 677extern tBTM_INQ_INFO *BTM_InqDbNext (tBTM_INQ_INFO *p_cur); 678 679 680/******************************************************************************* 681** 682** Function BTM_ClearInqDb 683** 684** Description This function is called to clear out a device or all devices 685** from the inquiry database. 686** 687** Parameter p_bda - (input) BD_ADDR -> Address of device to clear 688** (NULL clears all entries) 689** 690** Returns BTM_BUSY if an inquiry, get remote name, or event filter 691** is active, otherwise BTM_SUCCESS 692** 693*******************************************************************************/ 694extern tBTM_STATUS BTM_ClearInqDb (BD_ADDR p_bda); 695 696/******************************************************************************* 697** 698** Function BTM_ReadInquiryRspTxPower 699** 700** Description This command will read the inquiry Transmit Power level used 701** to transmit the FHS and EIR data packets. 702** This can be used directly in the Tx Power Level EIR data type. 703** 704** Returns BTM_SUCCESS if successful 705** 706*******************************************************************************/ 707extern tBTM_STATUS BTM_ReadInquiryRspTxPower (tBTM_CMPL_CB *p_cb); 708 709/******************************************************************************* 710** 711** Function BTM_StartDiscovery 712** 713** Description This function is called by an application (or profile) 714** when it wants to trigger an service discovery using the 715** BTM's discovery database. 716** 717** Returns tBTM_STATUS 718** BTM_CMD_STARTED if the discovery was initiated 719** BTM_BUSY if one is already in progress 720** BTM_UNKNOWN_ADDR if no addresses are in the INQ DB 721** BTM_ERR_PROCESSING if err initiating the command 722** 723*******************************************************************************/ 724extern tBTM_STATUS BTM_StartDiscovery (tBTM_CMPL_CB *p_cmpl_cb, 725 BD_ADDR_PTR p_rem_addr); 726 727 728/******************************************************************************* 729** 730** Function BTM_FindAttribute 731** 732** Description This function is called by an application (or profile) 733** when it wants to see if an attribute exists in the BTM 734** discovery database. 735** 736** Returns Pointer to matching record, or NULL 737** 738*******************************************************************************/ 739extern tSDP_DISC_REC *BTM_FindAttribute (uint16_t attr_id, 740 tSDP_DISC_REC *p_start_rec); 741 742 743/******************************************************************************* 744** 745** Function BTM_FindService 746** 747** Description This function is called by an application (or profile) 748** when it wants to see if a service exists in the BTM 749** discovery database. 750** 751** Returns Pointer to matching record, or NULL 752** 753*******************************************************************************/ 754extern tSDP_DISC_REC *BTM_FindService (uint16_t service_uuid, 755 tSDP_DISC_REC *p_start_rec); 756 757 758/******************************************************************************* 759** 760** Function BTM_SetDiscoveryParams 761** 762** Description This function is called to set the BTM default discovery parameters. 763** These UUID and attribute filters are used during the call to 764** BTM_StartDiscovery. 765** 766** Returns void 767** 768*******************************************************************************/ 769extern void BTM_SetDiscoveryParams (uint16_t num_uuid, tSDP_UUID *p_uuid_list, 770 uint16_t num_attr, uint16_t *p_attr_list); 771 772 773/***************************************************************************** 774** ACL CHANNEL MANAGEMENT FUNCTIONS 775*****************************************************************************/ 776/******************************************************************************* 777** 778** Function BTM_SetLinkPolicy 779** 780** Description Create and send HCI "Write Policy Set" command 781** 782** Returns BTM_CMD_STARTED if successfully initiated, otherwise error 783** 784*******************************************************************************/ 785extern tBTM_STATUS BTM_SetLinkPolicy (BD_ADDR remote_bda, 786 uint16_t *settings); 787 788/******************************************************************************* 789** 790** Function BTM_SetDefaultLinkPolicy 791** 792** Description Set the default value for HCI "Write Policy Set" command 793** to use when an ACL link is created. 794** 795** Returns void 796** 797*******************************************************************************/ 798extern void BTM_SetDefaultLinkPolicy (uint16_t settings); 799 800 801/******************************************************************************* 802** 803** Function BTM_SetDefaultLinkSuperTout 804** 805** Description Set the default value for HCI "Write Link Supervision Timeout" 806** command to use when an ACL link is created. 807** 808** Returns void 809** 810*******************************************************************************/ 811extern void BTM_SetDefaultLinkSuperTout (uint16_t timeout); 812 813 814/******************************************************************************* 815** 816** Function BTM_SetLinkSuperTout 817** 818** Description Create and send HCI "Write Link Supervision Timeout" command 819** 820** Returns BTM_CMD_STARTED if successfully initiated, otherwise error 821** 822*******************************************************************************/ 823extern tBTM_STATUS BTM_SetLinkSuperTout (BD_ADDR remote_bda, 824 uint16_t timeout); 825/******************************************************************************* 826** 827** Function BTM_GetLinkSuperTout 828** 829** Description Read the link supervision timeout value of the connection 830** 831** Returns status of the operation 832** 833*******************************************************************************/ 834extern tBTM_STATUS BTM_GetLinkSuperTout (BD_ADDR remote_bda, 835 uint16_t *p_timeout); 836 837/******************************************************************************* 838** 839** Function BTM_IsAclConnectionUp 840** 841** Description This function is called to check if an ACL connection exists 842** to a specific remote BD Address. 843** 844** Returns true if connection is up, else false. 845** 846*******************************************************************************/ 847extern bool BTM_IsAclConnectionUp (BD_ADDR remote_bda, tBT_TRANSPORT transport); 848 849 850/******************************************************************************* 851** 852** Function BTM_GetRole 853** 854** Description This function is called to get the role of the local device 855** for the ACL connection with the specified remote device 856** 857** Returns BTM_SUCCESS if connection exists. 858** BTM_UNKNOWN_ADDR if no active link with bd addr specified 859** 860*******************************************************************************/ 861extern tBTM_STATUS BTM_GetRole (BD_ADDR remote_bd_addr, uint8_t *p_role); 862 863 864 865/******************************************************************************* 866** 867** Function BTM_SwitchRole 868** 869** Description This function is called to switch role between master and 870** slave. If role is already set it will do nothing. If the 871** command was initiated, the callback function is called upon 872** completion. 873** 874** Returns BTM_SUCCESS if already in specified role. 875** BTM_CMD_STARTED if command issued to controller. 876** BTM_NO_RESOURCES if couldn't allocate memory to issue command 877** BTM_UNKNOWN_ADDR if no active link with bd addr specified 878** BTM_MODE_UNSUPPORTED if local device does not support role switching 879** 880*******************************************************************************/ 881extern tBTM_STATUS BTM_SwitchRole (BD_ADDR remote_bd_addr, 882 uint8_t new_role, 883 tBTM_CMPL_CB *p_cb); 884 885/******************************************************************************* 886** 887** Function BTM_ReadRSSI 888** 889** Description This function is called to read the link policy settings. 890** The address of link policy results are returned in the callback. 891** (tBTM_RSSI_RESULTS) 892** 893** Returns BTM_CMD_STARTED if command issued to controller. 894** BTM_NO_RESOURCES if couldn't allocate memory to issue command 895** BTM_UNKNOWN_ADDR if no active link with bd addr specified 896** BTM_BUSY if command is already in progress 897** 898*******************************************************************************/ 899extern tBTM_STATUS BTM_ReadRSSI (const BD_ADDR remote_bda, tBTM_CMPL_CB *p_cb); 900 901 902/******************************************************************************* 903** 904** Function BTM_ReadTxPower 905** 906** Description This function is called to read the current connection 907** TX power of the connection. The TX power level results 908** are returned in the callback. 909** (tBTM_RSSI_RESULTS) 910** 911** Returns BTM_CMD_STARTED if command issued to controller. 912** BTM_NO_RESOURCES if couldn't allocate memory to issue command 913** BTM_UNKNOWN_ADDR if no active link with bd addr specified 914** BTM_BUSY if command is already in progress 915** 916*******************************************************************************/ 917extern tBTM_STATUS BTM_ReadTxPower (BD_ADDR remote_bda, 918 tBT_TRANSPORT transport, tBTM_CMPL_CB *p_cb); 919 920/******************************************************************************* 921** 922** Function BTM_ReadLinkQuality 923** 924** Description This function is called to read the link quality. 925** The value of the link quality is returned in the callback. 926** (tBTM_LINK_QUALITY_RESULTS) 927** 928** Returns BTM_CMD_STARTED if command issued to controller. 929** BTM_NO_RESOURCES if couldn't allocate memory to issue command 930** BTM_UNKNOWN_ADDR if no active link with bd addr specified 931** BTM_BUSY if command is already in progress 932** 933*******************************************************************************/ 934extern tBTM_STATUS BTM_ReadLinkQuality (BD_ADDR remote_bda, tBTM_CMPL_CB *p_cb); 935 936/******************************************************************************* 937** 938** Function BTM_RegBusyLevelNotif 939** 940** Description This function is called to register a callback to receive 941** busy level change events. 942** 943** Returns BTM_SUCCESS if successfully registered, otherwise error 944** 945*******************************************************************************/ 946extern tBTM_STATUS BTM_RegBusyLevelNotif (tBTM_BL_CHANGE_CB *p_cb, uint8_t *p_level, 947 tBTM_BL_EVENT_MASK evt_mask); 948 949/******************************************************************************* 950** 951** Function BTM_AclRegisterForChanges 952** 953** Description This function is called to register a callback to receive 954** ACL database change events, i.e. new connection or removed. 955** 956** Returns BTM_SUCCESS if successfully initiated, otherwise error 957** 958*******************************************************************************/ 959extern tBTM_STATUS BTM_AclRegisterForChanges (tBTM_ACL_DB_CHANGE_CB *p_cb); 960 961/******************************************************************************* 962** 963** Function BTM_GetNumAclLinks 964** 965** Description This function is called to count the number of 966** ACL links that are active. 967** 968** Returns uint16_t Number of active ACL links 969** 970*******************************************************************************/ 971extern uint16_t BTM_GetNumAclLinks (void); 972 973/******************************************************************************* 974** 975** Function BTM_SetQoS 976** 977** Description This function is called to setup QoS 978** 979** Returns BTM_CMD_STARTED if successfully initiated, otherwise error 980** 981*******************************************************************************/ 982extern tBTM_STATUS BTM_SetQoS(BD_ADDR bd, FLOW_SPEC *p_flow, 983 tBTM_CMPL_CB *p_cb); 984 985 986/***************************************************************************** 987** (e)SCO CHANNEL MANAGEMENT FUNCTIONS 988*****************************************************************************/ 989/******************************************************************************* 990** 991** Function BTM_CreateSco 992** 993** Description This function is called to create an SCO connection. If the 994** "is_orig" flag is true, the connection will be originated, 995** otherwise BTM will wait for the other side to connect. 996** 997** Returns BTM_UNKNOWN_ADDR if the ACL connection is not up 998** BTM_BUSY if another SCO being set up to 999** the same BD address 1000** BTM_NO_RESOURCES if the max SCO limit has been reached 1001** BTM_CMD_STARTED if the connection establishment is started. 1002** In this case, "*p_sco_inx" is filled in 1003** with the sco index used for the connection. 1004** 1005*******************************************************************************/ 1006extern tBTM_STATUS BTM_CreateSco (BD_ADDR remote_bda, bool is_orig, 1007 uint16_t pkt_types, uint16_t *p_sco_inx, 1008 tBTM_SCO_CB *p_conn_cb, 1009 tBTM_SCO_CB *p_disc_cb); 1010 1011 1012/******************************************************************************* 1013** 1014** Function BTM_RemoveSco 1015** 1016** Description This function is called to remove a specific SCO connection. 1017** 1018** Returns BTM_CMD_STARTED if successfully initiated, otherwise error 1019** 1020*******************************************************************************/ 1021extern tBTM_STATUS BTM_RemoveSco (uint16_t sco_inx); 1022 1023 1024/******************************************************************************* 1025** 1026** Function BTM_SetScoPacketTypes 1027** 1028** Description This function is called to set the packet types used for 1029** a specific SCO connection, 1030** 1031** Parameters pkt_types - One or more of the following 1032** BTM_SCO_PKT_TYPES_MASK_HV1 1033** BTM_SCO_PKT_TYPES_MASK_HV2 1034** BTM_SCO_PKT_TYPES_MASK_HV3 1035** BTM_SCO_PKT_TYPES_MASK_EV3 1036** BTM_SCO_PKT_TYPES_MASK_EV4 1037** BTM_SCO_PKT_TYPES_MASK_EV5 1038** 1039** BTM_SCO_LINK_ALL_MASK - enables all supported types 1040** 1041** Returns BTM_CMD_STARTED if successfully initiated, otherwise error 1042** 1043*******************************************************************************/ 1044extern tBTM_STATUS BTM_SetScoPacketTypes (uint16_t sco_inx, uint16_t pkt_types); 1045 1046 1047/******************************************************************************* 1048** 1049** Function BTM_ReadScoPacketTypes 1050** 1051** Description This function is read the packet types used for a specific 1052** SCO connection. 1053** 1054** Returns One or more of the following (bitmask) 1055** BTM_SCO_PKT_TYPES_MASK_HV1 1056** BTM_SCO_PKT_TYPES_MASK_HV2 1057** BTM_SCO_PKT_TYPES_MASK_HV3 1058** BTM_SCO_PKT_TYPES_MASK_EV3 1059** BTM_SCO_PKT_TYPES_MASK_EV4 1060** BTM_SCO_PKT_TYPES_MASK_EV5 1061** 1062** Returns packet types supported for the connection 1063** 1064*******************************************************************************/ 1065extern uint16_t BTM_ReadScoPacketTypes (uint16_t sco_inx); 1066 1067 1068/******************************************************************************* 1069** 1070** Function BTM_ReadDeviceScoPacketTypes 1071** 1072** Description This function is read the SCO packet types that 1073** the device supports. 1074** 1075** Returns packet types supported by the device. 1076** 1077*******************************************************************************/ 1078extern uint16_t BTM_ReadDeviceScoPacketTypes (void); 1079 1080 1081/******************************************************************************* 1082** 1083** Function BTM_ReadScoHandle 1084** 1085** Description This function is used to read the HCI handle used for a specific 1086** SCO connection, 1087** 1088** Returns handle for the connection, or 0xFFFF if invalid SCO index. 1089** 1090*******************************************************************************/ 1091extern uint16_t BTM_ReadScoHandle (uint16_t sco_inx); 1092 1093 1094/******************************************************************************* 1095** 1096** Function BTM_ReadScoBdAddr 1097** 1098** Description This function is read the remote BD Address for a specific 1099** SCO connection, 1100** 1101** Returns pointer to BD address or NULL if not known 1102** 1103*******************************************************************************/ 1104extern uint8_t *BTM_ReadScoBdAddr (uint16_t sco_inx); 1105 1106 1107/******************************************************************************* 1108** 1109** Function BTM_ReadScoDiscReason 1110** 1111** Description This function is returns the reason why an (e)SCO connection 1112** has been removed. It contains the value until read, or until 1113** another (e)SCO connection has disconnected. 1114** 1115** Returns HCI reason or BTM_INVALID_SCO_DISC_REASON if not set. 1116** 1117*******************************************************************************/ 1118extern uint16_t BTM_ReadScoDiscReason (void); 1119 1120 1121/******************************************************************************* 1122** 1123** Function BTM_SetEScoMode 1124** 1125** Description This function sets up the negotiated parameters for SCO or 1126** eSCO, and sets as the default mode used for calls to 1127** BTM_CreateSco. It can be called only when there are no 1128** active (e)SCO links. 1129** 1130** Returns BTM_SUCCESS if the successful. 1131** BTM_BUSY if there are one or more active (e)SCO links. 1132** 1133*******************************************************************************/ 1134extern tBTM_STATUS BTM_SetEScoMode (tBTM_SCO_TYPE sco_mode, 1135 tBTM_ESCO_PARAMS *p_parms); 1136 1137/******************************************************************************* 1138** 1139** Function BTM_SetWBSCodec 1140** 1141** Description This function sends command to the controller to setup 1142** WBS codec for the upcoming eSCO connection. 1143** 1144** Returns BTM_SUCCESS. 1145** 1146** 1147*******************************************************************************/ 1148extern tBTM_STATUS BTM_SetWBSCodec (tBTM_SCO_CODEC_TYPE codec_type); 1149 1150/******************************************************************************* 1151** 1152** Function BTM_RegForEScoEvts 1153** 1154** Description This function registers a SCO event callback with the 1155** specified instance. It should be used to received 1156** connection indication events and change of link parameter 1157** events. 1158** 1159** Returns BTM_SUCCESS if the successful. 1160** BTM_ILLEGAL_VALUE if there is an illegal sco_inx 1161** 1162*******************************************************************************/ 1163extern tBTM_STATUS BTM_RegForEScoEvts (uint16_t sco_inx, 1164 tBTM_ESCO_CBACK *p_esco_cback); 1165 1166/******************************************************************************* 1167** 1168** Function BTM_ReadEScoLinkParms 1169** 1170** Description This function returns the current eSCO link parameters for 1171** the specified handle. This can be called anytime a connection 1172** is active, but is typically called after receiving the SCO 1173** opened callback. 1174** 1175** Note: If called over a 1.1 controller, only the packet types 1176** field has meaning. 1177** Note: If the upper layer doesn't know the current sco index, 1178** BTM_FIRST_ACTIVE_SCO_INDEX can be used as the first parameter to 1179** find the first active SCO index 1180** 1181** Returns BTM_SUCCESS if returned data is valid connection. 1182** BTM_ILLEGAL_VALUE if no connection for specified sco_inx. 1183** BTM_MODE_UNSUPPORTED if local controller does not support 1184** 1.2 specification. 1185** 1186*******************************************************************************/ 1187extern tBTM_STATUS BTM_ReadEScoLinkParms (uint16_t sco_inx, 1188 tBTM_ESCO_DATA *p_parms); 1189 1190/******************************************************************************* 1191** 1192** Function BTM_ChangeEScoLinkParms 1193** 1194** Description This function requests renegotiation of the parameters on 1195** the current eSCO Link. If any of the changes are accepted 1196** by the controllers, the BTM_ESCO_CHG_EVT event is sent in 1197** the tBTM_ESCO_CBACK function with the current settings of 1198** the link. The callback is registered through the call to 1199** BTM_SetEScoMode. 1200** 1201** 1202** Returns BTM_CMD_STARTED if command is successfully initiated. 1203** BTM_ILLEGAL_VALUE if no connection for specified sco_inx. 1204** BTM_NO_RESOURCES - not enough resources to initiate command. 1205** BTM_MODE_UNSUPPORTED if local controller does not support 1206** 1.2 specification. 1207** 1208*******************************************************************************/ 1209extern tBTM_STATUS BTM_ChangeEScoLinkParms (uint16_t sco_inx, 1210 tBTM_CHG_ESCO_PARAMS *p_parms); 1211 1212/******************************************************************************* 1213** 1214** Function BTM_EScoConnRsp 1215** 1216** Description This function is called upon receipt of an (e)SCO connection 1217** request event (BTM_ESCO_CONN_REQ_EVT) to accept or reject 1218** the request. Parameters used to negotiate eSCO links. 1219** If p_parms is NULL, then values set through BTM_SetEScoMode 1220** are used. 1221** If the link type of the incoming request is SCO, then only 1222** the tx_bw, max_latency, content format, and packet_types are 1223** valid. The hci_status parameter should be 1224** ([0x0] to accept, [0x0d..0x0f] to reject) 1225** 1226** 1227** Returns void 1228** 1229*******************************************************************************/ 1230extern void BTM_EScoConnRsp (uint16_t sco_inx, uint8_t hci_status, 1231 tBTM_ESCO_PARAMS *p_parms); 1232 1233/******************************************************************************* 1234** 1235** Function BTM_GetNumScoLinks 1236** 1237** Description This function returns the number of active SCO links. 1238** 1239** Returns uint8_t 1240** 1241*******************************************************************************/ 1242extern uint8_t BTM_GetNumScoLinks (void); 1243 1244/***************************************************************************** 1245** SECURITY MANAGEMENT FUNCTIONS 1246*****************************************************************************/ 1247/******************************************************************************* 1248** 1249** Function BTM_SecRegister 1250** 1251** Description Application manager calls this function to register for 1252** security services. There can be one and only one application 1253** saving link keys. BTM allows only first registration. 1254** 1255** Returns true if registered OK, else false 1256** 1257*******************************************************************************/ 1258extern bool BTM_SecRegister (tBTM_APPL_INFO *p_cb_info); 1259 1260/******************************************************************************* 1261** 1262** Function BTM_SecRegisterLinkKeyNotificationCallback 1263** 1264** Description Profiles can register to be notified when a new Link Key 1265** is generated per connection. 1266** 1267** Returns true if registered OK, else false 1268** 1269*******************************************************************************/ 1270extern bool BTM_SecRegisterLinkKeyNotificationCallback( 1271 tBTM_LINK_KEY_CALLBACK *p_callback); 1272 1273/******************************************************************************* 1274** 1275** Function BTM_SecAddRmtNameNotifyCallback 1276** 1277** Description Profiles can register to be notified when name of the 1278** remote device is resolved (up to BTM_SEC_MAX_RMT_NAME_CALLBACKS). 1279** 1280** Returns true if registered OK, else false 1281** 1282*******************************************************************************/ 1283extern bool BTM_SecAddRmtNameNotifyCallback (tBTM_RMT_NAME_CALLBACK *p_callback); 1284 1285 1286/******************************************************************************* 1287** 1288** Function BTM_SecDeleteRmtNameNotifyCallback 1289** 1290** Description A profile can deregister notification when a new Link Key 1291** is generated per connection. 1292** 1293** Returns true if OK, else false 1294** 1295*******************************************************************************/ 1296extern bool BTM_SecDeleteRmtNameNotifyCallback (tBTM_RMT_NAME_CALLBACK *p_callback); 1297 1298/******************************************************************************* 1299** 1300** Function BTM_GetSecurityFlags 1301** 1302** Description Get security flags for the device 1303** 1304** Returns bool true or false is device found 1305** 1306*******************************************************************************/ 1307extern bool BTM_GetSecurityFlags (BD_ADDR bd_addr, uint8_t * p_sec_flags); 1308 1309/******************************************************************************* 1310** 1311** Function BTM_GetSecurityFlagsByTransport 1312** 1313** Description Get security flags for the device on a particular transport 1314** 1315** Parameters bd_addr: BD address of remote device 1316** p_sec_flags : Out parameter to be filled with security flags for the connection 1317** transport : Physical transport of the connection (BR/EDR or LE) 1318** 1319** Returns bool true or false is device found 1320** 1321*******************************************************************************/ 1322extern bool BTM_GetSecurityFlagsByTransport (BD_ADDR bd_addr, 1323 uint8_t * p_sec_flags, tBT_TRANSPORT transport); 1324 1325/******************************************************************************* 1326** 1327** Function BTM_ReadTrustedMask 1328** 1329** Description Get trusted mask for the device 1330** 1331** Returns NULL, if the device record is not found. 1332** otherwise, the trusted mask 1333** 1334*******************************************************************************/ 1335extern uint32_t * BTM_ReadTrustedMask (BD_ADDR bd_addr); 1336 1337/******************************************************************************* 1338** 1339** Function BTM_SetPinType 1340** 1341** Description Set PIN type for the device. 1342** 1343** Returns void 1344** 1345*******************************************************************************/ 1346extern void BTM_SetPinType (uint8_t pin_type, PIN_CODE pin_code, uint8_t pin_code_len); 1347 1348 1349/******************************************************************************* 1350** 1351** Function BTM_SetPairableMode 1352** 1353** Description Enable or disable pairing 1354** 1355** Parameters allow_pairing - (true or false) whether or not the device 1356** allows pairing. 1357** connect_only_paired - (true or false) whether or not to 1358** only allow paired devices to connect. 1359** 1360** Returns void 1361** 1362*******************************************************************************/ 1363extern void BTM_SetPairableMode (bool allow_pairing, bool connect_only_paired); 1364 1365/******************************************************************************* 1366** 1367** Function BTM_SetSecureConnectionsOnly 1368** 1369** Description Enable or disable default treatment for Mode 4 Level 0 services 1370** 1371** Parameter secure_connections_only_mode - (true or false) 1372** true means that the device should treat Mode 4 Level 0 services as 1373** services of other levels. 1374** false means that the device should provide default treatment for 1375** Mode 4 Level 0 services. 1376** 1377** Returns void 1378** 1379*******************************************************************************/ 1380extern void BTM_SetSecureConnectionsOnly (bool secure_connections_only_mode); 1381 1382/******************************************************************************* 1383** 1384** Function BTM_SetSecurityLevel 1385** 1386** Description Register service security level with Security Manager. Each 1387** service must register its requirements regardless of the 1388** security level that is used. This API is called once for originators 1389** nad again for acceptors of connections. 1390** 1391** Returns true if registered OK, else false 1392** 1393*******************************************************************************/ 1394extern bool BTM_SetSecurityLevel (bool is_originator, const char *p_name, 1395 uint8_t service_id, uint16_t sec_level, 1396 uint16_t psm, uint32_t mx_proto_id, 1397 uint32_t mx_chan_id); 1398 1399/******************************************************************************* 1400** 1401** Function BTM_SetOutService 1402** 1403** Description This function is called to set the service for 1404** outgoing connection. 1405** 1406** Returns void 1407** 1408*******************************************************************************/ 1409extern void BTM_SetOutService(BD_ADDR bd_addr, uint8_t service_id, uint32_t mx_chan_id); 1410 1411/******************************************************************************* 1412** 1413** Function BTM_SecClrService 1414** 1415** Description Removes specified service record(s) from the security database. 1416** All service records with the specified name are removed. 1417** Typically used only by devices with limited RAM so that it can 1418** reuse an old security service record. 1419** records (except SDP). 1420** 1421** Returns Number of records that were freed. 1422** 1423*******************************************************************************/ 1424extern uint8_t BTM_SecClrService (uint8_t service_id); 1425 1426/******************************************************************************* 1427** 1428** Function BTM_SecAddDevice 1429** 1430** Description Add/modify device. This function will be normally called 1431** during host startup to restore all required information 1432** stored in the NVRAM. 1433** dev_class, bd_name, link_key, and features are NULL if unknown 1434** 1435** Returns true if added OK, else false 1436** 1437*******************************************************************************/ 1438extern bool BTM_SecAddDevice (BD_ADDR bd_addr, DEV_CLASS dev_class, 1439 BD_NAME bd_name, uint8_t *features, 1440 uint32_t trusted_mask[], LINK_KEY link_key, 1441 uint8_t key_type, tBTM_IO_CAP io_cap, uint8_t pin_length); 1442 1443 1444/******************************************************************************* 1445** 1446** Function BTM_SecDeleteDevice 1447** 1448** Description Free resources associated with the device. 1449** 1450** Returns true if rmoved OK, false if not found 1451** 1452*******************************************************************************/ 1453extern bool BTM_SecDeleteDevice (BD_ADDR bd_addr); 1454 1455/******************************************************************************* 1456** 1457** Function BTM_SecClearSecurityFlags 1458** 1459** Description Reset the security flags (mark as not-paired) for a given 1460** remove device. 1461** 1462*******************************************************************************/ 1463extern void BTM_SecClearSecurityFlags (BD_ADDR bd_addr); 1464 1465/******************************************************************************* 1466** 1467** Function BTM_SecGetDeviceLinkKey 1468** 1469** Description This function is called to obtain link key for the device 1470** it returns BTM_SUCCESS if link key is available, or 1471** BTM_UNKNOWN_ADDR if Security Manager does not know about 1472** the device or device record does not contain link key info 1473** 1474** Returns BTM_SUCCESS if successful, otherwise error code 1475** 1476*******************************************************************************/ 1477extern tBTM_STATUS BTM_SecGetDeviceLinkKey (BD_ADDR bd_addr, 1478 LINK_KEY link_key); 1479 1480 1481/******************************************************************************* 1482** 1483** Function BTM_SecGetDeviceLinkKeyType 1484** 1485** Description This function is called to obtain link key type for the 1486** device. 1487** it returns BTM_SUCCESS if link key is available, or 1488** BTM_UNKNOWN_ADDR if Security Manager does not know about 1489** the device or device record does not contain link key info 1490** 1491** Returns BTM_LKEY_TYPE_IGNORE if link key is unknown, link type 1492** otherwise. 1493** 1494*******************************************************************************/ 1495extern tBTM_LINK_KEY_TYPE BTM_SecGetDeviceLinkKeyType (BD_ADDR bd_addr); 1496 1497 1498/******************************************************************************* 1499** 1500** Function BTM_PINCodeReply 1501** 1502** Description This function is called after Security Manager submitted 1503** PIN code request to the UI. 1504** 1505** Parameters: bd_addr - Address of the device for which PIN was requested 1506** res - result of the operation BTM_SUCCESS if success 1507** pin_len - length in bytes of the PIN Code 1508** p_pin - pointer to array with the PIN Code 1509** trusted_mask - bitwise OR of trusted services (array of uint32_t) 1510** 1511** Returns void 1512** 1513*******************************************************************************/ 1514extern void BTM_PINCodeReply (BD_ADDR bd_addr, uint8_t res, uint8_t pin_len, 1515 uint8_t *p_pin, uint32_t trusted_mask[]); 1516 1517 1518/******************************************************************************* 1519** 1520** Function BTM_SecBond 1521** 1522** Description This function is called to perform bonding with peer device. 1523** 1524** Parameters: bd_addr - Address of the device to bond 1525** pin_len - length in bytes of the PIN Code 1526** p_pin - pointer to array with the PIN Code 1527** trusted_mask - bitwise OR of trusted services (array of uint32_t) 1528 1529** Returns BTM_CMD_STARTED if successfully initiated, otherwise error 1530** 1531*******************************************************************************/ 1532extern tBTM_STATUS BTM_SecBond (BD_ADDR bd_addr, 1533 uint8_t pin_len, uint8_t *p_pin, 1534 uint32_t trusted_mask[]); 1535 1536/******************************************************************************* 1537** 1538** Function BTM_SecBondByTransport 1539** 1540** Description This function is called to perform bonding by designated transport 1541** 1542** Parameters: bd_addr - Address of the device to bond 1543** pin_len - length in bytes of the PIN Code 1544** p_pin - pointer to array with the PIN Code 1545** trusted_mask - bitwise OR of trusted services (array of uint32_t) 1546** transport : Physical transport to use for bonding (BR/EDR or LE) 1547** 1548** Returns BTM_CMD_STARTED if successfully initiated, otherwise error 1549** 1550*******************************************************************************/ 1551extern tBTM_STATUS BTM_SecBondByTransport (BD_ADDR bd_addr, 1552 tBT_TRANSPORT transport, 1553 uint8_t pin_len, uint8_t *p_pin, 1554 uint32_t trusted_mask[]); 1555 1556/******************************************************************************* 1557** 1558** Function BTM_SecBondCancel 1559** 1560** Description This function is called to cancel ongoing bonding process 1561** with peer device. 1562** 1563** Returns BTM_CMD_STARTED if successfully initiated, otherwise error 1564** 1565*******************************************************************************/ 1566extern tBTM_STATUS BTM_SecBondCancel (BD_ADDR bd_addr); 1567 1568/******************************************************************************* 1569** 1570** Function BTM_SetEncryption 1571** 1572** Description This function is called to ensure that connection is 1573** encrypted. Should be called only on an open connection. 1574** Typically only needed for connections that first want to 1575** bring up unencrypted links, then later encrypt them. 1576** 1577** Parameters: bd_addr - Address of the peer device 1578** transport - Link transport 1579** p_callback - Pointer to callback function called if 1580** this function returns PENDING after required 1581** procedures are completed. Can be set to NULL 1582** if status is not desired. 1583** p_ref_data - pointer to any data the caller wishes to receive 1584** in the callback function upon completion. 1585** can be set to NULL if not used. 1586** sec_act - LE security action, unused for BR/EDR 1587** 1588** Returns BTM_SUCCESS - already encrypted 1589** BTM_PENDING - command will be returned in the callback 1590** BTM_WRONG_MODE- connection not up. 1591** BTM_BUSY - security procedures are currently active 1592** BTM_MODE_UNSUPPORTED - if security manager not linked in. 1593** 1594*******************************************************************************/ 1595extern tBTM_STATUS BTM_SetEncryption (BD_ADDR bd_addr, tBT_TRANSPORT transport, 1596 tBTM_SEC_CBACK *p_callback, 1597 void *p_ref_data, tBTM_BLE_SEC_ACT sec_act); 1598 1599/******************************************************************************* 1600** 1601** Function BTM_ConfirmReqReply 1602** 1603** Description This function is called to confirm the numeric value for 1604** Simple Pairing in response to BTM_SP_CFM_REQ_EVT 1605** 1606** Parameters: res - result of the operation BTM_SUCCESS if success 1607** bd_addr - Address of the peer device 1608** 1609*******************************************************************************/ 1610extern void BTM_ConfirmReqReply(tBTM_STATUS res, BD_ADDR bd_addr); 1611 1612/******************************************************************************* 1613** 1614** Function BTM_PasskeyReqReply 1615** 1616** Description This function is called to provide the passkey for 1617** Simple Pairing in response to BTM_SP_KEY_REQ_EVT 1618** 1619** Parameters: res - result of the operation BTM_SUCCESS if success 1620** bd_addr - Address of the peer device 1621** passkey - numeric value in the range of 0 - 999999(0xF423F). 1622** 1623*******************************************************************************/ 1624extern void BTM_PasskeyReqReply(tBTM_STATUS res, BD_ADDR bd_addr, uint32_t passkey); 1625 1626/******************************************************************************* 1627** 1628** Function BTM_SendKeypressNotif 1629** 1630** Description This function is used during the passkey entry model 1631** by a device with KeyboardOnly IO capabilities 1632** (very likely to be a HID Device). 1633** It is called by a HID Device to inform the remote device when 1634** a key has been entered or erased. 1635** 1636** Parameters: bd_addr - Address of the peer device 1637** type - notification type 1638** 1639*******************************************************************************/ 1640extern void BTM_SendKeypressNotif(BD_ADDR bd_addr, tBTM_SP_KEY_TYPE type); 1641 1642/******************************************************************************* 1643** 1644** Function BTM_IoCapRsp 1645** 1646** Description This function is called in response to BTM_SP_IO_REQ_EVT 1647** When the event data io_req.oob_data is set to BTM_OOB_UNKNOWN 1648** by the tBTM_SP_CALLBACK implementation, this function is 1649** called to provide the actual response 1650** 1651** Parameters: bd_addr - Address of the peer device 1652** io_cap - The IO capability of local device. 1653** oob - BTM_OOB_NONE or BTM_OOB_PRESENT. 1654** auth_req- MITM protection required or not. 1655** 1656*******************************************************************************/ 1657extern void BTM_IoCapRsp(BD_ADDR bd_addr, tBTM_IO_CAP io_cap, 1658 tBTM_OOB_DATA oob, tBTM_AUTH_REQ auth_req); 1659 1660/******************************************************************************* 1661** 1662** Function BTM_ReadLocalOobData 1663** 1664** Description This function is called to read the local OOB data from 1665** LM 1666** 1667*******************************************************************************/ 1668extern void BTM_ReadLocalOobData(void); 1669 1670/******************************************************************************* 1671** 1672** Function BTM_RemoteOobDataReply 1673** 1674** Description This function is called to provide the remote OOB data for 1675** Simple Pairing in response to BTM_SP_RMT_OOB_EVT 1676** 1677** Parameters: bd_addr - Address of the peer device 1678** c - simple pairing Hash C. 1679** r - simple pairing Randomizer C. 1680** 1681*******************************************************************************/ 1682extern void BTM_RemoteOobDataReply(tBTM_STATUS res, BD_ADDR bd_addr, 1683 BT_OCTET16 c, BT_OCTET16 r); 1684 1685/******************************************************************************* 1686** 1687** Function BTM_BuildOobData 1688** 1689** Description This function is called to build the OOB data payload to 1690** be sent over OOB (non-Bluetooth) link 1691** 1692** Parameters: p_data - the location for OOB data 1693** max_len - p_data size. 1694** c - simple pairing Hash C. 1695** r - simple pairing Randomizer C. 1696** name_len- 0, local device name would not be included. 1697** otherwise, the local device name is included for 1698** up to this specified length 1699** 1700** Returns Number of bytes in p_data. 1701** 1702*******************************************************************************/ 1703extern uint16_t BTM_BuildOobData(uint8_t *p_data, uint16_t max_len, BT_OCTET16 c, 1704 BT_OCTET16 r, uint8_t name_len); 1705 1706/******************************************************************************* 1707** 1708** Function BTM_BothEndsSupportSecureConnections 1709** 1710** Description This function is called to check if both the local device and the peer device 1711** specified by bd_addr support BR/EDR Secure Connections. 1712** 1713** Parameters: bd_addr - address of the peer 1714** 1715** Returns true if BR/EDR Secure Connections are supported by both local 1716** and the remote device. 1717** else false. 1718** 1719*******************************************************************************/ 1720extern bool BTM_BothEndsSupportSecureConnections(BD_ADDR bd_addr); 1721 1722/******************************************************************************* 1723** 1724** Function BTM_PeerSupportsSecureConnections 1725** 1726** Description This function is called to check if the peer supports 1727** BR/EDR Secure Connections. 1728** 1729** Parameters: bd_addr - address of the peer 1730** 1731** Returns true if BR/EDR Secure Connections are supported by the peer, 1732** else false. 1733** 1734*******************************************************************************/ 1735extern bool BTM_PeerSupportsSecureConnections(BD_ADDR bd_addr); 1736 1737/******************************************************************************* 1738** 1739** Function BTM_ReadOobData 1740** 1741** Description This function is called to parse the OOB data payload 1742** received over OOB (non-Bluetooth) link 1743** 1744** Parameters: p_data - the location for OOB data 1745** eir_tag - The associated EIR tag to read the data. 1746** *p_len(output) - the length of the data with the given tag. 1747** 1748** Returns the beginning of the data with the given tag. 1749** NULL, if the tag is not found. 1750** 1751*******************************************************************************/ 1752extern uint8_t * BTM_ReadOobData(uint8_t *p_data, uint8_t eir_tag, uint8_t *p_len); 1753 1754/******************************************************************************* 1755** 1756** Function BTM_SecReadDevName 1757** 1758** Description Looks for the device name in the security database for the 1759** specified BD address. 1760** 1761** Returns Pointer to the name or NULL 1762** 1763*******************************************************************************/ 1764extern char *BTM_SecReadDevName (BD_ADDR bd_addr); 1765 1766 1767/***************************************************************************** 1768** POWER MANAGEMENT FUNCTIONS 1769*****************************************************************************/ 1770/******************************************************************************* 1771** 1772** Function BTM_PmRegister 1773** 1774** Description register or deregister with power manager 1775** 1776** Returns BTM_SUCCESS if successful, 1777** BTM_NO_RESOURCES if no room to hold registration 1778** BTM_ILLEGAL_VALUE 1779** 1780*******************************************************************************/ 1781extern tBTM_STATUS BTM_PmRegister (uint8_t mask, uint8_t *p_pm_id, 1782 tBTM_PM_STATUS_CBACK *p_cb); 1783 1784 1785/******************************************************************************* 1786** 1787** Function BTM_SetPowerMode 1788** 1789** Description store the mode in control block or 1790** alter ACL connection behavior. 1791** 1792** Returns BTM_SUCCESS if successful, 1793** BTM_UNKNOWN_ADDR if bd addr is not active or bad 1794** 1795*******************************************************************************/ 1796extern tBTM_STATUS BTM_SetPowerMode (uint8_t pm_id, BD_ADDR remote_bda, 1797 tBTM_PM_PWR_MD *p_mode); 1798 1799 1800/******************************************************************************* 1801** 1802** Function BTM_ReadPowerMode 1803** 1804** Description This returns the current mode for a specific 1805** ACL connection. 1806** 1807** Input Param remote_bda - device address of desired ACL connection 1808** 1809** Output Param p_mode - address where the current mode is copied into. 1810** BTM_ACL_MODE_NORMAL 1811** BTM_ACL_MODE_HOLD 1812** BTM_ACL_MODE_SNIFF 1813** BTM_ACL_MODE_PARK 1814** (valid only if return code is BTM_SUCCESS) 1815** 1816** Returns BTM_SUCCESS if successful, 1817** BTM_UNKNOWN_ADDR if bd addr is not active or bad 1818** 1819*******************************************************************************/ 1820extern tBTM_STATUS BTM_ReadPowerMode (BD_ADDR remote_bda, 1821 tBTM_PM_MODE *p_mode); 1822 1823/******************************************************************************* 1824** 1825** Function BTM_SetSsrParams 1826** 1827** Description This sends the given SSR parameters for the given ACL 1828** connection if it is in ACTIVE mode. 1829** 1830** Input Param remote_bda - device address of desired ACL connection 1831** max_lat - maximum latency (in 0.625ms)(0-0xFFFE) 1832** min_rmt_to - minimum remote timeout 1833** min_loc_to - minimum local timeout 1834** 1835** 1836** Returns BTM_SUCCESS if the HCI command is issued successful, 1837** BTM_UNKNOWN_ADDR if bd addr is not active or bad 1838** BTM_CMD_STORED if the command is stored 1839** 1840*******************************************************************************/ 1841extern tBTM_STATUS BTM_SetSsrParams (BD_ADDR remote_bda, uint16_t max_lat, 1842 uint16_t min_rmt_to, uint16_t min_loc_to); 1843 1844/******************************************************************************* 1845** 1846** Function BTM_GetHCIConnHandle 1847** 1848** Description This function is called to get the handle for an ACL connection 1849** to a specific remote BD Address. 1850** 1851** Returns the handle of the connection, or 0xFFFF if none. 1852** 1853*******************************************************************************/ 1854extern uint16_t BTM_GetHCIConnHandle (BD_ADDR remote_bda, tBT_TRANSPORT transport); 1855 1856/******************************************************************************* 1857** 1858** Function BTM_DeleteStoredLinkKey 1859** 1860** Description This function is called to delete link key for the specified 1861** device addresses from the NVRAM storage attached to the Bluetooth 1862** controller. 1863** 1864** Parameters: bd_addr - Addresses of the devices 1865** p_cb - Call back function to be called to return 1866** the results 1867** 1868*******************************************************************************/ 1869extern tBTM_STATUS BTM_DeleteStoredLinkKey(BD_ADDR bd_addr, tBTM_CMPL_CB *p_cb); 1870 1871/******************************************************************************* 1872** 1873** Function BTM_WriteEIR 1874** 1875** Description This function is called to write EIR data to controller. 1876** 1877** Parameters p_buff - allocated HCI command buffer including extended 1878** inquriry response 1879** 1880** Returns BTM_SUCCESS - if successful 1881** BTM_MODE_UNSUPPORTED - if local device cannot support it 1882** 1883*******************************************************************************/ 1884extern tBTM_STATUS BTM_WriteEIR( BT_HDR * p_buff ); 1885 1886/******************************************************************************* 1887** 1888** Function BTM_CheckEirData 1889** 1890** Description This function is called to get EIR data from significant part. 1891** 1892** Parameters p_eir - pointer of EIR significant part 1893** type - finding EIR data type 1894** p_length - return the length of EIR data 1895** 1896** Returns pointer of EIR data 1897** 1898*******************************************************************************/ 1899extern uint8_t *BTM_CheckEirData( uint8_t *p_eir, uint8_t type, uint8_t *p_length ); 1900 1901/******************************************************************************* 1902** 1903** Function BTM_HasEirService 1904** 1905** Description This function is called to know if UUID in bit map of UUID. 1906** 1907** Parameters p_eir_uuid - bit map of UUID list 1908** uuid16 - UUID 16-bit 1909** 1910** Returns true - if found 1911** false - if not found 1912** 1913*******************************************************************************/ 1914extern bool BTM_HasEirService( uint32_t *p_eir_uuid, uint16_t uuid16 ); 1915 1916/******************************************************************************* 1917** 1918** Function BTM_HasInquiryEirService 1919** 1920** Description This function is called to know if UUID in bit map of UUID list. 1921** 1922** Parameters p_results - inquiry results 1923** uuid16 - UUID 16-bit 1924** 1925** Returns BTM_EIR_FOUND - if found 1926** BTM_EIR_NOT_FOUND - if not found and it is complete list 1927** BTM_EIR_UNKNOWN - if not found and it is not complete list 1928** 1929*******************************************************************************/ 1930extern tBTM_EIR_SEARCH_RESULT BTM_HasInquiryEirService( tBTM_INQ_RESULTS *p_results, 1931 uint16_t uuid16 ); 1932 1933/******************************************************************************* 1934** 1935** Function BTM_AddEirService 1936** 1937** Description This function is called to add a service in bit map of UUID list. 1938** 1939** Parameters p_eir_uuid - bit mask of UUID list for EIR 1940** uuid16 - UUID 16-bit 1941** 1942** Returns None 1943** 1944*******************************************************************************/ 1945extern void BTM_AddEirService( uint32_t *p_eir_uuid, uint16_t uuid16 ); 1946 1947/******************************************************************************* 1948** 1949** Function BTM_RemoveEirService 1950** 1951** Description This function is called to remove a service in bit map of UUID list. 1952** 1953** Parameters p_eir_uuid - bit mask of UUID list for EIR 1954** uuid16 - UUID 16-bit 1955** 1956** Returns None 1957** 1958*******************************************************************************/ 1959extern void BTM_RemoveEirService( uint32_t *p_eir_uuid, uint16_t uuid16 ); 1960 1961/******************************************************************************* 1962** 1963** Function BTM_GetEirSupportedServices 1964** 1965** Description This function is called to get UUID list from bit map of UUID list. 1966** 1967** Parameters p_eir_uuid - bit mask of UUID list for EIR 1968** p - reference of current pointer of EIR 1969** max_num_uuid16 - max number of UUID can be written in EIR 1970** num_uuid16 - number of UUID have been written in EIR 1971** 1972** Returns BTM_EIR_MORE_16BITS_UUID_TYPE, if it has more than max 1973** BTM_EIR_COMPLETE_16BITS_UUID_TYPE, otherwise 1974** 1975*******************************************************************************/ 1976extern uint8_t BTM_GetEirSupportedServices( uint32_t *p_eir_uuid, uint8_t **p, 1977 uint8_t max_num_uuid16, uint8_t *p_num_uuid16); 1978 1979/******************************************************************************* 1980** 1981** Function BTM_GetEirUuidList 1982** 1983** Description This function parses EIR and returns UUID list. 1984** 1985** Parameters p_eir - EIR 1986** uuid_size - LEN_UUID_16, LEN_UUID_32, LEN_UUID_128 1987** p_num_uuid - return number of UUID in found list 1988** p_uuid_list - return UUID 16-bit list 1989** max_num_uuid - maximum number of UUID to be returned 1990** 1991** Returns 0 - if not found 1992** BTM_EIR_COMPLETE_16BITS_UUID_TYPE 1993** BTM_EIR_MORE_16BITS_UUID_TYPE 1994** BTM_EIR_COMPLETE_32BITS_UUID_TYPE 1995** BTM_EIR_MORE_32BITS_UUID_TYPE 1996** BTM_EIR_COMPLETE_128BITS_UUID_TYPE 1997** BTM_EIR_MORE_128BITS_UUID_TYPE 1998** 1999*******************************************************************************/ 2000extern uint8_t BTM_GetEirUuidList( uint8_t *p_eir, uint8_t uuid_size, uint8_t *p_num_uuid, 2001 uint8_t *p_uuid_list, uint8_t max_num_uuid); 2002 2003/***************************************************************************** 2004** SCO OVER HCI 2005*****************************************************************************/ 2006/******************************************************************************* 2007** 2008** Function BTM_ConfigScoPath 2009** 2010** Description This function enable/disable SCO over HCI and registers SCO 2011** data callback if SCO over HCI is enabled. 2012** 2013** Parameter path: SCO or HCI 2014** p_sco_data_cb: callback function or SCO data if path is set 2015** to transport. 2016** p_pcm_param: pointer to the PCM interface parameter. If a NULL 2017** pointer is used, PCM parameter maintained in 2018** the control block will be used; otherwise update 2019** control block value. 2020** err_data_rpt: Lisbon feature to enable the erronous data report 2021** or not. 2022** 2023** Returns BTM_SUCCESS if the successful. 2024** BTM_NO_RESOURCES: no rsource to start the command. 2025** BTM_ILLEGAL_VALUE: invalid callback function pointer. 2026** BTM_CMD_STARTED :Command sent. Waiting for command cmpl event. 2027** 2028** 2029*******************************************************************************/ 2030extern tBTM_STATUS BTM_ConfigScoPath (tBTM_SCO_ROUTE_TYPE path, 2031 tBTM_SCO_DATA_CB *p_sco_data_cb, 2032 tBTM_SCO_PCM_PARAM *p_pcm_param, 2033 bool err_data_rpt); 2034 2035/******************************************************************************* 2036** 2037** Function BTM_WriteScoData 2038** 2039** Description This function write SCO data to a specified instance. The data 2040** to be written p_buf needs to carry an offset of 2041** HCI_SCO_PREAMBLE_SIZE bytes, and the data length can not 2042** exceed BTM_SCO_DATA_SIZE_MAX bytes, whose default value is set 2043** to 60 and is configurable. Data longer than the maximum bytes 2044** will be truncated. 2045** 2046** Returns BTM_SUCCESS: data write is successful 2047** BTM_ILLEGAL_VALUE: SCO data contains illegal offset value. 2048** BTM_SCO_BAD_LENGTH: SCO data length exceeds the max SCO packet 2049** size. 2050** BTM_NO_RESOURCES: no resources. 2051** BTM_UNKNOWN_ADDR: unknown SCO connection handle, or SCO is not 2052** routed via HCI. 2053** 2054** 2055*******************************************************************************/ 2056extern tBTM_STATUS BTM_WriteScoData (uint16_t sco_inx, BT_HDR *p_buf); 2057 2058/******************************************************************************* 2059** 2060** Function BTM_SetARCMode 2061** 2062** Description Send Audio Routing Control command. 2063** 2064** Returns void 2065** 2066*******************************************************************************/ 2067extern void BTM_SetARCMode (uint8_t iface, uint8_t arc_mode, tBTM_VSC_CMPL_CB *p_arc_cb); 2068 2069 2070/******************************************************************************* 2071** 2072** Function BTM_PCM2Setup_Write 2073** 2074** Description Send PCM2_Setup write command. 2075** 2076** Returns void 2077** 2078*******************************************************************************/ 2079extern void BTM_PCM2Setup_Write (bool clk_master, tBTM_VSC_CMPL_CB *p_arc_cb); 2080 2081 2082/******************************************************************************* 2083** 2084** Function BTM_PM_ReadControllerState 2085** 2086** Description This function is called to obtain the controller state 2087** 2088** Returns Controller state (BTM_CONTRL_ACTIVE, BTM_CONTRL_SCAN, and BTM_CONTRL_IDLE) 2089** 2090*******************************************************************************/ 2091extern tBTM_CONTRL_STATE BTM_PM_ReadControllerState(void); 2092 2093#ifdef __cplusplus 2094} 2095#endif 2096 2097#endif /* BTM_API_H */ 2098