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