1 /* 2 * Copyright (C) 2021 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 #ifndef GAP_LE_H 17 #define GAP_LE_H 18 19 #include <stdbool.h> 20 #include <stddef.h> 21 #include <stdlib.h> 22 23 #include "btstack.h" 24 #include "gap_le_if.h" 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 /** 31 * @brief Set BLE Roles 32 * @param[in] role BLE Roles 33 * @return @c BT_SUCCESS : The function is executed successfully. 34 * @c otherwise : The function is not executed successfully. 35 */ 36 int GAP_LeSetRole(uint8_t role); 37 38 /** 39 * @brief Get local bluetooth address from HCI. 40 * @param[out] addr Bluetooth address of bluetooth chip. 41 * @return @c BT_SUCCESS : The function is executed successfully. 42 * @c otherwise : The function is not executed successfully. 43 */ 44 int GAP_GetLocalAddr(BtAddr *addr); 45 46 /** 47 * @brief Set Static Identity Address if controller does not have a Public Device Address 48 * @param[in/out] addr Static Identity Address 49 * @return @c BT_SUCCESS : The function is executed successfully. 50 * @c otherwise : The function is not executed successfully. 51 */ 52 int GAP_LeSetStaticIdentityAddr(uint8_t addr[BT_ADDRESS_SIZE]); 53 54 /** 55 * @brief Generate a local resolvable private address 56 * @param[in] callback Generate RPA result function 57 * @param[in] context Generate RPA result function context 58 * @return @c BT_SUCCESS : The function is executed successfully. 59 * @c otherwise : The function is not executed successfully. 60 */ 61 int GAP_LeGenResPriAddrAsync(GenResPriAddrResult callback, void *context); 62 63 /** 64 * @brief Read the maximum length of entended advertising data supported by the Controller 65 * @param[out] len length of entended advertising data or scan response data 66 * @return @c BT_SUCCESS : The function is executed successfully. 67 * @c otherwise : The function is not executed successfully. 68 */ 69 int GAP_LeExAdvGetMaxDataLen(uint16_t *len); 70 71 /** 72 * @brief Read the maximum number of advertising sets supported by the advertising Controller at the same time. 73 * @param[out] num maximum number of advertising sets 74 * @return @c BT_SUCCESS : The function is executed successfully. 75 * @c otherwise : The function is not executed successfully. 76 */ 77 int GAP_LeExAdvGetMaxHandleNum(uint8_t *num); 78 79 /** 80 * @brief Register Extended advertising callback function 81 * @param[in] callback Extended advertising callback structure 82 * @param[in] context Extended advertising result callback context parameter 83 * @return @c BT_SUCCESS : The function is executed successfully. 84 * @c otherwise : The function is not executed successfully. 85 */ 86 int GAP_RegisterExAdvCallback(const GapExAdvCallback *callback, void *context); 87 88 /** 89 * @brief Degegister Extended advertising callback function 90 * @return @c BT_SUCCESS : The function is executed successfully. 91 * @c otherwise : The function is not executed successfully. 92 */ 93 int GAP_DeregisterExAdvCallback(void); 94 95 /** 96 * @brief Set the random device address used by advertising. 97 * @param[in] advHandle used to identify an advertising set (0x00-0xEF) 98 * @param[in] addr random device address 99 * @return @c BT_SUCCESS : The function is executed successfully. 100 * @c otherwise : The function is not executed successfully. 101 */ 102 int GAP_LeExAdvSetRandAddr(uint8_t advHandle, const uint8_t addr[BT_ADDRESS_SIZE]); 103 104 /** 105 * @brief Set the advertising parameter used by advertising. 106 * @param[in] advHandle used to identify an advertising set (0x00-0xEF) 107 * @param[in] properties entended Advertising property 108 * @param[in] txPower advertising TX power 109 * @param[in] advExParam advertising parameter 110 * @return @c BT_SUCCESS : The function is executed successfully. 111 * @c otherwise : The function is not executed successfully. 112 */ 113 int GAP_LeExAdvSetParam(uint8_t advHandle, uint8_t properties, int8_t txPower, GapLeExAdvParam advExParam); 114 115 /** 116 * @brief Set the advertising data used by advertising. 117 * @param[in] advHandle used to identify an advertising set (0x00-0xEF) 118 * @param[in] operation entended Advertising operation 119 * @param[in] fragmentPreference fragment preference 120 * @param[in] advDataLength advertising data length 121 * @param[in] advData advertising data 122 * @return @c BT_SUCCESS : The function is executed successfully. 123 * @c otherwise : The function is not executed successfully. 124 */ 125 int GAP_LeExAdvSetData( 126 uint8_t advHandle, uint8_t operation, uint8_t fragmentPreference, uint8_t advDataLength, const uint8_t *advData); 127 128 /** 129 * @brief Set the scan response data used by advertising. 130 * @param[in] advHandle used to identify an advertising set (0x00-0xEF) 131 * @param[in] operation entended Advertising operation 132 * @param[in] fragmentPreference fragment preference 133 * @param[in] scanResponseDataLen scan response data length 134 * @param[in] scanResponseData scan response data 135 * @return @c BT_SUCCESS : The function is executed successfully. 136 * @c otherwise : The function is not executed successfully. 137 */ 138 int GAP_LeExAdvSetScanRspData(uint8_t advHandle, uint8_t operation, uint8_t fragmentPreference, 139 uint8_t scanResponseDataLen, const uint8_t *scanResponseData); 140 141 /** 142 * @brief Set the advertising enable used by advertising. 143 * @param[in] enable advertising enable (0x00 is disable, 0x01 is enable) 144 * @param[in] numberOfSet number of parameter (When disabled, 0 is to disable all) 145 * @param[in] advSet advertising enable parameter 146 * @return @c BT_SUCCESS : The function is executed successfully. 147 * @c otherwise : The function is not executed successfully. 148 */ 149 int GAP_LeExAdvSetEnable(uint8_t enable, uint8_t numberOfSet, const GapExAdvSet *advSet); 150 151 /** 152 * @brief Remove all advertising set of advertising. 153 * @return @c BT_SUCCESS : The function is executed successfully. 154 * @c otherwise : The function is not executed successfully. 155 */ 156 int GAP_LeExAdvClearHandle(void); 157 158 /** 159 * @brief Register legacy advertising result callback 160 * @param[in] callback legacy advertising callback 161 * @param[in] context legacy advertising callback context parameter 162 * @return @c BT_SUCCESS : The function is executed successfully. 163 * @c otherwise : The function is not executed successfully. 164 */ 165 int GAP_RegisterAdvCallback(const GapAdvCallback *callback, void *context); 166 167 /** 168 * @brief Deregister legacy advertising result callback 169 * @return @c BT_SUCCESS : The function is executed successfully. 170 * @c otherwise : The function is not executed successfully. 171 */ 172 int GAP_DeregisterAdvCallback(void); 173 174 /** 175 * @brief Set legacy advertising parameter 176 * @param[in] advType legacy advertising type 177 * @param[in] advParam legacy advertising parameter 178 * @return @c BT_SUCCESS : The function is executed successfully. 179 * @c otherwise : The function is not executed successfully. 180 */ 181 int GAP_LeAdvSetParam(uint8_t advType, GapLeAdvParam advParam); 182 183 /** 184 * @brief Read legacy advertising TX power 185 * @return @c BT_SUCCESS : The function is executed successfully. 186 * @c otherwise : The function is not executed successfully. 187 */ 188 int GAP_LeAdvReadTxPower(void); 189 190 /** 191 * @brief Set legacy advertising data 192 * @param[in] advDataLength legacy advertising data length 193 * @param[in] advData legacy advertising data 194 * @return @c BT_SUCCESS : The function is executed successfully. 195 * @c otherwise : The function is not executed successfully. 196 */ 197 int GAP_LeAdvSetData(uint8_t advDataLength, const uint8_t *advData); 198 199 /** 200 * @brief Set legacy advertising scan response data 201 * @param[in] advDataLength legacy advertising scan response data length 202 * @param[in] advData legacy advertising scan response data 203 * @return @c BT_SUCCESS : The function is executed successfully. 204 * @c otherwise : The function is not executed successfully. 205 */ 206 int GAP_LeAdvSetScanRspData(uint8_t advDataLength, const uint8_t *advData); 207 208 /** 209 * @brief Set legacy advertising enable 210 * @param[in] enable advertising enable (0x00 is disable, 0x01 is enable) 211 * @return @c BT_SUCCESS : The function is executed successfully. 212 * @c otherwise : The function is not executed successfully. 213 */ 214 int GAP_LeAdvSetEnable(uint8_t enable); 215 216 /** 217 * @brief Register scan result callback 218 * @param[in] callback scan result callback 219 * @param[in] context scan result callback context parameter 220 * @return @c BT_SUCCESS : The function is executed successfully. 221 * @c otherwise : The function is not executed successfully. 222 */ 223 int GAP_RegisterScanCallback(const GapScanCallback *callback, void *context); 224 225 /** 226 * @brief Deregister scan result callback 227 * @return @c BT_SUCCESS : The function is executed successfully. 228 * @c otherwise : The function is not executed successfully. 229 */ 230 int GAP_DeregisterScanCallback(void); 231 232 /** 233 * @brief Set scan parameter 234 * @param[in] param scan parameter 235 * @param[in] scanFilterPolity scan filter policy 236 * @return @c BT_SUCCESS : The function is executed successfully. 237 * @c otherwise : The function is not executed successfully. 238 */ 239 int GAP_LeScanSetParam(GapLeScanParam param, uint8_t scanFilterPolity); 240 241 /** 242 * @brief Set scan enable 243 * @param[in] scanEnable scan enable (0x00 is disable, 0x01 is enable) 244 * @param[in] filterDuplicates filter duplicates (0x00 is disable, 0x01 is enable) 245 * @return @c BT_SUCCESS : The function is executed successfully. 246 * @c otherwise : The function is not executed successfully. 247 */ 248 int GAP_LeScanSetEnable(uint8_t scanEnable, uint8_t filterDuplicates); 249 250 /** 251 * @brief Register extended scan result callback 252 * @param[in] callback extended scan result callback 253 * @param[in] context extended scan result callback context parameter 254 * @return @c BT_SUCCESS : The function is executed successfully. 255 * @c otherwise : The function is not executed successfully. 256 */ 257 int GAP_RegisterExScanCallback(const GapExScanCallback *callback, void *context); 258 259 /** 260 * @brief Deregister extended scan result callback 261 * @return @c BT_SUCCESS : The function is executed successfully. 262 * @c otherwise : The function is not executed successfully. 263 */ 264 int GAP_DeregisterExScanCallback(void); 265 266 /** 267 * @brief Set extended scan parameter 268 * @param[in] scanFilterPolity scan filter policy 269 * @param[in] scanPhys scan PHYs 270 * @param[in] param scan parameter 271 * @return @c BT_SUCCESS : The function is executed successfully. 272 * @c otherwise : The function is not executed successfully. 273 */ 274 int GAP_LeExScanSetParam(uint8_t scanFilterPolity, uint8_t scanPhys, const GapLeScanParam param[]); 275 276 /** 277 * @brief Set extended scan parameter 278 * @param[in] scanEnable scan enable (0x00 is disable, 0x01 is enable) 279 * @param[in] filterDuplicates filter duplicates (0x00 is disable, 0x01 is enable) 280 * @param[in] duration (n * 10ms, 0 is scan continuously) 281 * @param[in] period (n * 1.28s, 0 is periodic scanning disabled) 282 * @return @c BT_SUCCESS : The function is executed successfully. 283 * @c otherwise : The function is not executed successfully. 284 */ 285 int GAP_LeExScanSetEnable(uint8_t scanEnable, uint8_t filterDuplicates, uint16_t duration, uint16_t period); 286 287 /** 288 * @brief Register link layer control callback 289 * @param[in] callback link layer control callback 290 * @param[in] context link layer control callback context parameter 291 * @return @c BT_SUCCESS : The function is executed successfully. 292 * @c otherwise : The function is not executed successfully. 293 */ 294 int GAP_RegisterLeConnCallback(const GapLeConnCallback *callback, void *context); 295 296 /** 297 * @brief Deregister link layer control callback 298 * @return @c BT_SUCCESS : The function is executed successfully. 299 * @c otherwise : The function is not executed successfully. 300 */ 301 int GAP_DeregisterLeConnCallback(void); 302 303 /** 304 * @brief Send Connection parameter update request 305 * @param[in] addr target device address 306 * @param[in] connParam connection parameter 307 * @return @c BT_SUCCESS : The function is executed successfully. 308 * @c otherwise : The function is not executed successfully. 309 */ 310 int GAP_LeConnParamUpdate(const BtAddr *addr, const GapLeConnectionParameter *connParam); 311 312 /** 313 * @brief Respond Connection parameter update request 314 * @param[in] addr target device address 315 * @param[in] accept accept or reject 316 * @param[in] connParam connection parameter 317 * @return @c BT_SUCCESS : The function is executed successfully. 318 * @c otherwise : The function is not executed successfully. 319 */ 320 int GAP_LeConnectionParameterRsp(const BtAddr *addr, uint8_t accept, const GapLeConnectionParameter *connParam); 321 322 /** 323 * @brief specify a channel classification for data channels 324 * @param[in] channelMap contains 37 bits (0 is bad, 1 is unknown) 325 * @return @c BT_SUCCESS : The function is executed successfully. 326 * @c otherwise : The function is not executed successfully. 327 */ 328 int GAP_LeSetHostChannelClassification(uint64_t channelMap); 329 330 /** 331 * @brief Register BLE security callback 332 * @param[in] callback BLE security callback 333 * @param[in] context BLE security callback context parameter 334 * @return @c BT_SUCCESS : The function is executed successfully. 335 * @c otherwise : The function is not executed successfully. 336 */ 337 int GAP_RegisterLeSecurityCallback(const GapLeSecurityCallback *callback, void *context); 338 339 /** 340 * @brief Deregister BLE security callback 341 * @return @c BT_SUCCESS : The function is executed successfully. 342 * @c otherwise : The function is not executed successfully. 343 */ 344 int GAP_DeregisterLeSecurityCallback(void); 345 346 /** 347 * @brief Respond remote encryption key of target device 348 * @param[in] addr target device address 349 * @param[in] accept accept or reject 350 * @param[in] encKey remote encryption key 351 * @param[in] keyType remote encryption key type 352 * @return @c BT_SUCCESS : The function is executed successfully. 353 * @c otherwise : The function is not executed successfully. 354 */ 355 int GAP_LeRemoteEncryptionKeyRsp(const BtAddr *addr, uint8_t accept, LeEncKey encKey, uint8_t keyType); 356 357 /** 358 * @brief Respond local encryption key of target device 359 * @param[in] addr target device address 360 * @param[in] accept accept or reject 361 * @param[in] encKey local encryption key 362 * @param[in] keyType local encryption key type 363 * @return @c BT_SUCCESS : The function is executed successfully. 364 * @c otherwise : The function is not executed successfully. 365 */ 366 int GAP_LeLocalEncryptionKeyRsp(const BtAddr *addr, uint8_t accept, LeEncKey encKey, uint8_t keyType); 367 368 /** 369 * @brief Respond signing key of target device 370 * @param[in] addr target device address 371 * @param[in] accept accept or reject 372 * @param[in] info signing key info 373 * @return @c BT_SUCCESS : The function is executed successfully. 374 * @c otherwise : The function is not executed successfully. 375 */ 376 int GAP_RequestSigningAlgorithmInfoRsp(const BtAddr *addr, uint8_t accept, GapSigningAlgorithmInfo info); 377 378 /** 379 * @brief Set BLE bondable mode 380 * @param[in] mode boneable mode 381 * @return @c BT_SUCCESS : The function is executed successfully. 382 * @c otherwise : The function is not executed successfully. 383 */ 384 int GAP_LeSetBondMode(uint8_t mode); 385 386 /** 387 * @brief Set BLE security mode 388 * @param[in] mode1Level level of LE security mode 1 389 * @param[in] mode2Level level of LE security mode 2 390 * @return @c BT_SUCCESS : The function is executed successfully. 391 * @c otherwise : The function is not executed successfully. 392 */ 393 int GAP_LeSetSecurityMode(GAP_LeSecMode1Level mode1Level, GAP_LeSecMode2Level mode2Level); 394 395 /** 396 * @brief Get security status of le connection 397 * @param[in] addr target device address 398 * @param[out] status security status of le connection 399 * @param[out] encKeySize encryption Key Size 400 * @return @c BT_SUCCESS : The function is executed successfully. 401 * @c otherwise : The function is not executed successfully. 402 */ 403 int GAP_LeGetSecurityStatus(const BtAddr *addr, GAP_LeSecurityStatus *status, uint8_t *encKeySize); 404 405 /** 406 * @brief Request security of le connection 407 * @param[in] addr target device address 408 * @param[in] status security status of le connection 409 * @param[in] callback result callback 410 * @param[in] context result callback context parameter 411 * @return @c BT_SUCCESS : The function is executed successfully. 412 * @c otherwise : The function is not executed successfully. 413 */ 414 int GAP_LeRequestSecurity( 415 const BtAddr *addr, GAP_LeSecurityStatus status, GapLeRequestSecurityResult callback, void *context); 416 417 /** 418 * @brief BLE bonding procedure 419 * @param[in] addr target device address 420 * @return @c BT_SUCCESS : The function is executed successfully. 421 * @c otherwise : The function is not executed successfully. 422 */ 423 int GAP_LePair(const BtAddr *addr); 424 425 /** 426 * @brief Cancel BLE bonding procedure 427 * @param[in] addr target device address 428 * @return @c BT_SUCCESS : The function is executed successfully. 429 * @c otherwise : The function is not executed successfully. 430 */ 431 int GAP_LeCancelPair(const BtAddr *addr); 432 433 /** 434 * @brief Set minimum of Long Term Key size 435 * @param[in] minSize minimum of Long Term Key size 436 * @return @c BT_SUCCESS : The function is executed successfully. 437 * @c otherwise : The function is not executed successfully. 438 */ 439 int GAP_LeSetMinEncKeySize(uint8_t minSize); 440 441 /** 442 * @brief Register BLE pair callback 443 * @param[in] callback BLE pair callback 444 * @param[in] context BLE pair callback context parameter 445 * @return @c BT_SUCCESS : The function is executed successfully. 446 * @c otherwise : The function is not executed successfully. 447 */ 448 int GAP_RegisterLePairCallback(const GapLePairCallback *callback, void *context); 449 450 /** 451 * @brief Deregister BLE pair callback 452 * @return @c BT_SUCCESS : The function is executed successfully. 453 * @c otherwise : The function is not executed successfully. 454 */ 455 int GAP_DeregisterLePairCallback(void); 456 457 /** 458 * @brief Respond BLE pair feature request 459 * @param[in] addr target device address 460 * @param[in] localFeature local BLE pair feature 461 * @return @c BT_SUCCESS : The function is executed successfully. 462 * @c otherwise : The function is not executed successfully. 463 */ 464 int GAP_LePairFeatureRsp(const BtAddr *addr, GapLePairFeature localFeature); 465 466 /** 467 * @brief Respond BLE pair passkey request 468 * @param[in] addr target device address 469 * @param[in] accept accept orr reject 470 * @param[in] number passkey number (000000-999999) 471 * @return @c BT_SUCCESS : The function is executed successfully. 472 * @c otherwise : The function is not executed successfully. 473 */ 474 int GAP_LePairPassKeyRsp(const BtAddr *addr, uint8_t accept, uint32_t number); 475 476 /** 477 * @brief Respond BLE legacy OOB data request 478 * @param[in] addr target device address 479 * @param[in] accept accept orr reject 480 * @param[in] oobData legacy OOB data 481 * @return @c BT_SUCCESS : The function is executed successfully. 482 * @c otherwise : The function is not executed successfully. 483 */ 484 int GAP_LePairOobRsp(const BtAddr *addr, uint8_t accept, uint8_t oobData[GAP_OOB_DATA_SIZE]); 485 486 /** 487 * @brief Respond BLE Secure connection OOB data request 488 * @param[in] addr target device address 489 * @param[in] accept accept orr reject 490 * @param[in] oobDataC Secure connection OOB confirm data 491 * @param[in] oobDataR Secure connection OOB random data 492 * @return @c BT_SUCCESS : The function is executed successfully. 493 * @c otherwise : The function is not executed successfully. 494 */ 495 int GAP_LePairScOobRsp(const BtAddr *addr, uint8_t accept, const uint8_t oobDataC[GAP_OOB_DATA_CONFIRM_SIZE], 496 const uint8_t oobDataR[GAP_OOB_DATA_RANDOM_SIZE]); 497 498 /** 499 * @brief Respond user confirmation request 500 * @param[in] addr target device address 501 * @param[in] accept accept orr reject 502 * @return @c BT_SUCCESS : The function is executed successfully. 503 * @c otherwise : The function is not executed successfully. 504 */ 505 int GAP_LePairScUserConfirmRsp(const BtAddr *addr, uint8_t accept); 506 507 /** 508 * @brief generation a data signature 509 * @param[in] addr target device address 510 * @param[in] dataInfo data PDU 511 * @param[in] callback result callback function 512 * @param[in] context result callback function context 513 * @return @c BT_SUCCESS : The function is executed successfully. 514 * @c otherwise : The function is not executed successfully. 515 */ 516 int GAP_LeDataSignatureGeneration( 517 const BtAddr *addr, GapSignatureData dataInfo, GAPSignatureGenerationResult callback, void *context); 518 519 /** 520 * @brief Confirmation a data signature 521 * @param[in] addr target device address 522 * @param[in] dataInfo data PDU 523 * @param[in] signature signature data 524 * @param[in] callback result callback function 525 * @param[in] context result callback function context 526 * @return @c BT_SUCCESS : The function is executed successfully. 527 * @c otherwise : The function is not executed successfully. 528 */ 529 int GAP_LeDataSignatureConfirmation(const BtAddr *addr, GapSignatureData dataInfo, 530 const uint8_t signature[GAP_SIGNATURE_SIZE], GAPSignatureConfirmationResult callback, void *context); 531 532 #ifdef __cplusplus 533 } 534 #endif 535 536 #endif /* GAP_LE_H */