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, void *context); 185 void (*userPasskeyReq)(const BtAddr *addr, void *context); 186 void (*userPasskeyNotification)(const BtAddr *addr, uint32_t number, void *context); 187 void (*remoteOobReq)(const BtAddr *addr, void *context); 188 void (*pinCodeReq)(const BtAddr *addr, void *context); 189 void (*linkKeyReq)(const BtAddr *addr, void *context); 190 void (*linkKeyNotification)( 191 const BtAddr *addr, const uint8_t linkKey[GAP_LINKKEY_SIZE], uint8_t keyType, void *context); 192 void (*simplePairComplete)(const BtAddr *addr, uint8_t status, void *context); 193 void (*IOCapabilityReq)(const BtAddr *addr, void *context); 194 void (*IOCapabilityRsp)(const BtAddr *addr, uint8_t ioCapability, void *context); 195 void (*authenticationComplete)(const BtAddr *addr, uint8_t status, void *context); 196 void (*encryptionChangeCallback)(const BtAddr *addr, uint8_t status, void *context); 197 } GapAuthenticationCallback; 198 199 /** 200 * @brief Encryption change result callback 201 * @param[in] addr encryption change target device address 202 * @param[in] status encryption change result status 203 * @param[in] context encryption change context 204 * @return @c void 205 */ 206 typedef void (*GapEncryptionChangeCallback)(const BtAddr *addr, uint8_t status, void *context); 207 208 /// Inquiry mode 209 #define GAP_INQUIRY_MODE_GENERAL 0x00 210 #define GAP_INQUIRY_MODE_LIMITED 0x01 211 212 /** 213 * @brief Device discover callback structure. 214 */ 215 typedef struct { 216 void (*inquiryResult)(const BtAddr *addr, uint32_t classOfDevice, void *context); 217 void (*inquiryResultRssi)(const BtAddr *addr, uint32_t classOfDevice, int8_t rssi, void *context); 218 void (*extendedInquiryResult)( 219 const BtAddr *addr, uint32_t classOfDevice, int8_t rssi, const uint8_t eir[GAP_EIR_SIZE_MAX], void *context); 220 void (*remoteName)(uint8_t status, const BtAddr *addr, const uint8_t name[GAP_NAME_SIZE_MAX], void *context); 221 void (*inquiryComplete)(uint8_t status, void *context); 222 } GapDiscoveryCallback; 223 224 /** 225 * @brief Set local bluetooth device name. (Used for BR/EDR) 226 * @param[in] name Bluetooth device name. 227 * @param[in] length Length of the device name. (248 or less) 228 * @return @c BT_NO_ERROR : The function is executed successfully. 229 * @c otherwise : The function is not executed successfully. 230 */ 231 BTSTACK_API int GAPIF_SetLocalName(const char *name, int length); 232 233 /** 234 * @brief Set local bluetooth device class. 235 * @param[in] cod Bluetooth device class. 236 * @return @c BT_NO_ERROR : The function is executed successfully. 237 * @c otherwise : The function is not executed successfully. 238 */ 239 BTSTACK_API int GAPIF_SetClassOfDevice(uint32_t cod); 240 241 /** 242 * @brief Set local bluetooth device class. 243 * @param[in] cod Bluetooth device class. 244 * @return @c BT_NO_ERROR : The function is executed successfully. 245 * @c otherwise : The function is not executed successfully. 246 */ 247 BTSTACK_API int GAPIF_SetExtendedInquiryResponse(const uint8_t eir[GAP_EIR_SIZE_MAX]); 248 249 /** 250 * @brief Set scan mode of bluetooth BR/EDR physical transport. 251 * @param[in] discoverInfo Discoverability modes configuration parameter. 252 * @param[in] connectableInfo Connectionability modes configuration parameter. 253 * @param[in] callback Callback function for the result. 254 * @param[in] context The context of the callback function. 255 * @return @c BT_NO_ERROR : The function is executed successfully. 256 * @c otherwise : The function is not executed successfully. 257 * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part C 258 * 4.1 DISCOVERABILITY MODES 259 * 4.2 CONNECTABILITY MODES 260 */ 261 BTSTACK_API int GAPIF_SetScanMode(const GapDiscoverModeInfo *discoverInfo, 262 const GapConnectableModeInfo *connectableInfo, GapSetScanModeResultCallback callback, void *context); 263 264 /** 265 * @brief Set boneable mode of bluetooth BR/EDR physical transport. 266 * @param[in] isBondable boneable mode 267 * @return @c BT_NO_ERROR : The function is executed successfully. 268 * @c otherwise : The function is not executed successfully. 269 * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part C 270 * 4.3 BONDABLE MODES 271 */ 272 BTSTACK_API int GAPIF_SetBondableMode(uint8_t isBondable); 273 274 /** 275 * @brief Service register security requirements to GAP 276 * @param[in] addr outgoing attributes to remote device 277 * @param[in] serviceInfo security requirements information 278 * @param[in] securityMode Security attributes 279 * @return @c BT_NO_ERROR : The function is executed successfully. 280 * @c otherwise : The function is not executed successfully. 281 */ 282 BTSTACK_API int GAPIF_RegisterServiceSecurity( 283 const BtAddr *addr, const GapServiceSecurityInfo *serviceInfo, uint16_t securityMode); 284 BTSTACK_API int GAPIF_RegisterServiceSecurityAsync( 285 const BtAddr *addr, const GapServiceSecurityInfo *serviceInfo, uint16_t securityMode); 286 287 /** 288 * @brief Service deregister security requirements to GAP 289 * @param[in] addr outgoing attributes to remote device 290 * @param[in] serviceInfo security requirements information 291 * @return @c BT_NO_ERROR : The function is executed successfully. 292 * @c otherwise : The function is not executed successfully. 293 */ 294 BTSTACK_API int GAPIF_DeregisterServiceSecurity(const BtAddr *addr, const GapServiceSecurityInfo *serviceInfo); 295 BTSTACK_API int GAPIF_DeregisterServiceSecurityAsync(const BtAddr *addr, const GapServiceSecurityInfo *serviceInfo); 296 297 /** 298 * @brief Service request security requirements to GAP 299 * @param[in] addr target device address 300 * @param[in] param structure of security requirements information and result callback function 301 * @return @c BT_NO_ERROR : The function is executed successfully. 302 * @c otherwise : The function is not executed successfully. 303 */ 304 BTSTACK_API int GAPIF_RequestSecurity(const BtAddr *addr, const GapRequestSecurityParam *param); 305 BTSTACK_API int GAPIF_RequestSecurityAsync(const BtAddr *addr, const GapRequestSecurityParam *param); 306 307 /** 308 * @brief Register service security verify callback 309 * @param[in] callback security verify callback 310 * @param[in] context security verify callback context parameter 311 * @return @c BT_NO_ERROR : The function is executed successfully. 312 * @c otherwise : The function is not executed successfully. 313 */ 314 BTSTACK_API int GAPIF_RegisterSecurityCallback(const GapSecurityCallback *callback, void *context); 315 316 /** 317 * @brief Deregister service security verify callback 318 * @return @c BT_NO_ERROR : The function is executed successfully. 319 * @c otherwise : The function is not executed successfully. 320 */ 321 BTSTACK_API int GAPIF_DeregisterSecurityCallback(void); 322 323 /** 324 * @brief Set security modes of BR/EDR physical transport 325 * @param[in] mode security modes 326 * @return @c BT_NO_ERROR : The function is executed successfully. 327 * @c otherwise : The function is not executed successfully. 328 */ 329 BTSTACK_API int GAPIF_SetSecurityMode(GAP_SecurityMode mode); 330 331 /** 332 * @brief Service authorization verify response 333 * @param[in] addr target device address 334 * @param[in] service service identity 335 * @param[in] accept accept or reject 336 * @return @c BT_NO_ERROR : The function is executed successfully. 337 * @c otherwise : The function is not executed successfully. 338 */ 339 BTSTACK_API int GAPIF_AuthorizeRes(const BtAddr *addr, GAP_Service service, uint8_t accept); 340 341 /** 342 * @brief Register authentication callback 343 * @param[in] callback authentication callback structure 344 * @param[in] context authentication verify callback context parameter 345 * @return @c BT_NO_ERROR : The function is executed successfully. 346 * @c otherwise : The function is not executed successfully. 347 */ 348 BTSTACK_API int GAPIF_RegisterAuthenticationCallback(const GapAuthenticationCallback *callback, void *context); 349 350 /** 351 * @brief Deregister authentication callback 352 * @return @c BT_NO_ERROR : The function is executed successfully. 353 * @c otherwise : The function is not executed successfully. 354 */ 355 BTSTACK_API int GAPIF_DeregisterAuthenticationCallback(void); 356 357 /** 358 * @brief Get current pair originator 359 * @param[in] addr pairing device address 360 * @param[out] isLocal is local initiate 361 * @return @c BT_NO_ERROR : The function is executed successfully. 362 * @c otherwise : The function is not executed successfully. 363 */ 364 BTSTACK_API int GAPIF_PairIsFromLocal(const BtAddr *addr, bool *isLocal); 365 366 /** 367 * @brief authenticate the remote device associated. 368 * @param[in] addr target device address 369 * @return @c BT_NO_ERROR : The function is executed successfully. 370 * @c otherwise : The function is not executed successfully. 371 */ 372 BTSTACK_API int GAPIF_AuthenticationReq(const BtAddr *addr); 373 374 /** 375 * @brief cancel authenticate the remote device associated. 376 * @param[in] addr target device address 377 * @return @c BT_NO_ERROR : The function is executed successfully. 378 * @c otherwise : The function is not executed successfully. 379 */ 380 BTSTACK_API int GAPIF_CancelAuthenticationReq(const BtAddr *addr); 381 382 /** 383 * @brief Respond IO capability request. Reply callback GapAuthenticationCallback::IOCapabilityReq 384 * @param[in] addr target device address 385 * @param[in] accept accept or reject 386 * @param[in] ioCapability local device IO capability 387 * @param[in] oobDataPresent OOB authentication data from remote device present 388 * @param[in] authReq Authentication Requirements: MITM protection 389 * @return @c BT_NO_ERROR : The function is executed successfully. 390 * @c otherwise : The function is not executed successfully. 391 */ 392 BTSTACK_API int GAPIF_IOCapabilityRsp( 393 const BtAddr *addr, uint8_t accept, uint8_t ioCapability, uint8_t oobDataPresent, uint8_t authReq); 394 395 /** 396 * @brief Respond user confirmation request. Reply callback GapAuthenticationCallback::userConfirmReq 397 * @param[in] addr target device address 398 * @param[in] accept accept or reject 399 * @return @c BT_NO_ERROR : The function is executed successfully. 400 * @c otherwise : The function is not executed successfully. 401 */ 402 BTSTACK_API int GAPIF_UserConfirmRsp(const BtAddr *addr, uint8_t accept); 403 404 /** 405 * @brief Respond user passkey request. Reply callback GapAuthenticationCallback::userPasskeyReq 406 * @param[in] addr target device address 407 * @param[in] accept accept or reject 408 * @param[in] number user input number (000000 - 999999) 409 * @return @c BT_NO_ERROR : The function is executed successfully. 410 * @c otherwise : The function is not executed successfully. 411 */ 412 BTSTACK_API int GAPIF_UserPasskeyRsp(const BtAddr *addr, uint8_t accept, uint32_t number); 413 414 /** 415 * @brief Respond remote OOB data request. Reply callback GapAuthenticationCallback::remoteOobReq 416 * @param[in] addr target device address 417 * @param[in] accept accept or reject 418 * @param[in] data OOB data 419 * @return @c BT_NO_ERROR : The function is executed successfully. 420 * @c otherwise : The function is not executed successfully. 421 */ 422 BTSTACK_API int GAPIF_RemoteOobRsp(const BtAddr *addr, uint8_t accept, const GapOOBData *data); 423 424 /** 425 * @brief Respond PIN code request. Reply callback GapAuthenticationCallback::pinCodeReq 426 * @param[in] addr target device address 427 * @param[in] accept accept or reject 428 * @param[in] pinCode PIN code data 429 * @param[in] pinCodeLength PIN code data length 430 * @return @c BT_NO_ERROR : The function is executed successfully. 431 * @c otherwise : The function is not executed successfully. 432 */ 433 BTSTACK_API int GAPIF_PinCodeRsp(const BtAddr *addr, uint8_t accept, const uint8_t *pinCode, uint8_t pinCodeLength); 434 435 /** 436 * @brief Respond link key request. Reply callback GapAuthenticationCallback::linkKeyReq 437 * @param[in] addr target device address 438 * @param[in] accept accept or reject 439 * @param[in] linkKey link key 440 * @param[in] keyType link key type 441 * @return @c BT_NO_ERROR : The function is executed successfully. 442 * @c otherwise : The function is not executed successfully. 443 */ 444 BTSTACK_API int GAPIF_LinkKeyRsp( 445 const BtAddr *addr, uint8_t accept, const uint8_t linkKey[GAP_LINKKEY_SIZE], uint8_t keyType); 446 447 /** 448 * @brief Register device discover callback 449 * @param[in] callback device discover callback structure 450 * @param[in] context device discover callback context parameter 451 * @return @c BT_NO_ERROR : The function is executed successfully. 452 * @c otherwise : The function is not executed successfully. 453 */ 454 BTSTACK_API int GAPIF_RegisterDiscoveryCallback(const GapDiscoveryCallback *callback, void *context); 455 456 /** 457 * @brief Deregister device discover callback 458 * @return @c BT_NO_ERROR : The function is executed successfully. 459 * @c otherwise : The function is not executed successfully. 460 */ 461 BTSTACK_API int GAPIF_DeregisterDiscoveryCallback(void); 462 463 /** 464 * @brief discover other nearby BR/EDR Controllers 465 * @param[in] mode Inquiry mode 466 * @param[in] inquiryLength Maximum inquiry time.(n * 1.28s) 467 * @return @c BT_NO_ERROR : The function is executed successfully. 468 * @c otherwise : The function is not executed successfully. 469 */ 470 BTSTACK_API int GAPIF_Inquiry(uint8_t mode, uint8_t inquiryLength); 471 472 /** 473 * @brief Cancel discover other nearby BR/EDR Controllers 474 * @return @c BT_NO_ERROR : The function is executed successfully. 475 * @c otherwise : The function is not executed successfully. 476 */ 477 BTSTACK_API int GAPIF_InquiryCancel(void); 478 479 /** 480 * @brief Get remote device name 481 * @param[in] addr target device address 482 * @return @c BT_NO_ERROR : The function is executed successfully. 483 * @c otherwise : The function is not executed successfully. 484 */ 485 BTSTACK_API int GAPIF_GetRemoteName(const BtAddr *addr); 486 487 /** 488 * @brief Cancel get remote device name 489 * @param[in] addr target device address 490 * @return @c BT_NO_ERROR : The function is executed successfully. 491 * @c otherwise : The function is not executed successfully. 492 */ 493 BTSTACK_API int GAPIF_GetRemoteNameCancel(const BtAddr *addr); 494 495 /** 496 * @brief Get local bluetooth address from HCI. 497 * @param[out] addr Bluetooth address of bluetooth chip. 498 * @return @c BT_NO_ERROR : The function is executed successfully. 499 * @c otherwise : The function is not executed successfully. 500 */ 501 BTSTACK_API int GAPIF_GetLocalAddr(BtAddr *addr); 502 503 #ifdef __cplusplus 504 } 505 #endif 506 507 #endif /* GAP_IF_H */ 508