1 /******************************************************************************
2  *
3  *  Copyright 1999-2012 Broadcom Corporation
4  *
5  *  Licensed under the Apache License, Version 2.0 (the "License");
6  *  you may not use this file except in compliance with the License.
7  *  You may obtain a copy of the License at:
8  *
9  *  http://www.apache.org/licenses/LICENSE-2.0
10  *
11  *  Unless required by applicable law or agreed to in writing, software
12  *  distributed under the License is distributed on an "AS IS" BASIS,
13  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  *  See the License for the specific language governing permissions and
15  *  limitations under the License.
16  *
17  ******************************************************************************/
18 
19 /******************************************************************************
20  *
21  *  This file contains the Bluetooth Manager (BTM) API function external
22  *  definitions.
23  *
24  ******************************************************************************/
25 #ifndef BTM_BLE_API_H
26 #define BTM_BLE_API_H
27 
28 #include <base/functional/callback_forward.h>
29 #include <hardware/bt_common_types.h>
30 
31 #include <cstdint>
32 #include <memory>
33 
34 #include "btm_api.h"
35 #include "btm_ble_api_types.h"
36 #include "stack/btm/neighbor_inquiry.h"
37 #include "types/bt_transport.h"
38 #include "types/raw_address.h"
39 
40 void btm_ble_init();
41 void btm_ble_free();
42 
43 /*****************************************************************************
44  *  EXTERNAL FUNCTION DECLARATIONS
45  ****************************************************************************/
46 
47 /*******************************************************************************
48  *
49  * Function         BTM_BleGetVendorCapabilities
50  *
51  * Description      This function reads local LE features
52  *
53  * Parameters       p_cmn_vsc_cb : Locala LE capability structure
54  *
55  * Returns          void
56  *
57  ******************************************************************************/
58 void BTM_BleGetVendorCapabilities(tBTM_BLE_VSC_CB* p_cmn_vsc_cb);
59 
60 /*******************************************************************************
61  *
62  * Function         BTM_BleGetDynamicAudioBuffer
63  *
64  * Description      This function reads dynamic audio buffer
65  *
66  * Parameters       p_dynamic_audio_buffer_cb : Dynamic Audio Buffer structure
67  *
68  * Returns          void
69  *
70  ******************************************************************************/
71 void BTM_BleGetDynamicAudioBuffer(
72     tBTM_BT_DYNAMIC_AUDIO_BUFFER_CB* p_dynamic_audio_buffer_cb);
73 
74 /*******************************************************************************
75  *
76  * Function         BTM_BleObserve
77  *
78  * Description      This procedure keep the device listening for advertising
79  *                  events from a broadcast device.
80  *
81  * Parameters       start: start or stop observe.
82  *                  duration: how long the scan should last, in seconds. 0 means
83  *                  scan without timeout. Starting the scan second time without
84  *                  timeout will disable the timer.
85  *                  low_latency_scan: whether this is a low latency scan,
86  *                                    default is false.
87  *
88  * Returns          void
89  *
90  ******************************************************************************/
91 tBTM_STATUS BTM_BleObserve(bool start, uint8_t duration,
92                            tBTM_INQ_RESULTS_CB* p_results_cb,
93                            tBTM_CMPL_CB* p_cmpl_cb,
94                            bool low_latency_scan = false);
95 
96 /*******************************************************************************
97  *
98  * Function         BTM_BleOpportunisticObserve
99  *
100  * Description      Register/unregister opportunistic scan callback. This method
101  *                  does not trigger scan start/stop, but if scan is ever started,
102  *                  this callback would get called with scan results. Additionally,
103  *                  this callback is not reset on each scan start/stop. It's
104  *                  intended to be used by LE Audio related profiles, that would
105  *                  find yet unpaired members of CSIS set, or broadcasts.
106  *
107  * Parameters       enable: enable/disable observing.
108  *                  p_results_cb: callback for results.
109  *
110  * Returns          void
111  *
112  ******************************************************************************/
113 void BTM_BleOpportunisticObserve(bool enable,
114                                  tBTM_INQ_RESULTS_CB* p_results_cb);
115 
116 /*******************************************************************************
117  *
118  * Function         BTM_BleTargetAnnouncementObserve
119  *
120  * Description      Register/Unregister client interested in the targeted
121  *                  announcements. Not that it is client responsible for parsing
122  *                  advertising data.
123  *
124  * Parameters       start: start or stop observe.
125  *                  p_results_cb: callback for results.
126  *
127  * Returns          void
128  *
129  ******************************************************************************/
130 void BTM_BleTargetAnnouncementObserve(bool enable,
131                                       tBTM_INQ_RESULTS_CB* p_results_cb);
132 
133 /*******************************************************************************
134  *
135  * Function         BTM_IsBleConnection
136  *
137  * Description      This function is called to check if the connection handle
138  *                  for an LE link
139  *
140  * Returns          true if connection is LE link, otherwise false.
141  *
142  ******************************************************************************/
143 bool BTM_IsBleConnection(uint16_t conn_handle);
144 
145 /*******************************************************************************
146  *
147  * Function         BTM_ReadRemoteConnectionAddr
148  *
149  * Description      Read the remote device address currently used.
150  *
151  * Returns          void
152  *
153  ******************************************************************************/
154 bool BTM_ReadRemoteConnectionAddr(const RawAddress& pseudo_addr,
155                                   RawAddress& conn_addr,
156                                   tBLE_ADDR_TYPE* p_addr_type,
157                                   bool ota_address);
158 
159 
160 #include "stack/btm/btm_ble_bgconn.h"
161 
162 /********************************************************
163  *
164  * Function         BTM_BleSetPrefConnParams
165  *
166  * Description      Set a peripheral's preferred connection parameters. When
167  *                  any of the value does not want to be updated while others
168  *                  do, use BTM_BLE_CONN_PARAM_UNDEF for the ones want to
169  *                  leave untouched.
170  *
171  * Parameters:      bd_addr          - BD address of the peripheral
172  *                  min_conn_int     - minimum preferred connection interval
173  *                  max_conn_int     - maximum preferred connection interval
174  *                  peripheral_latency    - preferred peripheral latency
175  *                  supervision_tout - preferred supervision timeout
176  *
177  * Returns          void
178  *
179  ******************************************************************************/
180 void BTM_BleSetPrefConnParams(const RawAddress& bd_addr, uint16_t min_conn_int,
181                               uint16_t max_conn_int,
182                               uint16_t peripheral_latency,
183                               uint16_t supervision_tout);
184 
185 /******************************************************************************
186  *
187  * Function         BTM_BleReadControllerFeatures
188  *
189  * Description      Reads BLE specific controller features
190  *
191  * Parameters:      tBTM_BLE_CTRL_FEATURES_CBACK : Callback to notify when
192  *                  features are read
193  *
194  * Returns          void
195  *
196  ******************************************************************************/
197 void BTM_BleReadControllerFeatures(tBTM_BLE_CTRL_FEATURES_CBACK* p_vsc_cback);
198 
199 /*******************************************************************************
200  *
201  * Function         BTM_ReadDevInfo
202  *
203  * Description      This function is called to read the device/address type
204  *                  of BD address.
205  *
206  * Parameter        remote_bda: remote device address
207  *                  p_dev_type: output parameter to read the device type.
208  *                  p_addr_type: output parameter to read the address type.
209  *
210  ******************************************************************************/
211 void BTM_ReadDevInfo(const RawAddress& remote_bda, tBT_DEVICE_TYPE* p_dev_type,
212                      tBLE_ADDR_TYPE* p_addr_type);
213 
214 /*******************************************************************************
215  *
216  * Function         BTM_GetRemoteDeviceName
217  *
218  * Description      This function is called to get the dev name of remote device
219  *                  from NV
220  *
221  * Returns          true if success; otherwise failed.
222  *
223  *******************************************************************************/
224 bool BTM_GetRemoteDeviceName(const RawAddress& bda, BD_NAME bd_name);
225 
226 /*******************************************************************************
227  *
228  * Function         BTM_ReadConnectedTransportAddress
229  *
230  * Description      This function is called to read the paired device/address
231  *                  type of other device paired corresponding to the BD_address
232  *
233  * Parameter        remote_bda: remote device address, carry out the transport
234  *                              address
235  *                  transport: active transport
236  *
237  * Return           true if an active link is identified; false otherwise
238  *
239  ******************************************************************************/
240 bool BTM_ReadConnectedTransportAddress(RawAddress* remote_bda,
241                                        tBT_TRANSPORT transport);
242 
243 /*******************************************************************************
244  *
245  * Function         BTM_BleReceiverTest
246  *
247  * Description      This function is called to start the LE Receiver test
248  *
249  * Parameter       rx_freq - Frequency Range
250  *               p_cmd_cmpl_cback - Command Complete callback
251  *
252  ******************************************************************************/
253 void BTM_BleReceiverTest(uint8_t rx_freq, tBTM_CMPL_CB* p_cmd_cmpl_cback);
254 
255 /*******************************************************************************
256  *
257  * Function         BTM_BleTransmitterTest
258  *
259  * Description      This function is called to start the LE Transmitter test
260  *
261  * Parameter       tx_freq - Frequency Range
262  *                       test_data_len - Length in bytes of payload data in each
263  *                                       packet
264  *                       packet_payload - Pattern to use in the payload
265  *                       p_cmd_cmpl_cback - Command Complete callback
266  *
267  ******************************************************************************/
268 void BTM_BleTransmitterTest(uint8_t tx_freq, uint8_t test_data_len,
269                             uint8_t packet_payload,
270                             tBTM_CMPL_CB* p_cmd_cmpl_cback);
271 
272 /*******************************************************************************
273  *
274  * Function         BTM_BleTestEnd
275  *
276  * Description     This function is called to stop the in-progress TX or RX test
277  *
278  * Parameter       p_cmd_cmpl_cback - Command complete callback
279  *
280  ******************************************************************************/
281 void BTM_BleTestEnd(tBTM_CMPL_CB* p_cmd_cmpl_cback);
282 
283 /*******************************************************************************
284  *
285  * Function         BTM_UseLeLink
286  *
287  * Description      Select the underlying physical link to use.
288  *
289  * Returns          true to use LE, false use BR/EDR.
290  *
291  ******************************************************************************/
292 bool BTM_UseLeLink(const RawAddress& bd_addr);
293 
294 /*******************************************************************************
295  *
296  * Function         BTM_BleAdvFilterParamSetup
297  *
298  * Description      This function is called to setup the adv data payload filter
299  *                  condition.
300  *
301  ******************************************************************************/
302 void BTM_BleAdvFilterParamSetup(
303     tBTM_BLE_SCAN_COND_OP action, tBTM_BLE_PF_FILT_INDEX filt_index,
304     std::unique_ptr<btgatt_filt_param_setup_t> p_filt_params,
305     tBTM_BLE_PF_PARAM_CB cb);
306 
307 /*******************************************************************************
308  *
309  * Function         BTM_BleGetEnergyInfo
310  *
311  * Description      This function obtains the energy info
312  *
313  * Parameters       p_ener_cback - Callback pointer
314  *
315  * Returns          status
316  *
317  ******************************************************************************/
318 tBTM_STATUS BTM_BleGetEnergyInfo(tBTM_BLE_ENERGY_INFO_CBACK* p_ener_cback);
319 
320 /*******************************************************************************
321  *
322  * Function         BTM_SetBleDataLength
323  *
324  * Description      Set the maximum BLE transmission packet size
325  *
326  * Returns          BTM_SUCCESS if success; otherwise failed.
327  *
328  ******************************************************************************/
329 tBTM_STATUS BTM_SetBleDataLength(const RawAddress& bd_addr,
330                                  uint16_t tx_pdu_length);
331 
332 /*******************************************************************************
333  *
334  * Function         BTM_BleReadPhy
335  *
336  * Description      To read the current PHYs for specified LE connection
337  *
338  *
339  * Returns          BTM_SUCCESS if success; otherwise failed.
340  *
341  ******************************************************************************/
342 void BTM_BleReadPhy(
343     const RawAddress& bd_addr,
344     base::Callback<void(uint8_t tx_phy, uint8_t rx_phy, uint8_t status)> cb);
345 
346 /*******************************************************************************
347  *
348  * Function         BTM_BleSetPhy
349  *
350  * Description      To set PHY preferences for specified LE connection
351  *
352  *
353  * Returns          BTM_SUCCESS if success; otherwise failed.
354  *
355  ******************************************************************************/
356 void BTM_BleSetPhy(const RawAddress& bd_addr, uint8_t tx_phys, uint8_t rx_phys,
357                    uint16_t phy_options);
358 
359 /*******************************************************************************
360  *
361  * Function         btm_ble_get_acl_remote_addr
362  *
363  * Description      This function reads the active remote address used for the
364  *                  connection.
365  *
366  * Returns          success return true, otherwise false.
367  *
368  ******************************************************************************/
369 bool btm_ble_get_acl_remote_addr(uint16_t hci_handle, RawAddress& conn_addr,
370                                  tBLE_ADDR_TYPE* p_addr_type);
371 
372 using StartSyncCb = base::Callback<void(
373     uint8_t /*status*/, uint16_t /*sync_handle*/, uint8_t /*advertising_sid*/,
374     uint8_t /*address_type*/, RawAddress /*address*/, uint8_t /*phy*/,
375     uint16_t /*interval*/)>;
376 using SyncReportCb = base::Callback<void(
377     uint16_t /*sync_handle*/, int8_t /*tx_power*/, int8_t /*rssi*/,
378     uint8_t /*status*/, std::vector<uint8_t> /*data*/)>;
379 using SyncLostCb = base::Callback<void(uint16_t /*sync_handle*/)>;
380 using BigInfoReportCb = base::Callback<void(uint16_t /*sync_handle*/, bool /*encrypted*/)>;
381 
382 void btm_ble_periodic_adv_sync_established(uint8_t status, uint16_t sync_handle,
383                                            uint8_t adv_sid,
384                                            uint8_t address_type,
385                                            const RawAddress& addr, uint8_t phy,
386                                            uint16_t interval,
387                                            uint8_t adv_clock_accuracy);
388 void btm_ble_periodic_adv_report(uint16_t sync_handle, uint8_t tx_power,
389                                  int8_t rssi, uint8_t cte_type,
390                                  uint8_t data_status, uint8_t data_len,
391                                  const uint8_t* periodic_data);
392 void btm_ble_periodic_adv_sync_lost(uint16_t sync_handle);
393 
394 /*******************************************************************************
395  *
396  * Function         BTM_BleConfigPrivacy
397  *
398  * Description      This function is called to enable or disable the privacy in
399  *                  the local device.
400  *
401  * Parameters       enable: true to enable it; false to disable it.
402  *
403  * Returns          bool    privacy mode set success; otherwise failed.
404  *
405  ******************************************************************************/
406 bool BTM_BleConfigPrivacy(bool enable);
407 
408 /*******************************************************************************
409  *
410  * Function         BTM_BleLocalPrivacyEnabled
411  *
412  * Description        Checks if local device supports private address
413  *
414  * Returns          Return true if local privacy is enabled else false
415  *
416  ******************************************************************************/
417 bool BTM_BleLocalPrivacyEnabled(void);
418 
419 #endif
420