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_H 17 #define GAP_H 18 19 #include <stdbool.h> 20 #include <stddef.h> 21 #include <stdlib.h> 22 23 #include "btstack.h" 24 #include "gap_if.h" 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 /** 31 * @brief Get local bluetooth address from HCI. 32 * @param[out] addr Bluetooth address of bluetooth chip. 33 * @return @c BT_SUCCESS : The function is executed successfully. 34 * @c otherwise : The function is not executed successfully. 35 */ 36 int GAP_GetLocalAddr(BtAddr *addr); 37 38 /** 39 * @brief Set local bluetooth device name. (Used for BR/EDR) 40 * @param[in] name Bluetooth device name. 41 * @param[in] length Length of the device name. (248 or less) 42 * @return @c BT_SUCCESS : The function is executed successfully. 43 * @c otherwise : The function is not executed successfully. 44 */ 45 int GAP_SetLocalName(const char *name, int length); 46 47 /** 48 * @brief Set local bluetooth device class. 49 * @param[in] cod Bluetooth device class. 50 * @return @c BT_SUCCESS : The function is executed successfully. 51 * @c otherwise : The function is not executed successfully. 52 */ 53 int GAP_SetClassOfDevice(uint32_t cod); 54 55 /** 56 * @brief Set local bluetooth device class. 57 * @param[in] cod Bluetooth device class. 58 * @return @c BT_SUCCESS : The function is executed successfully. 59 * @c otherwise : The function is not executed successfully. 60 */ 61 int GAP_SetExtendedInquiryResponse(const uint8_t eir[GAP_EIR_SIZE_MAX]); 62 63 /** 64 * @brief Set scan mode of bluetooth BR/EDR physical transport. 65 * @param[in] discoverInfo Discoverability modes configuration parameter. 66 * @param[in] connectableInfo Connectionability modes configuration parameter. 67 * @param[in] callback Callback function for the result. 68 * @param[in] context The context of the callback function. 69 * @return @c BT_SUCCESS : The function is executed successfully. 70 * @c otherwise : The function is not executed successfully. 71 * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part C 72 * 4.1 DISCOVERABILITY MODES 73 * 4.2 CONNECTABILITY MODES 74 */ 75 int GAP_SetScanMode(const GapDiscoverModeInfo *discoverInfo, const GapConnectableModeInfo *connectableInfo, 76 GapSetScanModeResultCallback callback, void *context); 77 78 /** 79 * @brief Set boneable mode of bluetooth BR/EDR physical transport. 80 * @param[in] bondableMode boneable mode 81 * @return @c BT_SUCCESS : The function is executed successfully. 82 * @c otherwise : The function is not executed successfully. 83 * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part C 84 * 4.3 BONDABLE MODES 85 */ 86 int GAP_SetBondableMode(uint8_t bondableMode); 87 88 /** 89 * @brief Service register security requirements to GAP 90 * @param[in] addr outgoing attributes to remote device 91 * @param[in] serviceInfo security requirements information 92 * @param[in] securityMode Security attributes 93 * @return @c BT_SUCCESS : The function is executed successfully. 94 * @c otherwise : The function is not executed successfully. 95 */ 96 int GAP_RegisterServiceSecurity(const BtAddr *addr, const GapServiceSecurityInfo *serviceInfo, uint16_t securityMode); 97 98 /** 99 * @brief Service deregister security requirements to GAP 100 * @param[in] addr outgoing attributes to remote device 101 * @param[in] serviceInfo security requirements information 102 * @return @c BT_SUCCESS : The function is executed successfully. 103 * @c otherwise : The function is not executed successfully. 104 */ 105 int GAP_DeregisterServiceSecurity(const BtAddr *addr, const GapServiceSecurityInfo *serviceInfo); 106 107 /** 108 * @brief Service request security requirements to GAP 109 * @param[in] addr target device address 110 * @param[in] param structure of security requirements information and result callback function 111 * @return @c BT_SUCCESS : The function is executed successfully. 112 * @c otherwise : The function is not executed successfully. 113 */ 114 int GAP_RequestSecurity(const BtAddr *addr, const GapRequestSecurityParam *param); 115 116 /** 117 * @brief Register service security verify callback 118 * @param[in] callback security verify callback 119 * @param[in] context security verify callback context parameter 120 * @return @c BT_SUCCESS : The function is executed successfully. 121 * @c otherwise : The function is not executed successfully. 122 */ 123 int GAP_RegisterSecurityCallback(const GapSecurityCallback *callback, void *context); 124 125 /** 126 * @brief Deregister service security verify callback 127 * @return @c BT_SUCCESS : The function is executed successfully. 128 * @c otherwise : The function is not executed successfully. 129 */ 130 int GAP_DeregisterSecurityCallback(void); 131 132 /** 133 * @brief Set security modes of BR/EDR physical transport 134 * @param[in] mode security modes 135 * @return @c BT_SUCCESS : The function is executed successfully. 136 * @c otherwise : The function is not executed successfully. 137 */ 138 int GAP_SetSecurityMode(GAP_SecurityMode mode); 139 140 /** 141 * @brief Service authorization verify response 142 * @param[in] addr target device address 143 * @param[in] service service identity 144 * @param[in] accept accept or reject 145 * @return @c BT_SUCCESS : The function is executed successfully. 146 * @c otherwise : The function is not executed successfully. 147 */ 148 int GAP_AuthorizeRes(const BtAddr *addr, GAP_Service service, uint8_t accept); 149 150 /** 151 * @brief Register authentication callback 152 * @param[in] callback authentication callback structure 153 * @param[in] context authentication verify callback context parameter 154 * @return @c BT_SUCCESS : The function is executed successfully. 155 * @c otherwise : The function is not executed successfully. 156 */ 157 int GAP_RegisterAuthenticationCallback(const GapAuthenticationCallback *callback, void *context); 158 159 /** 160 * @brief Deregister authentication callback 161 * @return @c BT_SUCCESS : The function is executed successfully. 162 * @c otherwise : The function is not executed successfully. 163 */ 164 int GAP_DeregisterAuthenticationCallback(void); 165 166 /** 167 * @brief Get current pair originator 168 * @param[in] addr pairing device address 169 * @param[out] isLocal is local initiate 170 * @return @c BT_SUCCESS : The function is executed successfully. 171 * @c otherwise : The function is not executed successfully. 172 */ 173 int GAP_PairIsFromLocal(const BtAddr *addr, bool *isLocal); 174 175 /** 176 * @brief authenticate the remote device associated. 177 * @param[in] addr target device address 178 * @return @c BT_SUCCESS : The function is executed successfully. 179 * @c otherwise : The function is not executed successfully. 180 */ 181 int GAP_AuthenticationReq(const BtAddr *addr); 182 183 /** 184 * @brief cancel authenticate the remote device associated. 185 * @param[in] addr target device address 186 * @return @c BT_SUCCESS : The function is executed successfully. 187 * @c otherwise : The function is not executed successfully. 188 */ 189 int GAP_CancelAuthenticationReq(const BtAddr *addr); 190 191 /** 192 * @brief Respond IO capability request. Reply callback GapAuthenticationCallback::IOCapabilityReq 193 * @param[in] addr target device address 194 * @param[in] accept accept or reject 195 * @param[in] ioCapability local device IO capability 196 * @param[in] oobDataPresent OOB authentication data from remote device present 197 * @param[in] authReq Authentication Requirements: MITM protection 198 * @return @c BT_SUCCESS : The function is executed successfully. 199 * @c otherwise : The function is not executed successfully. 200 */ 201 int GAP_IOCapabilityRsp( 202 const BtAddr *addr, uint8_t accept, uint8_t ioCapability, uint8_t oobDataPresent, uint8_t authReq); 203 204 /** 205 * @brief Respond user confirmation request. Reply callback GapAuthenticationCallback::userConfirmReq 206 * @param[in] addr target device address 207 * @param[in] accept accept or reject 208 * @return @c BT_SUCCESS : The function is executed successfully. 209 * @c otherwise : The function is not executed successfully. 210 */ 211 int GAP_UserConfirmRsp(const BtAddr *addr, uint8_t accept); 212 213 /** 214 * @brief Respond user passkey request. Reply callback GapAuthenticationCallback::userPasskeyReq 215 * @param[in] addr target device address 216 * @param[in] accept accept or reject 217 * @param[in] number user input number (000000 - 999999) 218 * @return @c BT_SUCCESS : The function is executed successfully. 219 * @c otherwise : The function is not executed successfully. 220 */ 221 int GAP_UserPasskeyRsp(const BtAddr *addr, uint8_t accept, uint32_t number); 222 223 /** 224 * @brief Respond remote OOB data request. Reply callback GapAuthenticationCallback::remoteOobReq 225 * @param[in] addr target device address 226 * @param[in] accept accept or reject 227 * @param[in] data OOB data 228 * @return @c BT_SUCCESS : The function is executed successfully. 229 * @c otherwise : The function is not executed successfully. 230 */ 231 int GAP_RemoteOobRsp(const BtAddr *addr, uint8_t accept, const GapOOBData *data); 232 233 /** 234 * @brief Respond PIN code request. Reply callback GapAuthenticationCallback::pinCodeReq 235 * @param[in] addr target device address 236 * @param[in] accept accept or reject 237 * @param[in] pinCode PIN code data 238 * @param[in] pinCodeLength PIN code data length 239 * @return @c BT_SUCCESS : The function is executed successfully. 240 * @c otherwise : The function is not executed successfully. 241 */ 242 int GAP_PinCodeRsp(const BtAddr *addr, uint8_t accept, const uint8_t *pinCode, uint8_t pinCodeLength); 243 244 /** 245 * @brief Respond link key request. Reply callback GapAuthenticationCallback::linkKeyReq 246 * @param[in] addr target device address 247 * @param[in] accept accept or reject 248 * @param[in] linkKey link key 249 * @param[in] keyType link key type 250 * @return @c BT_SUCCESS : The function is executed successfully. 251 * @c otherwise : The function is not executed successfully. 252 */ 253 int GAP_LinkKeyRsp(const BtAddr *addr, uint8_t accept, const uint8_t linkKey[GAP_LINKKEY_SIZE], uint8_t keyType); 254 255 /** 256 * @brief Get local OOB data to paired. 257 * @param[out] oobData192 258 * @param[out] oobData256 259 * @return @c BT_SUCCESS : The function is executed successfully. 260 * @c otherwise : The function is not executed successfully. 261 */ 262 int GAP_GetLocalExtendedOOBData(GapOOBData *oobData192, GapOOBData *oobData256); 263 264 /** 265 * @brief Register device discover callback 266 * @param[in] callback device discover callback structure 267 * @param[in] context device discover callback context parameter 268 * @return @c BT_SUCCESS : The function is executed successfully. 269 * @c otherwise : The function is not executed successfully. 270 */ 271 int GAP_RegisterDiscoveryCallback(const GapDiscoveryCallback *callback, void *context); 272 273 /** 274 * @brief Deregister device discover callback 275 * @return @c BT_SUCCESS : The function is executed successfully. 276 * @c otherwise : The function is not executed successfully. 277 */ 278 int GAP_DeregisterDiscoveryCallback(void); 279 280 /** 281 * @brief discover other nearby BR/EDR Controllers 282 * @param[in] mode Inquiry mode 283 * @param[in] inquiryLength Maximum inquiry time.(n * 1.28s) 284 * @return @c BT_SUCCESS : The function is executed successfully. 285 * @c otherwise : The function is not executed successfully. 286 */ 287 int GAP_Inquiry(uint8_t mode, uint8_t inquiryLength); 288 289 /** 290 * @brief Cancel discover other nearby BR/EDR Controllers 291 * @return @c BT_SUCCESS : The function is executed successfully. 292 * @c otherwise : The function is not executed successfully. 293 */ 294 int GAP_InquiryCancel(void); 295 296 /** 297 * @brief Get remote device name 298 * @param[in] addr target device address 299 * @return @c BT_SUCCESS : The function is executed successfully. 300 * @c otherwise : The function is not executed successfully. 301 */ 302 int GAP_GetRemoteName(const BtAddr *addr); 303 304 /** 305 * @brief Cancel get remote device name 306 * @param[in] addr target device address 307 * @return @c BT_SUCCESS : The function is executed successfully. 308 * @c otherwise : The function is not executed successfully. 309 */ 310 int GAP_GetRemoteNameCancel(const BtAddr *addr); 311 312 /** 313 * @brief Set configuration of retry pairing when remote device delete linkkey. 314 * @param[in] retry do retry 315 * @return @c BT_SUCCESS : The function is executed successfully. 316 * @c otherwise : The function is not executed successfully. 317 */ 318 int GAP_SetKeyMissingRetry(bool retry); 319 #ifdef __cplusplus 320 } 321 #endif 322 323 #endif /* GAP_H */ 324