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