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
27extern "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 */
36int 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 */
45int 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 */
53int 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 */
61int 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 */
75int 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 */
86int 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 */
96int 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 */
105int 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 */
114int 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 */
123int 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 */
130int 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 */
138int 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 */
148int 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 */
157int 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 */
164int 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 */
173int 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 */
181int 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 */
189int 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 */
201int 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 */
211int 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 */
221int 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 */
231int 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 */
242int 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 */
253int 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 */
262int 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 */
271int 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 */
278int 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 */
287int 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 */
294int 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 */
302int 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 */
310int 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 */
318int GAP_SetKeyMissingRetry(bool retry);
319#ifdef __cplusplus
320}
321#endif
322
323#endif /* GAP_H */
324