1 /* 2 * Copyright (C) 2021-2022 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup Bluetooth 18 * @{ 19 * 20 * @brief Provides basic Bluetooth capabilities. 21 * 22 * This module allows you to enable and disable Bluetooth, and access basic Bluetooth capabilities.\n 23 * Bluetooth uses profiles such as BT-GAP, BLE, BLE-GATT, BT-data transmission, HFP, A2DP, AVRCP, MAP, and PBAP. 24 * 25 * @since 6 26 */ 27 28 /** 29 * @file ohos_bt_gatt.h 30 * 31 * @brief Declares basic GATT data structures and functions, such as advertising and scan functions. 32 * 33 * @since 6 34 */ 35 36 37 #ifndef OHOS_BT_GATT_H 38 #define OHOS_BT_GATT_H 39 40 #include "ohos_bt_def.h" 41 #include <stdint.h> 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 /** 48 * @brief Enumerates ble address type 49 * 50 * @since 6 51 */ 52 typedef enum { 53 BLE_ADDR_RANDOM = 0x01, 54 } BleAddrType; 55 56 /** 57 * @brief Enumerates advertising filtering parameters. 58 * 59 * The parameters specify whether the advertiser uses a whitelist to filter scan or connection requests from scanners. 60 * 61 * @since 6 62 */ 63 typedef enum { 64 /** Processing scan and connection requests from all devices */ 65 OHOS_BLE_ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY = 0x00, 66 /** Processing connection requests from all devices and only the scan requests from devices in the whitelist */ 67 OHOS_BLE_ADV_FILTER_ALLOW_SCAN_WLST_CON_ANY = 0x01, 68 /** Processing scan requests from all devices and only the connection requests from devices in the whitelist */ 69 OHOS_BLE_ADV_FILTER_ALLOW_SCAN_ANY_CON_WLST = 0x02, 70 /** Processing only the scan and connection requests from devices in the whitelist */ 71 OHOS_BLE_ADV_FILTER_ALLOW_SCAN_WLST_CON_WLST = 0x03, 72 } BleAdvFilter; 73 74 /** 75 * @brief Enumerates advertisement types. 76 * 77 * @since 6 78 */ 79 typedef enum { 80 /** Connectable and scannable undirected advertisement (default) */ 81 OHOS_BLE_ADV_IND = 0x00, 82 /** Connectable directed advertisement with a high duty ratio */ 83 OHOS_BLE_ADV_DIRECT_IND_HIGH = 0x01, 84 /** Scannable undirected advertisement */ 85 OHOS_BLE_ADV_SCAN_IND = 0x02, 86 /** Unconnectable undirected advertisement */ 87 OHOS_BLE_ADV_NONCONN_IND = 0x03, 88 /** Connectable directed advertisement with a low duty ratio */ 89 OHOS_BLE_ADV_DIRECT_IND_LOW = 0x04, 90 } BleAdvType; 91 92 /** 93 * @brief Enumerates I/O capability modes. 94 * 95 * @since 6 96 */ 97 typedef enum { 98 /** <b>DisplayOnly</b>: display capability only */ 99 OHOS_BLE_IO_CAP_OUT = 0x00, 100 /** <b>DisplayYesNo</b>: YES/NO input and display capabilities */ 101 OHOS_BLE_IO_CAP_IO, 102 /** 103 * <b>KeyboardOnly</b>: Input of a number from 0 to 9, the confirmation key, and YES/NO, 104 * with no display capability 105 */ 106 OHOS_BLE_IO_CAP_IN, 107 /** <b>NoInputNoOutput</b>: no I/O capability */ 108 OHOS_BLE_IO_CAP_NONE, 109 /** 110 * <b>KeyboardDisplay</b>: Input of a number from 0 to 9, the confirmation key, and YES/NO, 111 * with the display capability 112 */ 113 OHOS_BLE_IO_CAP_KBDISP 114 } BleIoCapMode; 115 116 /** 117 * @brief Enumerates authentication modes for secure connection requests. 118 * 119 * @since 6 120 */ 121 typedef enum { 122 /** No bonding */ 123 OHOS_BLE_AUTH_NO_BOND = 0x00, 124 /** Bonding */ 125 OHOS_BLE_AUTH_BOND, 126 /** MITM only */ 127 OHOS_BLE_AUTH_REQ_MITM, 128 /** Secure connection only */ 129 OHOS_BLE_AUTH_REQ_SC_ONLY, 130 /** Secure connection and bonding */ 131 OHOS_BLE_AUTH_REQ_SC_BOND, 132 /** Secure connection and MITM */ 133 OHOS_BLE_AUTH_REQ_SC_MITM, 134 /** Secure connection, MITM, and bonding */ 135 OHOS_BLE_AUTH_REQ_SC_MITM_BOND 136 } BleAuthReqMode; 137 138 /** 139 * @brief Enumerates BLE scan types. 140 * 141 * @since 6 142 */ 143 typedef enum { 144 /** A passive scan with no scan request */ 145 OHOS_BLE_SCAN_TYPE_PASSIVE = 0x00, 146 /** An active scan that may contain a scan request */ 147 OHOS_BLE_SCAN_TYPE_ACTIVE, 148 } BleScanType; 149 150 /** 151 * @brief Enumerates BLE scan modes. 152 * 153 * @since 6 154 */ 155 typedef enum { 156 /** Low power */ 157 OHOS_BLE_SCAN_MODE_LOW_POWER = 0x00, 158 /** Balance */ 159 OHOS_BLE_SCAN_MODE_BALANCED = 0x01, 160 /** Low latency */ 161 OHOS_BLE_SCAN_MODE_LOW_LATENCY = 0x02, 162 /** Duty cycle 2 */ 163 OHOS_BLE_SCAN_MODE_OP_P2_60_3000 = 0x03, 164 /** Duty cycle 10 */ 165 OHOS_BLE_SCAN_MODE_OP_P10_60_600 = 0x04, 166 /** Duty cycle 25 */ 167 OHOS_BLE_SCAN_MODE_OP_P25_60_240 = 0x05, 168 /** Duty cycle 100 */ 169 OHOS_BLE_SCAN_MODE_OP_P100_1000_1000 = 0x06, 170 /** Duty cycle 50 */ 171 OHOS_BLE_SCAN_MODE_OP_P50_100_200 = 0x07, 172 /** Duty cycle 10 30/300 */ 173 OHOS_BLE_SCAN_MODE_OP_P10_30_300 = 0x08, 174 /** Duty cycle 2 30/1500 */ 175 OHOS_BLE_SCAN_MODE_OP_P2_30_1500 = 0x09, 176 /** Duty cycle 75 30/40 */ 177 OHOS_BLE_SCAN_MODE_OP_P75_30_40 = 0x0A, 178 /** Duty cycle 50 30/60 */ 179 OHOS_BLE_SCAN_MODE_OP_P50_30_60 = 0x0B, 180 } BleScanMode; 181 182 /** 183 * @brief Enumerates policies for filtering advertisements in a BLE scan. 184 * 185 * @since 6 186 */ 187 typedef enum { 188 /** 189 * Accepting all advertisements except the directed advertisements 190 * that are not sent to the current device (default) 191 */ 192 OHOS_BLE_SCAN_FILTER_POLICY_ACCEPT_ALL = 0x00, 193 /** 194 * Accepting advertisements from devices in the whitelist and ignoring the directed advertisements 195 * that are not sent to the current device */ 196 OHOS_BLE_SCAN_FILTER_POLICY_ONLY_WHITE_LIST, 197 /** 198 * Accepting all undirected advertisements, directed advertisements sent by advertisers with 199 * resolvable private addresses, and all the directed advertisements sent to the current device 200 */ 201 OHOS_BLE_SCAN_FILTER_POLICY_ACCEPT_ALL_AND_RPA, 202 /** 203 * Accepting all undirected advertisements from the devices in the whitelist, 204 * directed advertisements sent by advertisers with resolvable private addresses, 205 * and all the directed advertisements sent to the current device 206 */ 207 OHOS_BLE_SCAN_FILTER_POLICY_ONLY_WHITE_LIST_AND_RPA 208 } BleScanFilterPolicy; 209 210 /** 211 * @brief Enumerates advertisement types in the BLE scan result. 212 * 213 * @since 6 214 */ 215 typedef enum { 216 /** Extended, unconnectable, unscannable, and undirected advertisement */ 217 OHOS_BLE_EVT_NON_CONNECTABLE_NON_SCANNABLE = 0x00, 218 /** Extended, unconnectable, unscannable, and directed advertisement */ 219 OHOS_BLE_EVT_NON_CONNECTABLE_NON_SCANNABLE_DIRECTED = 0x04, 220 /** Extended, connectable, and undirected advertisement */ 221 OHOS_BLE_EVT_CONNECTABLE = 0x01, 222 /** Extended, connectable, and directed advertisement */ 223 OHOS_BLE_EVT_CONNECTABLE_DIRECTED = 0x05, 224 /** Extended, scannable, and undirected advertisement */ 225 OHOS_BLE_EVT_SCANNABLE = 0x02, 226 /** Extended, scannable, and directed advertisement */ 227 OHOS_BLE_EVT_SCANNABLE_DIRECTED = 0x06, 228 229 /** Legacy, unconnectable, and undirected advertisement */ 230 OHOS_BLE_EVT_LEGACY_NON_CONNECTABLE = 0x10, 231 /** Legacy, scannable, and undirected advertisement */ 232 OHOS_BLE_EVT_LEGACY_SCANNABLE = 0x12, 233 /** Legacy, connectable, scannable, and undirected advertisement */ 234 OHOS_BLE_EVT_LEGACY_CONNECTABLE = 0x13, 235 /** Legacy, connectable, and directed advertisement */ 236 OHOS_BLE_EVT_LEGACY_CONNECTABLE_DIRECTED = 0x15, 237 /** Legacy scan response corresponding to <b>ADV_SCAN_IND</b> */ 238 OHOS_BLE_EVT_LEGACY_SCAN_RSP_TO_ADV_SCAN = 0x1A, 239 /** Legacy scan response corresponding to <b>ADV_IND</b> */ 240 OHOS_BLE_EVT_LEGACY_SCAN_RSP_TO_ADV = 0x1B 241 } BleScanResultEvtType; 242 243 /** 244 * @brief Enumerates data integrity types for a BLE scan result. 245 * 246 * @since 6 247 */ 248 typedef enum { 249 /** Complete data or the last segment */ 250 OHOS_BLE_DATA_COMPLETE = 0x00, 251 /** Incomplete data, with more data to come */ 252 OHOS_BLE_DATA_INCOMPLETE_MORE_TO_COME = 0x01, 253 /** Incomplete truncated data, with no more data to come */ 254 OHOS_BLE_DATA_INCOMPLETE_TRUNCATED = 0x02, 255 } BleScanResultDataStatus; 256 257 /** 258 * @brief Enumerates address types for a BLE scan result. 259 * 260 * @since 6 261 */ 262 typedef enum { 263 /** Public device address */ 264 OHOS_BLE_PUBLIC_DEVICE_ADDRESS = 0x00, 265 /** Random device address */ 266 OHOS_BLE_RANDOM_DEVICE_ADDRESS = 0x01, 267 /** Public identity address */ 268 OHOS_BLE_PUBLIC_IDENTITY_ADDRESS = 0x02, 269 /** Random (static) identity address */ 270 OHOS_BLE_RANDOM_STATIC_IDENTITY_ADDRESS = 0x03, 271 /** Unresolvable random device address */ 272 OHOS_BLE_UNRESOLVABLE_RANDOM_DEVICE_ADDRESS = 0xFE, 273 /** No address (anonymous advertisement) */ 274 OHOS_BLE_NO_ADDRESS = 0xFF, 275 } BleScanResultAddrType; 276 277 /** 278 * @brief Enumerates PHY types for a BLE scan result. 279 * 280 * @since 6 281 */ 282 typedef enum { 283 /** No advertisement packet */ 284 OHOS_BLE_SCAN_PHY_NO_PACKET = 0x00, 285 /** 1M PHY */ 286 OHOS_BLE_SCAN_PHY_1M = 0x01, 287 /** 2M PHY */ 288 OHOS_BLE_SCAN_PHY_2M = 0x02, 289 /** Coded PHY */ 290 OHOS_BLE_SCAN_PHY_CODED = 0x03 291 } BleScanResultPhyType; 292 293 /** 294 * @brief Update scan filter parameters action. 295 * 296 * @since 16 297 */ 298 typedef enum { 299 BLE_SCAN_UPDATE_FILTER_NONE, 300 BLE_SCAN_UPDATE_FILTER_ADD, 301 BLE_SCAN_UPDATE_FILTER_DELETE, 302 BLE_SCAN_UPDATE_FILTER_MODIFY, 303 } BleScanUpdateFilterAction; 304 305 /** 306 * @brief Defines BLE advertising own address parameters. 307 * 308 * @since 6 309 */ 310 typedef struct { 311 uint8_t addr[OHOS_BD_ADDR_LEN]; // little endian 312 BleAddrType addrType; 313 } AdvOwnAddrParams; 314 315 /** 316 * @brief Defines BLE advertising parameters. 317 * 318 * @since 6 319 */ 320 typedef struct { 321 /** 322 * Minimum advertising interval. 323 * It is calculated as follows: [N * 0.625 ms], where N indicates the value of this field. 324 */ 325 int minInterval; 326 /** 327 * Maximum advertising interval. 328 * It is calculated as follows: [N * 0.625 ms], where N indicates the value of this field. 329 */ 330 int maxInterval; 331 /** Advertising type */ 332 BleAdvType advType; 333 /** Local address type */ 334 unsigned char ownAddrType; 335 /** Peer address type */ 336 unsigned char peerAddrType; 337 /** Peer address */ 338 BdAddr peerAddr; 339 /** 340 * Advertising channel to be used. For example, <b>0x01</b> indicates that channel 37 is to be used, 341 * and <b>0x07</b> indicates that channels 37, 38, and 39 are used. 342 */ 343 int channelMap; 344 /** Advertisement filtering policy based on a whitelist */ 345 BleAdvFilter advFilterPolicy; 346 /** Transmit power (dBm) */ 347 int txPower; 348 /** Advertising duration. It is calculated as follows: [N * 10 ms], where N indicates the value of this field. */ 349 int duration; 350 } BleAdvParams; 351 352 /** 353 * @brief Defines BLE scan parameters. 354 * 355 * @since 6 356 */ 357 typedef struct { 358 /** Scan interval. It is calculated as follows: [N * 0.625 ms], where N indicates the value of this field. */ 359 unsigned short scanInterval; 360 /** Scan window. It is calculated as follows: [N * 0.625 ms], where N indicates the value of this field. */ 361 unsigned short scanWindow; 362 /** Scan type, as enumerated in {@link BleScanType} */ 363 unsigned char scanType; 364 /** 365 * PHY on which the advertising packets are received. 366 * <b>bit0</b> indicates 1M PHY and <b>bit2</b> indicates LE Coded PHY. 367 * <b>bit0</b> and <b>bit2</b> can both be set to <b>1</b>. All other bits are reserved for future use. 368 */ 369 unsigned char scanPhy; 370 /** Policy for filtering the scan result, as enumerated in {@link BleScanFilterPolicy} */ 371 unsigned char scanFilterPolicy; 372 } BleScanParams; 373 374 /** 375 * @brief Defines BLE scan native filter. 376 * 377 * @since 6 378 */ 379 typedef struct { 380 /** Handling advertisments sent by advertisers with specific address */ 381 char *address; 382 /** Handling advertisments sent by advertisers with specific deviceName */ 383 char *deviceName; 384 /** The length of the service uuid */ 385 unsigned int serviceUuidLength; 386 /** Handling advertisments sent by advertisers with specific service uuid */ 387 unsigned char *serviceUuid; 388 /** Handling advertisments sent by advertisers with specific service uuid mask */ 389 unsigned char *serviceUuidMask; 390 /** The length of the service data */ 391 unsigned int serviceDataLength; 392 /** Handling advertisments sent by advertisers with specific serviceData */ 393 unsigned char *serviceData; 394 /** Handling advertisments sent by advertisers with specific serviceDataMask */ 395 unsigned char *serviceDataMask; 396 /** The length of the manufacture data */ 397 unsigned int manufactureDataLength; 398 /** Handling advertisments sent by advertisers with specific manufactureData */ 399 unsigned char *manufactureData; 400 /** Handling advertisments sent by advertisers with specific manufactureDataMask */ 401 unsigned char *manufactureDataMask; 402 /** Handling advertisments sent by advertisers with specific manufactureId */ 403 unsigned short manufactureId; 404 /** Adv_Ind Report */ 405 bool advIndReport; 406 /** Scan filter identifier index */ 407 uint8_t filterIndex; 408 } BleScanNativeFilter; 409 410 /** 411 * @brief Defines BLE scan configurations. 412 * 413 * @since 6 414 */ 415 typedef struct { 416 /** Repport delay time */ 417 long reportDelayMillis; 418 /** Scan mode */ 419 int scanMode; 420 /** Legacy */ 421 bool legacy; 422 /** Phy */ 423 int phy; 424 } BleScanConfigs; 425 426 /** 427 * @brief Defines raw data for the BLE advertising and scan response. 428 * 429 * This structure is available for system applications only. 430 * 431 * @since 6 432 */ 433 typedef struct { 434 /** Advertising data */ 435 unsigned char *advData; 436 /** Advertising data length */ 437 unsigned int advDataLen; 438 /** Scan response data */ 439 unsigned char *rspData; 440 /** Scan response data length */ 441 unsigned int rspDataLen; 442 } StartAdvRawData; 443 444 /** 445 * @brief Defines the BLE scan result data. 446 * 447 * @since 6 448 */ 449 typedef struct { 450 /** Advertisement type, as enumerated in {@link BleScanResultEvtType} */ 451 unsigned char eventType; 452 /** Data status, as enumerated in {@link BleScanResultDataStatus} */ 453 unsigned char dataStatus; 454 /** Address type, as enumerated in {@link BleScanResultAddrType}. Value <b>0xFE</b> is unavailable. */ 455 unsigned char addrType; 456 /** Address */ 457 BdAddr addr; 458 /** 459 * PHY type of a primary advertisement, as enumerated in {@link BleScanResultPhyType}. 460 * The value can only be <b>0x01</b> or <b>0x03</b>. 461 */ 462 unsigned char primaryPhy; 463 /** 464 * PHY type of a secondary advertisement. 465 * The value can be any of the enumerations of {@link BleScanResultPhyType}. 466 */ 467 unsigned char secondaryPhy; 468 /** 469 * Advertising SID in the ADI field of the PDU or of the original scannable advertisement (for scan responses). 470 * Value <b>0xFF</b> indicates that no ADI field is available. 471 */ 472 unsigned char advSid; 473 /** 474 * Transmit power. The value ranges from -127 to +20 dBm. 475 * Value <b>0x7F</b> indicates that this field is invalid. 476 */ 477 char txPower; 478 /** RSSI. The value ranges from -127 to +20 dBm. Value <b>0x7F</b> indicates that this field is invalid. */ 479 char rssi; 480 /** 481 * Periodic advertising interval. 482 * It is calculated as follows: [N * 1.25 ms], where N indicates the value of this field. 483 * Value <b>0x00</b> indicates that this field is invalid. 484 */ 485 unsigned short periodicAdvInterval; 486 /** 487 * Address type for directed advertising, as enumerated in {@link BleScanResultAddrType}. 488 * Value <b>0xFF</b> is unavailable. 489 */ 490 unsigned char directAddrType; 491 /** Address for directed advertising */ 492 BdAddr directAddr; 493 /** Advertising data length */ 494 unsigned char advLen; 495 /** Advertising data */ 496 unsigned char *advData; 497 } BtScanResultData; 498 499 typedef struct { 500 char deviceId[OHOS_ACTIVE_DEVICE_ID_LEN]; 501 int status; 502 int timeOut; 503 } BtActiveDeviceInfo; 504 505 typedef struct { 506 BleScanConfigs *scanConfig; 507 BleScanNativeFilter *filter; 508 unsigned int filterSize; 509 BleAdvParams advParam; 510 StartAdvRawData rawData; 511 BtUuid uuid; 512 BtActiveDeviceInfo *activeDeviceInfo; 513 unsigned int activeDeviceSize; 514 int advHandle; 515 int duration; 516 int deliveryMode; 517 } BtLpDeviceParam; 518 519 /** 520 * @brief Called when advertising is enabled. For details, see {@link BleStartAdv}. 521 * 522 * @since 6 523 */ 524 typedef void (*AdvEnableCallback)(int advId, int status); 525 526 /** 527 * @brief Called when advertising is disabled. For details, see {@link BleStopAdv}. 528 * 529 * @since 6 530 */ 531 typedef void (*AdvDisableCallback)(int advId, int status); 532 533 /** 534 * @brief Called when advertising data is set. For details, see {@link BleSetAdvData}. 535 * 536 * @since 6 537 */ 538 typedef void (*AdvDataCallback)(int advId, int status); 539 540 /** 541 * @brief Called when advertising parameters are updated. For details, see {@link BleUpdateAdv} 542 * 543 * @since 6 544 */ 545 typedef void (*AdvUpdateCallback)(int advId, int status); 546 547 /** 548 * @brief Called when a secure access request is received. 549 * 550 * {@link BleGattSecurityRsp} is used to grant the secure access permission. 551 * 552 * @since 6 553 */ 554 typedef void (*SecurityRespondCallback)(const BdAddr *bdAddr); 555 556 /** 557 * @brief Called when the scan result is received. 558 * 559 * @since 6 560 */ 561 typedef void (*ScanResultCallback)(BtScanResultData *scanResultdata); 562 563 /** 564 * @brief Called when scan parameters are set. 565 * 566 * @since 6 567 */ 568 typedef void (*ScanParameterSetCompletedCallback)(int clientId, int status); 569 570 typedef void (*LpDeviceInfoCallback)(BtUuid *uuid, int32_t type, uint8_t *data, uint32_t dataSize); 571 572 typedef void (*ScanStateChangeCallback)(int32_t resultCode, bool isStartScan); 573 574 /** 575 * @brief Called when advertising is enabled. For details, see {@link BleEnableAdvEx}. 576 * 577 * @since 16 578 */ 579 typedef void (*AdvEnableExCallback)(int advId, int status); 580 581 /** 582 * @brief Called when advertising is disabled. For details, see {@link BleDisableAdvEx}. 583 * 584 * @since 16 585 */ 586 typedef void (*AdvDisableExCallback)(int advId, int status); 587 588 /** 589 * @brief Called when advertising setting is changed. For details, see {@link BleChangeAdvParams}. 590 * 591 * @since 16 592 */ 593 typedef void (*AdvChangedCallback)(int advId, int status); 594 595 /** 596 * @brief Defines GATT callbacks. 597 * 598 * @since 6 599 */ 600 typedef struct { 601 /** Called when advertising is enabled. */ 602 AdvEnableCallback advEnableCb; 603 /** Called when advertising is disabled. */ 604 AdvDisableCallback advDisableCb; 605 /** Called when advertising data is set. */ 606 AdvDataCallback advDataCb; 607 /** Called when advertising parameters are updated. */ 608 AdvUpdateCallback advUpdateCb; 609 /** Called when a secure access request is received. */ 610 SecurityRespondCallback securityRespondCb; 611 /** Called when advertising is changed from disabled to enabled */ 612 AdvEnableExCallback onEnableExCb; 613 /** Called when advertising is changed form enabled to disabled */ 614 AdvDisableExCallback onDisableExCb; 615 /** Called when advertising setting is changed */ 616 AdvChangedCallback advChangeCb; 617 } BtGattCallbacks; 618 619 /** 620 * @brief Defines ble scan callbacks. 621 * 622 * @since 6 623 */ 624 typedef struct { 625 /** Called when the scan result is received. */ 626 ScanResultCallback scanResultCb; 627 /** Called when scan state change. */ 628 ScanStateChangeCallback scanStateChangeCb; 629 /** Called when low power device notify msg. */ 630 LpDeviceInfoCallback lpDeviceInfoCb; 631 } BleScanCallbacks; 632 633 /** 634 * @brief Initializes the Bluetooth protocol stack. 635 * 636 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the Bluetooth protocol stack is initialized; 637 * returns an error code defined in {@link BtStatus} otherwise. 638 * @since 6 639 */ 640 int InitBtStack(void); 641 642 /** 643 * @brief Enables the Bluetooth protocol stack. 644 * 645 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the Bluetooth protocol stack is enabled; 646 * returns an error code defined in {@link BtStatus} otherwise. 647 * @since 6 648 */ 649 int EnableBtStack(void); 650 651 /** 652 * @brief Disables the Bluetooth protocol stack. 653 * 654 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the Bluetooth protocol stack is disabled; 655 * returns an error code defined in {@link BtStatus} otherwise. 656 * @since 6 657 */ 658 int DisableBtStack(void); 659 660 /** 661 * @brief Sets the Bluetooth device name. 662 * 663 * @param name Indicates the pointer to the name to set. 664 * @param len Indicates the length of the name to set. 665 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the Bluetooth device name is set; 666 * returns an error code defined in {@link BtStatus} otherwise. 667 * @since 6 668 */ 669 int SetDeviceName(const char *name, unsigned int len); 670 671 /** 672 * @brief Sets advertising data. 673 * 674 * @param advId Indicates the advertisement ID, which is allocated by the upper layer of the advertiser. 675 * @param data Indicates the pointer to the advertising data. For details, see {@link StartAdvRawData}. 676 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if advertising data is set; 677 * returns an error code defined in {@link BtStatus} otherwise. 678 * @since 6 679 */ 680 int BleSetAdvData(int advId, const StartAdvRawData data); 681 682 /** 683 * @brief Starts advertising. 684 * 685 * @param advId Indicates the advertisement ID, which is allocated by the upper layer of the advertiser. 686 * @param param Indicates the pointer to the advertising parameters. For details, see {@link BleAdvParams}. 687 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if advertising is started; 688 * returns an error code defined in {@link BtStatus} otherwise. 689 * @since 6 690 */ 691 int BleStartAdv(int advId, const BleAdvParams *param); 692 693 /** 694 * @brief Stops advertising. 695 * 696 * @param advId Indicates the advertisement ID, which is allocated by the upper layer of the advertiser. 697 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if advertising is stopped; 698 * returns an error code defined in {@link BtStatus} otherwise. 699 * @since 6 700 */ 701 int BleStopAdv(int advId); 702 703 /** 704 * @brief Updates advertising parameters. 705 * 706 * @param advId Indicates the advertisement ID, which is allocated by the upper layer of the advertiser. 707 * @param param Indicates the pointer to the advertising parameters. For details, see {@link BleAdvParams}. 708 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if advertising parameters are updated; 709 * returns an error code defined in {@link BtStatus} otherwise. 710 * @since 6 711 */ 712 int BleUpdateAdv(int advId, const BleAdvParams *param); 713 714 /** 715 * @brief Sets the secure I/O capability mode. 716 * 717 * @param mode Indicates the capability mode to set. For details, see {@link BleIoCapMode}. 718 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the capability mode is set; 719 * returns an error code defined in {@link BtStatus} otherwise. 720 * @since 6 721 */ 722 int BleSetSecurityIoCap(BleIoCapMode mode); 723 724 /** 725 * @brief Sets the authentication mode for secure connection requests. 726 * 727 * @param mode Indicates the authentication mode to set. For details, see {@link BleAuthReqMode}. 728 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the authentication mode is set; 729 * returns an error code defined in {@link BtStatus} otherwise. 730 * @since 6 731 */ 732 int BleSetSecurityAuthReq(BleAuthReqMode mode); 733 734 /** 735 * @brief Responds to a secure connection request. 736 * 737 * @param bdAddr Indicates the address of the device that sends the request. 738 * @param accept Specifies whether to accept the request. The value <b>true</b> means to accept the request, 739 * and <b>false</b> means to reject the request. 740 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the request is responded to; 741 * returns an error code defined in {@link BtStatus} otherwise. 742 * @since 6 743 */ 744 int BleGattSecurityRsp(BdAddr bdAddr, bool accept); 745 746 /** 747 * @brief Obtains the device MAC address. 748 * 749 * @param mac Indicates the pointer to the device MAC address. 750 * @param len Indicates the length of the device MAC address. 751 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the device MAC address is obtained; 752 * returns an error code defined in {@link BtStatus} otherwise. 753 * @since 6 754 */ 755 int ReadBtMacAddr(unsigned char *mac, unsigned int len); 756 757 /** 758 * @brief Sets scan parameters. 759 * 760 * @param clientId Indicates the client ID, which is obtained during client registration. 761 * @param param Indicates the pointer to the scan parameters. For details, see {@link BleScanParams}. 762 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the scan parameters are set; 763 * returns an error code defined in {@link BtStatus} otherwise. 764 * @since 6 765 */ 766 int BleSetScanParameters(int clientId, BleScanParams *param); 767 768 /** 769 * @brief Starts a scan. 770 * 771 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the scan is started; 772 * returns an error code defined in {@link BtStatus} otherwise. 773 * @since 6 774 */ 775 int BleStartScan(void); 776 777 /** 778 * @brief Stops a scan. 779 * 780 * @param scannerId Indicates the scanner id. 781 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the scan is stopped; 782 * returns an error code defined in {@link BtStatus} otherwise. 783 * @since 6 784 */ 785 int BleStopScan(int32_t scannerId); 786 787 /** 788 * @brief Registers GATT callbacks. 789 * 790 * @param func Indicates the pointer to the callbacks to register. For details, see {@link BtGattCallbacks}. 791 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the GATT callbacks are registered; 792 * returns an error code defined in {@link BtStatus} otherwise. 793 * @since 6 794 */ 795 int BleGattRegisterCallbacks(BtGattCallbacks *func); 796 797 /** 798 * @brief Register ble scan callbacks. 799 * 800 * @param func Indicates the pointer to the callbacks to register. For details, see {@link BleScanCallbacks}. 801 * @param scannerId Indicates the pointer to the scannerId, identify one scan. 802 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the BLE callbacks are registered; 803 * returns an error code defined in {@link BtStatus} otherwise. 804 * @since 6 805 */ 806 int BleRegisterScanCallbacks(BleScanCallbacks *func, int32_t *scannerId); 807 808 /** 809 * @brief Deregister ble scan callbacks. 810 * 811 * @param scannerId Indicates the scanner id. 812 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the BLE callbacks are deregistered; 813 * returns an error code defined in {@link BtStatus} otherwise. 814 * @since 6 815 */ 816 int BleDeregisterScanCallbacks(int32_t scannerId); 817 818 /** 819 * @brief Sets own address, own address type, advertising data and parameters and starts advertising. 820 * 821 * This function is available for softbus only. 822 * 823 * @param advId Indicates the pointer to the advertisement ID. 824 * @param rawData Indicates the advertising data. For details, see {@link StartAdvRawData}. 825 * @param advParam Indicates the advertising parameters. For details, see {@link BleAdvParams}. 826 * @param ownAddrParams Indicates the own address(little endian) and own address type. 827 * For details, see {@link AdvOwnAddrParams}. 828 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the operation is successful; 829 * returns an error code defined in {@link BtStatus} otherwise. 830 * @since 6 831 */ 832 int BleStartAdvWithAddr(int *advId, const StartAdvRawData *rawData, const BleAdvParams *advParam, 833 const AdvOwnAddrParams *ownAddrParams); 834 835 /** 836 * @brief Sets advertising data and parameters and starts advertising. 837 * 838 * This function is available for system applications only. \n 839 * 840 * @param advId Indicates the pointer to the advertisement ID. 841 * @param rawData Indicates the advertising data. For details, see {@link StartAdvRawData}. 842 * @param advParam Indicates the advertising parameters. For details, see {@link BleAdvParams}. 843 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the operation is successful; 844 * returns an error code defined in {@link BtStatus} otherwise. 845 * @since 6 846 */ 847 int BleStartAdvEx(int *advId, const StartAdvRawData rawData, BleAdvParams advParam); 848 849 /** 850 * @brief Enable advertising. 851 * 852 * This function is available for system applications only. \n 853 * 854 * @param advId Indicates the pointer to the advertisement ID. 855 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the operation is successful; 856 * returns an error code defined in {@link BtStatus} otherwise. 857 * @since 11 858 */ 859 int BleEnableAdvEx(int advId); 860 861 /** 862 * @brief Disable advertising. 863 * 864 * This function is available for system applications only. \n 865 * 866 * @param advId Indicates the pointer to the advertisement ID. 867 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the operation is successful; 868 * returns an error code defined in {@link BtStatus} otherwise. 869 * @since 11 870 */ 871 int BleDisableAdvEx(int advId); 872 873 /** 874 * @brief Starts a scan with BleScanConfigs. 875 * If don't need ble scan filter, set BleScanNativeFilter to NULL or filterSize to zero. 876 * If one of the ble scan filtering rules is not required, set it to NULL. 877 * For example, set the address to NULL when you don't need it. 878 * Don't support only using manufactureId as filter conditions, need to use it with manufactureData. 879 * The manufactureId need to be set a related number when you need a filtering condition of manufactureData. 880 * 881 * @param scannerId Indicates the scanner id. 882 * @param configs Indicates the pointer to the scan filter. For details, see {@link BleScanConfigs}. 883 * @param filter Indicates the pointer to the scan filter. For details, see {@link BleScanNativeFilter}. 884 * @param filterSize Indicates the number of the scan filter. 885 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the scan is started; 886 * returns an error code defined in {@link BtStatus} otherwise. 887 * @since 6 888 */ 889 int BleStartScanEx(int32_t scannerId, const BleScanConfigs *configs, const BleScanNativeFilter *filter, 890 uint32_t filterSize); 891 /** 892 * @brief set low power device adv param. 893 * 894 * @param duration advertise duration. 895 * @param maxExtAdvEvents maximum number of extended advertising events. 896 * @param window work window. 897 * @param interval work interval. 898 * @param advHandle Indicates the advertise handle. 899 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if set success; 900 * returns an error code defined in {@link BtStatus} otherwise. 901 * @since 6 902 */ 903 int SetLpDeviceAdvParam(int duration, int maxExtAdvEvents, int window, int interval, int advHandle); 904 905 /** 906 * @brief Set scan report channel. 907 * 908 * @param scannerId Indicates the scanner id. 909 * @param enable true：report to low power device; false：not report to low power device. 910 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if set report channel success; 911 * returns an error code defined in {@link BtStatus} otherwise. 912 * @since 6 913 */ 914 int SetScanReportChannelToLpDevice(int32_t scannerId, bool enable); 915 916 /** 917 * @brief Enable synchronizing data to low power device. 918 * 919 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if enable sync success; 920 * returns an error code defined in {@link BtStatus} otherwise. 921 * @since 6 922 */ 923 int EnableSyncDataToLpDevice(void); 924 925 /** 926 * @brief Disable synchronizing data to the low power device. 927 * 928 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if disable sync success; 929 * returns an error code defined in {@link BtStatus} otherwise. 930 * @since 6 931 */ 932 int DisableSyncDataToLpDevice(void); 933 934 /** 935 * @brief Get advertiser handle. 936 * 937 * @param advId Indicates the advertisement ID. 938 * @param advHandle Indicates the pointer to the advertiser handle. 939 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if get success; 940 * returns an error code defined in {@link BtStatus} otherwise. 941 * @since 6 942 */ 943 int GetAdvHandle(int advId, int *advHandle); 944 945 /** 946 * @brief Translate ParamData to low power device. 947 * 948 * @param data Indicates the pointer to the data. 949 * @param dataSize Indicates the data size. 950 * @param type Indicates the data type. 951 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if set param to low power device success; 952 * returns an error code defined in {@link BtStatus} otherwise. 953 * @since 6 954 */ 955 int SendParamsToLpDevice(const uint8_t *data, uint32_t dataSize, int32_t type); 956 957 /** 958 * @brief Get whether low power device available. 959 * 960 * @return true: available; false: not available. 961 * @since 6 962 */ 963 bool IsLpDeviceAvailable(void); 964 965 /** 966 * @brief Set low power device Param. 967 * 968 * @param lpDeviceParam the param set to low power device. 969 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if set lpDeviceParam success; 970 * returns an error code defined in {@link BtStatus} otherwise. 971 * @since 6 972 */ 973 int SetLpDeviceParam(const BtLpDeviceParam *lpDeviceParam); 974 975 /** 976 * @brief Remove low power device Param. 977 * 978 * @param uuid Uuid. 979 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if remove success; 980 * returns an error code defined in {@link BtStatus} otherwise. 981 * @since 6 982 */ 983 int RemoveLpDeviceParam(BtUuid uuid); 984 985 /** 986 * @brief Clear global resource when ble turn on or bluetooth_serivce unload. 987 * @since 11 988 */ 989 void ClearGlobalResource(void); 990 991 /** 992 * @brief start RPA adv addr timer 993 * @param advHandle Indicates the advertise handle. 994 * @param ownAddrParams Indicates the own address(little endian) and own address type. 995 * @return true: start timer; false: start timer fail. 996 * @since 12 997 */ 998 bool StartAdvAddrTimer(int advHandle, const AdvOwnAddrParams *ownAddrParams); 999 1000 /** 1001 * @brief Change Advertising parameters when adv is disabled. If advertising started, an error will be returned. 1002 * 1003 * @param advId Indicates the advertisement ID. 1004 * @param advParam Indicates the advertising parameters. For details, see {@link BleAdvParams}. If you don't want 1005 * to cahnge current advertising address, please set ownAddr to 0xFF. 1006 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the advertising is started. 1007 * returns an error code defined in {@link BtStatus} otherwise. 1008 * @since 16 1009 */ 1010 int BleChangeAdvParams(int advId, const BleAdvParams advParam); 1011 1012 /** 1013 * @brief Change a scan with BleScanConfigs and filter. Please make sure scan is started. 1014 * If don't change ble scan filter, set BleScanNativeFilter to nullptr or filterSzie to zero. 1015 * Don't support only using manufactureId as filter conditions, need to use it with manufactureData. 1016 * The manufactureId need to be set a related number when you need a filtering confition of manufactureData. 1017 * 1018 * @param scannerId Indicates the scanner id. 1019 * @param configs Indicates the pointer to the scan filter. For details, see {@link BleScanConfigs}. 1020 * @param filter Indicates the pointer to the scan filter. For details, see {@link BleScanNativeFilter}. 1021 * @param filterSize Indicates the number of the scan filter. 1022 * @param filterAction Indicates change filter behavior. See {@link BleScanUpdateFilterAction}. 1023 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the scan is started; 1024 * returns an error code defined in {@link BtStatus} otherwise. 1025 * @since 16 1026 */ 1027 int BleChangeScanParams(int32_t scannerId, const BleScanConfigs *config, const BleScanNativeFilter *filter, 1028 uint32_t filterSize, uint32_t filterAction); 1029 1030 /** 1031 * @brief Allocate adv handle 1032 * @return advertiser handle. 1033 * @since 12 1034 */ 1035 int AllocateAdvHandle(void); 1036 #ifdef __cplusplus 1037 } 1038 #endif 1039 #endif 1040 /** @} */