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 Generic Access Profile 21 * 22 */ 23 24 /** 25 * @file gap.h 26 * 27 * @brief bluetooth gap interface 28 * 29 */ 30 31 #ifndef GAP_IF_H 32 #define GAP_IF_H 33 34 #include "gap_comm.h" 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 /** 41 * @brief Result callback of set scan mode. 42 * @param[in] status Result of mode setting. 43 * @param[in] context The context of the caller. 44 * @return @c void 45 */ 46 typedef void (*GapSetScanModeResultCallback)(uint8_t status, void *context); 47 48 /** 49 * @brief Discoverability modes configuration parameter structure 50 */ 51 typedef struct { 52 uint8_t mode; /// Discoverable Mode 53 uint8_t type; /// Inquiry Scan Type 54 uint16_t scanInterval; /// The amount of time between consecutive inquiry scans. 55 uint16_t scanWindow; /// The amount of time for the duration of the inquiry scan. 56 } GapDiscoverModeInfo; 57 58 /** 59 * @brief Connectionability modes configuration parameter structure 60 */ 61 typedef struct { 62 uint8_t mode; /// Connectable Mode 63 uint8_t type; /// Page Scan Type 64 uint16_t scanInterval; /// The amount of time between consecutive page scans. 65 uint16_t scanWindow; /// The amount of time for the duration of the page scan. 66 } GapConnectableModeInfo; 67 68 /** 69 * @brief Service connection direction. 70 */ 71 typedef enum { 72 OUTGOING, 73 INCOMING, 74 } GAP_ServiceConnectDirection; 75 76 #define MAP_MAX_COUNT (13) 77 78 /** 79 * @brief Service identity. 80 */ 81 typedef enum { 82 UNKNOWN_SERVICE, 83 GAP, 84 SDP, 85 GAVDP_INT, 86 GAVDP_ACP, 87 A2DP_SINK, 88 A2DP_SRC, 89 AVRCP_CT, 90 AVRCP_TG, 91 AVRCP_CT_BROWSING, 92 AVRCP_TG_BROWSING, 93 HFP_HF, 94 HFP_AG, 95 PBAP_CLIENT, 96 PBAP_SERVER, 97 MAP_CLIENT_ID_START, 98 MAP_CLIENT_ID_END = MAP_CLIENT_ID_START + MAP_MAX_COUNT, 99 MAP_SERVER_ID_START, 100 MAP_SERVER_ID_END = MAP_SERVER_ID_START + MAP_MAX_COUNT, 101 GATT_CLIENT, 102 GATT_SERVER, 103 RFCOMM, 104 SPP_ID_START, 105 HID_HOST, 106 PAN_BNEP, 107 OPP_CLIENT, 108 OPP_SERVER, 109 } GAP_Service; 110 111 /** 112 * @brief Multiplexing protocol identity. 113 */ 114 typedef enum { 115 SEC_PROTOCOL_L2CAP, 116 SEC_PROTOCOL_RFCOMM, 117 } GAP_SecMultiplexingProtocol; 118 119 /** 120 * @brief Protocol channel. 121 */ 122 typedef union { 123 uint16_t l2capPsm; 124 uint8_t rfcommChannel; 125 } GapSecChannel; 126 127 /// Security attributes 128 #define GAP_SEC_IN_AUTHORIZATION (1 << 0) 129 #define GAP_SEC_IN_AUTHENTICATION (1 << 1) 130 #define GAP_SEC_IN_ENCRYPTION (1 << 2) 131 #define GAP_SEC_MITM (1 << 3) 132 #define GAP_SEC_OUT_AUTHENTICATION (1 << 4) 133 #define GAP_SEC_OUT_ENCRYPTION (1 << 5) 134 135 /** 136 * @brief Security request information structure. 137 */ 138 typedef struct { 139 GAP_ServiceConnectDirection direction; 140 GAP_Service serviceId; 141 GAP_SecMultiplexingProtocol protocolId; 142 GapSecChannel channelId; 143 } GapServiceSecurityInfo; 144 145 /** 146 * @brief Service security request result callback 147 * @param[in] result security request result 148 * @param[in] serviceInfo security request information 149 * @param[in] context security request context 150 * @return @c void 151 * 152 */ 153 typedef void (*GapSecurityResultCallback)(uint16_t result, GapServiceSecurityInfo serviceInfo, void *context); 154 155 /** 156 * @brief parameter of interface GAP_RequestSecurity. 157 */ 158 typedef struct { 159 GapServiceSecurityInfo info; /// Security request information 160 GapSecurityResultCallback callback; /// Service request security result callback function 161 void *context; /// Service request security result callback function context parameter 162 } GapRequestSecurityParam; 163 164 /** 165 * @brief Security modes of BR/EDR physical transport. 166 */ 167 typedef enum { 168 SEC_MODE_2, 169 SEC_MODE_4, 170 } GAP_SecurityMode; 171 172 /** 173 * @brief Service security verify callback structure of BR/EDR physical transport. 174 */ 175 typedef struct { 176 /// Service authorization verify callback 177 void (*authorizeInd)(const BtAddr *addr, GAP_Service service, void *context); 178 } GapSecurityCallback; 179 180 /** 181 * @brief authentication callback structure. 182 */ 183 typedef struct { 184 void (*userConfirmReq)(const BtAddr *addr, uint32_t number, int localMitmRequired, 185 int remoteMitmRequired, void *context); 186 void (*userPasskeyReq)(const BtAddr *addr, void *context); 187 void (*userPasskeyNotification)(const BtAddr *addr, uint32_t number, void *context); 188 void (*remoteOobReq)(const BtAddr *addr, void *context); 189 void (*pinCodeReq)(const BtAddr *addr, void *context); 190 void (*linkKeyReq)(const BtAddr *addr, void *context); 191 void (*linkKeyNotification)( 192 const BtAddr *addr, const uint8_t linkKey[GAP_LINKKEY_SIZE], uint8_t keyType, void *context); 193 void (*simplePairComplete)(const BtAddr *addr, uint8_t status, void *context); 194 void (*IOCapabilityReq)(const BtAddr *addr, void *context); 195 void (*IOCapabilityRsp)(const BtAddr *addr, uint8_t ioCapability, void *context); 196 void (*authenticationComplete)(const BtAddr *addr, uint8_t status, void *context); 197 void (*encryptionChangeCallback)(const BtAddr *addr, uint8_t status, void *context); 198 } GapAuthenticationCallback; 199 200 /** 201 * @brief Encryption change result callback 202 * @param[in] addr encryption change target device address 203 * @param[in] status encryption change result status 204 * @param[in] context encryption change context 205 * @return @c void 206 */ 207 typedef void (*GapEncryptionChangeCallback)(const BtAddr *addr, uint8_t status, void *context); 208 209 /// Inquiry mode 210 #define GAP_INQUIRY_MODE_GENERAL 0x00 211 #define GAP_INQUIRY_MODE_LIMITED 0x01 212 213 /** 214 * @brief Device discover callback structure. 215 */ 216 typedef struct { 217 void (*inquiryResult)(const BtAddr *addr, uint32_t classOfDevice, void *context); 218 void (*inquiryResultRssi)(const BtAddr *addr, uint32_t classOfDevice, int8_t rssi, void *context); 219 void (*extendedInquiryResult)( 220 const BtAddr *addr, uint32_t classOfDevice, int8_t rssi, const uint8_t eir[GAP_EIR_SIZE_MAX], void *context); 221 void (*remoteName)(uint8_t status, const BtAddr *addr, const uint8_t name[GAP_NAME_SIZE_MAX], void *context); 222 void (*inquiryComplete)(uint8_t status, void *context); 223 } GapDiscoveryCallback; 224 225 /** 226 * @brief Set local bluetooth device name. (Used for BR/EDR) 227 * @param[in] name Bluetooth device name. 228 * @param[in] length Length of the device name. (248 or less) 229 * @return @c BT_SUCCESS : The function is executed successfully. 230 * @c otherwise : The function is not executed successfully. 231 */ 232 BTSTACK_API int GAPIF_SetLocalName(const char *name, int length); 233 234 /** 235 * @brief Set local bluetooth device class. 236 * @param[in] cod Bluetooth device class. 237 * @return @c BT_SUCCESS : The function is executed successfully. 238 * @c otherwise : The function is not executed successfully. 239 */ 240 BTSTACK_API int GAPIF_SetClassOfDevice(uint32_t cod); 241 242 /** 243 * @brief Set local bluetooth device class. 244 * @param[in] cod Bluetooth device class. 245 * @return @c BT_SUCCESS : The function is executed successfully. 246 * @c otherwise : The function is not executed successfully. 247 */ 248 BTSTACK_API int GAPIF_SetExtendedInquiryResponse(const uint8_t eir[GAP_EIR_SIZE_MAX]); 249 250 /** 251 * @brief Set scan mode of bluetooth BR/EDR physical transport. 252 * @param[in] discoverInfo Discoverability modes configuration parameter. 253 * @param[in] connectableInfo Connectionability modes configuration parameter. 254 * @param[in] callback Callback function for the result. 255 * @param[in] context The context of the callback function. 256 * @return @c BT_SUCCESS : The function is executed successfully. 257 * @c otherwise : The function is not executed successfully. 258 * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part C 259 * 4.1 DISCOVERABILITY MODES 260 * 4.2 CONNECTABILITY MODES 261 */ 262 BTSTACK_API int GAPIF_SetScanMode(const GapDiscoverModeInfo *discoverInfo, 263 const GapConnectableModeInfo *connectableInfo, GapSetScanModeResultCallback callback, void *context); 264 265 /** 266 * @brief Set boneable mode of bluetooth BR/EDR physical transport. 267 * @param[in] isBondable boneable mode 268 * @return @c BT_SUCCESS : The function is executed successfully. 269 * @c otherwise : The function is not executed successfully. 270 * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part C 271 * 4.3 BONDABLE MODES 272 */ 273 BTSTACK_API int GAPIF_SetBondableMode(uint8_t isBondable); 274 275 /** 276 * @brief Service register security requirements to GAP 277 * @param[in] addr outgoing attributes to remote device 278 * @param[in] serviceInfo security requirements information 279 * @param[in] securityMode Security attributes 280 * @return @c BT_SUCCESS : The function is executed successfully. 281 * @c otherwise : The function is not executed successfully. 282 */ 283 BTSTACK_API int GAPIF_RegisterServiceSecurity( 284 const BtAddr *addr, const GapServiceSecurityInfo *serviceInfo, uint16_t securityMode); 285 BTSTACK_API int GAPIF_RegisterServiceSecurityAsync( 286 const BtAddr *addr, const GapServiceSecurityInfo *serviceInfo, uint16_t securityMode); 287 288 /** 289 * @brief Service deregister security requirements to GAP 290 * @param[in] addr outgoing attributes to remote device 291 * @param[in] serviceInfo security requirements information 292 * @return @c BT_SUCCESS : The function is executed successfully. 293 * @c otherwise : The function is not executed successfully. 294 */ 295 BTSTACK_API int GAPIF_DeregisterServiceSecurity(const BtAddr *addr, const GapServiceSecurityInfo *serviceInfo); 296 BTSTACK_API int GAPIF_DeregisterServiceSecurityAsync(const BtAddr *addr, const GapServiceSecurityInfo *serviceInfo); 297 298 /** 299 * @brief Service request security requirements to GAP 300 * @param[in] addr target device address 301 * @param[in] param structure of security requirements information and result callback function 302 * @return @c BT_SUCCESS : The function is executed successfully. 303 * @c otherwise : The function is not executed successfully. 304 */ 305 BTSTACK_API int GAPIF_RequestSecurity(const BtAddr *addr, const GapRequestSecurityParam *param); 306 BTSTACK_API int GAPIF_RequestSecurityAsync(const BtAddr *addr, const GapRequestSecurityParam *param); 307 308 /** 309 * @brief Register service security verify callback 310 * @param[in] callback security verify callback 311 * @param[in] context security verify callback context parameter 312 * @return @c BT_SUCCESS : The function is executed successfully. 313 * @c otherwise : The function is not executed successfully. 314 */ 315 BTSTACK_API int GAPIF_RegisterSecurityCallback(const GapSecurityCallback *callback, void *context); 316 317 /** 318 * @brief Deregister service security verify callback 319 * @return @c BT_SUCCESS : The function is executed successfully. 320 * @c otherwise : The function is not executed successfully. 321 */ 322 BTSTACK_API int GAPIF_DeregisterSecurityCallback(void); 323 324 /** 325 * @brief Set security modes of BR/EDR physical transport 326 * @param[in] mode security modes 327 * @return @c BT_SUCCESS : The function is executed successfully. 328 * @c otherwise : The function is not executed successfully. 329 */ 330 BTSTACK_API int GAPIF_SetSecurityMode(GAP_SecurityMode mode); 331 332 /** 333 * @brief Service authorization verify response 334 * @param[in] addr target device address 335 * @param[in] service service identity 336 * @param[in] accept accept or reject 337 * @return @c BT_SUCCESS : The function is executed successfully. 338 * @c otherwise : The function is not executed successfully. 339 */ 340 BTSTACK_API int GAPIF_AuthorizeRes(const BtAddr *addr, GAP_Service service, uint8_t accept); 341 342 /** 343 * @brief Register authentication callback 344 * @param[in] callback authentication callback structure 345 * @param[in] context authentication verify callback context parameter 346 * @return @c BT_SUCCESS : The function is executed successfully. 347 * @c otherwise : The function is not executed successfully. 348 */ 349 BTSTACK_API int GAPIF_RegisterAuthenticationCallback(const GapAuthenticationCallback *callback, void *context); 350 351 /** 352 * @brief Deregister authentication callback 353 * @return @c BT_SUCCESS : The function is executed successfully. 354 * @c otherwise : The function is not executed successfully. 355 */ 356 BTSTACK_API int GAPIF_DeregisterAuthenticationCallback(void); 357 358 /** 359 * @brief Get current pair originator 360 * @param[in] addr pairing device address 361 * @param[out] isLocal is local initiate 362 * @return @c BT_SUCCESS : The function is executed successfully. 363 * @c otherwise : The function is not executed successfully. 364 */ 365 BTSTACK_API int GAPIF_PairIsFromLocal(const BtAddr *addr, bool *isLocal); 366 367 /** 368 * @brief authenticate the remote device associated. 369 * @param[in] addr target device address 370 * @return @c BT_SUCCESS : The function is executed successfully. 371 * @c otherwise : The function is not executed successfully. 372 */ 373 BTSTACK_API int GAPIF_AuthenticationReq(const BtAddr *addr); 374 375 /** 376 * @brief cancel authenticate the remote device associated. 377 * @param[in] addr target device address 378 * @return @c BT_SUCCESS : The function is executed successfully. 379 * @c otherwise : The function is not executed successfully. 380 */ 381 BTSTACK_API int GAPIF_CancelAuthenticationReq(const BtAddr *addr); 382 383 /** 384 * @brief Respond IO capability request. Reply callback GapAuthenticationCallback::IOCapabilityReq 385 * @param[in] addr target device address 386 * @param[in] accept accept or reject 387 * @param[in] ioCapability local device IO capability 388 * @param[in] oobDataPresent OOB authentication data from remote device present 389 * @param[in] authReq Authentication Requirements: MITM protection 390 * @return @c BT_SUCCESS : The function is executed successfully. 391 * @c otherwise : The function is not executed successfully. 392 */ 393 BTSTACK_API int GAPIF_IOCapabilityRsp( 394 const BtAddr *addr, uint8_t accept, uint8_t ioCapability, uint8_t oobDataPresent, uint8_t authReq); 395 396 /** 397 * @brief Respond user confirmation request. Reply callback GapAuthenticationCallback::userConfirmReq 398 * @param[in] addr target device address 399 * @param[in] accept accept or reject 400 * @return @c BT_SUCCESS : The function is executed successfully. 401 * @c otherwise : The function is not executed successfully. 402 */ 403 BTSTACK_API int GAPIF_UserConfirmRsp(const BtAddr *addr, uint8_t accept); 404 405 /** 406 * @brief Respond user passkey request. Reply callback GapAuthenticationCallback::userPasskeyReq 407 * @param[in] addr target device address 408 * @param[in] accept accept or reject 409 * @param[in] number user input number (000000 - 999999) 410 * @return @c BT_SUCCESS : The function is executed successfully. 411 * @c otherwise : The function is not executed successfully. 412 */ 413 BTSTACK_API int GAPIF_UserPasskeyRsp(const BtAddr *addr, uint8_t accept, uint32_t number); 414 415 /** 416 * @brief Respond remote OOB data request. Reply callback GapAuthenticationCallback::remoteOobReq 417 * @param[in] addr target device address 418 * @param[in] accept accept or reject 419 * @param[in] data OOB data 420 * @return @c BT_SUCCESS : The function is executed successfully. 421 * @c otherwise : The function is not executed successfully. 422 */ 423 BTSTACK_API int GAPIF_RemoteOobRsp(const BtAddr *addr, uint8_t accept, const GapOOBData *data); 424 425 /** 426 * @brief Respond PIN code request. Reply callback GapAuthenticationCallback::pinCodeReq 427 * @param[in] addr target device address 428 * @param[in] accept accept or reject 429 * @param[in] pinCode PIN code data 430 * @param[in] pinCodeLength PIN code data length 431 * @return @c BT_SUCCESS : The function is executed successfully. 432 * @c otherwise : The function is not executed successfully. 433 */ 434 BTSTACK_API int GAPIF_PinCodeRsp(const BtAddr *addr, uint8_t accept, const uint8_t *pinCode, uint8_t pinCodeLength); 435 436 /** 437 * @brief Respond link key request. Reply callback GapAuthenticationCallback::linkKeyReq 438 * @param[in] addr target device address 439 * @param[in] accept accept or reject 440 * @param[in] linkKey link key 441 * @param[in] keyType link key type 442 * @return @c BT_SUCCESS : The function is executed successfully. 443 * @c otherwise : The function is not executed successfully. 444 */ 445 BTSTACK_API int GAPIF_LinkKeyRsp( 446 const BtAddr *addr, uint8_t accept, const uint8_t linkKey[GAP_LINKKEY_SIZE], uint8_t keyType); 447 448 /** 449 * @brief Register device discover callback 450 * @param[in] callback device discover callback structure 451 * @param[in] context device discover callback context parameter 452 * @return @c BT_SUCCESS : The function is executed successfully. 453 * @c otherwise : The function is not executed successfully. 454 */ 455 BTSTACK_API int GAPIF_RegisterDiscoveryCallback(const GapDiscoveryCallback *callback, void *context); 456 457 /** 458 * @brief Deregister device discover callback 459 * @return @c BT_SUCCESS : The function is executed successfully. 460 * @c otherwise : The function is not executed successfully. 461 */ 462 BTSTACK_API int GAPIF_DeregisterDiscoveryCallback(void); 463 464 /** 465 * @brief discover other nearby BR/EDR Controllers 466 * @param[in] mode Inquiry mode 467 * @param[in] inquiryLength Maximum inquiry time.(n * 1.28s) 468 * @return @c BT_SUCCESS : The function is executed successfully. 469 * @c otherwise : The function is not executed successfully. 470 */ 471 BTSTACK_API int GAPIF_Inquiry(uint8_t mode, uint8_t inquiryLength); 472 473 /** 474 * @brief Cancel discover other nearby BR/EDR Controllers 475 * @return @c BT_SUCCESS : The function is executed successfully. 476 * @c otherwise : The function is not executed successfully. 477 */ 478 BTSTACK_API int GAPIF_InquiryCancel(void); 479 480 /** 481 * @brief Get remote device name 482 * @param[in] addr target device address 483 * @return @c BT_SUCCESS : The function is executed successfully. 484 * @c otherwise : The function is not executed successfully. 485 */ 486 BTSTACK_API int GAPIF_GetRemoteName(const BtAddr *addr); 487 488 /** 489 * @brief Cancel get remote device name 490 * @param[in] addr target device address 491 * @return @c BT_SUCCESS : The function is executed successfully. 492 * @c otherwise : The function is not executed successfully. 493 */ 494 BTSTACK_API int GAPIF_GetRemoteNameCancel(const BtAddr *addr); 495 496 /** 497 * @brief Get local bluetooth address from HCI. 498 * @param[out] addr Bluetooth address of bluetooth chip. 499 * @return @c BT_SUCCESS : The function is executed successfully. 500 * @c otherwise : The function is not executed successfully. 501 */ 502 BTSTACK_API int GAPIF_GetLocalAddr(BtAddr *addr); 503 504 #ifdef __cplusplus 505 } 506 #endif 507 508 #endif /* GAP_IF_H */ 509