1 /* 2 * Copyright 2019 HIMSA II K/S - www.himsa.com. 3 * Represented by EHIMA - www.ehima.com 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 #ifndef BLE_SCANNER_HCI_INTERFACE_H 19 #define BLE_SCANNER_HCI_INTERFACE_H 20 21 #include <base/functional/callback.h> 22 23 #include <vector> 24 25 #include "stack/include/bt_types.h" 26 #include "types/raw_address.h" 27 28 class BleScannerHciInterface { 29 public: 30 using status_cb = base::Callback<void(uint8_t /* status */)>; 31 using list_size_cb = base::Callback<void(int8_t /* list_size */)>; 32 using handle_cb = 33 base::Callback<void(uint8_t /* status */, uint16_t /* adv_handle */)>; 34 35 static void Initialize(); 36 static BleScannerHciInterface* Get(); 37 static void CleanUp(); 38 39 virtual ~BleScannerHciInterface() = default; 40 41 class ScanEventObserver { 42 public: 43 virtual ~ScanEventObserver() = default; 44 virtual void OnPeriodicScanResult(uint16_t sync_handle, uint8_t tx_power, 45 int8_t rssi, uint8_t cte_type, 46 uint8_t pkt_data_status, 47 uint8_t pkt_data_len, 48 const uint8_t* pkt_data) = 0; 49 virtual void OnPeriodicScanEstablished( 50 uint8_t status, uint16_t sync_handle, uint8_t set_id, 51 uint8_t adv_addr_type, const RawAddress& adv_addr, uint8_t adv_phy, 52 uint16_t adv_interval, uint8_t adv_clock_accuracy) = 0; 53 virtual void OnPeriodicScanLost(uint16_t sync_handle) = 0; 54 }; 55 56 virtual void SetScanEventObserver(ScanEventObserver* observer) = 0; 57 58 /** 59 * Used to synchronize with a periodic advertising train from an advertiser 60 * and begin receiving periodic advertising packets. 61 * 62 * @param options bit 0: whether to use advertiser list, adv_sid, 63 * adv_addr_type and adv_addr parameters are being used otherwise, bit 1: 64 * whether reporting is initially disabled, all other bits: Reserved for 65 * future use 66 * @param adv_sid advertising set ID 67 * @param adv_addr_type advertiser device address type 68 * @param adv_addr advertiser device address 69 * @param skip_num the maximum number of periodic advertising events that can 70 * be skipped after a successful receive. Range: 0x0000 to 0x01F3. 71 * @param sync_timeout synchronization timeout for the periodic advertising 72 * train, Range: 0x000A to 0x4000, Time = N*10 ms, Range: 100 ms to 163.84s 73 * @param sync_cte_type bit 0: do not sync to packets with an AoA Constant 74 * Tone Extension, bit 1: do not sync to packets with an AoD Constant Tone 75 * Extension with 1 μs slots, bit 2: do not sync to packets with an AoD 76 * Constant Tone Extension with 2 μs slots, bit 3: do not sync to packets with 77 * a type 3 Constant Tone Extension (currently reserved for future use), 78 * bit 4: do not sync to packets without a Constant Tone Extension, all other 79 * bits: reserved for future use. 80 */ 81 virtual void PeriodicScanStart(uint8_t options, uint8_t set_id, 82 uint8_t adv_addr_type, 83 const RawAddress& adv_addr, uint16_t skip_num, 84 uint16_t sync_timeout, 85 uint8_t sync_cte_type) = 0; 86 87 /** 88 * Used to cancel the HCI_LE_Periodic_Advertising_Create_Sync command while it 89 * is pending. 90 * 91 * @param cb status callback 92 */ 93 virtual void PeriodicScanCancelStart(status_cb cb) = 0; 94 95 /** 96 * Used to stop reception of the periodic advertising train identified by the 97 * Sync_Handle parameter. 98 * 99 * @param sync_handle synced advertising handle 100 * @param cb status callback 101 */ 102 virtual void PeriodicScanTerminate(uint16_t sync_handle, status_cb cb) = 0; 103 104 /** 105 * Enable or disable reports for the periodic advertising train defined by the 106 * sync_handle. 107 * 108 * @param sync_handle synced advewrtising handle 109 * @param enable whether enable or disable the advertising reports 110 * @param cb status callback 111 */ 112 virtual void PeriodicScanResultEvtEnable(uint16_t sync_handle, bool enable, 113 status_cb cb) = 0; 114 115 /** 116 * Used to add an entry, consisting of a single device address and SID, to the 117 * Periodic Advertiser list stored in the Controller. Any additions to the 118 * Periodic Advertiser list take effect immediately. If the entry is already 119 * on the list, the Controller shall return the error code Invalid HCI Command 120 * Parameters (0x12). 121 * 122 * @param adv_addr_type advertiser device address type 123 * @param adv_addr advertiser device address 124 * @param adv_sid advertising set ID 125 * @param cb status callback 126 */ 127 virtual void PeriodicAdvertiserListAddDevice(uint8_t adv_addr_type, 128 RawAddress& adv_addr, 129 uint8_t adv_sid, 130 status_cb cb) = 0; 131 /** 132 * Remove one entry from the list of Periodic Advertisers stored in the 133 * Controller. Removals from the Periodic Advertisers List take effect 134 * immediately. 135 * 136 * @param adv_addr_type advertiser device address type 137 * @param adv_addr advertiser device address 138 * @param adv_sid advertising set ID 139 * @param cb status callback 140 */ 141 virtual void PeriodicAdvertiserListRemoveDevice(uint8_t adv_addr_type, 142 RawAddress& adv_addr, 143 uint8_t adv_sid, 144 status_cb cb) = 0; 145 146 /** 147 * Remove all entries from the list of Periodic Advertisers in the Controller. 148 * 149 * @param cb status callback 150 */ 151 virtual void PeriodicAdvertiserListClear(status_cb cb) = 0; 152 153 /** 154 * Read the total number of Periodic Advertiser list entries that can be 155 * stored in the Controller. 156 * 157 * @param cb status and advertiser list size callback 158 */ 159 virtual void PeriodicAdvertiserListGetSize(list_size_cb cb) = 0; 160 161 /** 162 * Send synchronization information about the periodic advertising train 163 * identified by the sync_handle parameter to a connected device. 164 * 165 * @param bd_addr connected peer device address to whom sync data is 166 * transferred 167 * @param service_data a value provided by the Host 168 * @param sync_handle synced advewrtising handle 169 * @param cb status and connection handle callback 170 */ 171 virtual void PeriodicAdvSyncTransfer(const RawAddress& bd_addr, 172 uint16_t service_data, 173 uint16_t sync_handle, handle_cb cb) = 0; 174 175 /** 176 * Send synchronization information about the periodic advertising in an 177 * advertising set to a connected device. 178 * 179 * @param bd_addr connected peer device address to whom set info is 180 * transferred 181 * @param service_data a value provided by the Host 182 * @param sync_handle synced advertising handle 183 * @param cb status and connection handle callback 184 */ 185 virtual void PeriodicAdvSetInfoTransfer(const RawAddress& bd_addr, 186 uint16_t service_data, 187 uint8_t sync_handle, 188 handle_cb cb) = 0; 189 190 /** 191 * Specify how the Controller will process periodic advertising 192 * synchronization information received from the device identified by the 193 * bd_addr 194 * 195 * @param bd_addr connected peer device address who transfers the sync data 196 * @param mode 0x00: No attempt is made to synchronize to the periodic 197 * advertising and no HCI_LE_Periodic_Advertising_Sync_Transfer_Received event 198 * is sent to the Host. 0x01: An 199 * HCI_LE_Periodic_Advertising_Sync_Transfer_Received event is sent to the 200 * Host. HCI_LE_Periodic_Advertising_Report events will be disabled. 0x02: An 201 * HCI_LE_Periodic_Advertising_Sync_Transfer_Received event is sent to the 202 * Host. HCI_LE_Periodic_Advertising_Report events will be enabled. All other 203 * values: Reserved for future use. 204 * @param skip The number of periodic advertising packets that can be skipped 205 * after a successful receive, Range: 0x0000 to 0x01F3 206 * @param sync_timeout Synchronization timeout for the periodic advertising 207 * train. Range: 0x000A to 0x4000. Time = N*10 ms. Time Range: 100 ms to 208 * 163.84 s 209 * @param cte_type bit 0: do not sync to packets with an AoA Constant Tone 210 * Extension, bit 1: do not sync to packets with an AoD Constant Tone 211 * Extension with 1 μs slots, bit 2: do not sync to packets with an AoD 212 * Constant Tone Extension with 2 μs slots, bit 4: do not sync to packets 213 * without a Constant Tone Extension, all other values: reserved for future 214 * use. 215 * @param set_defaults whether to send 216 * HCI_LE_SET_DEFAULT_PERIODIC_ADVERTISING_SYNC_TRANSFER_PARAM or 217 * HCI_LE_SET_PERIODIC_ADVERTISING_SYNC_TRANSFER_PARAM. 218 * @param cb status callback 219 */ 220 virtual void SetPeriodicAdvSyncTransferParams(const RawAddress& bd_addr, 221 uint8_t mode, uint16_t skip, 222 uint16_t sync_timeout, 223 uint8_t cte_type, 224 bool set_defaults, 225 status_cb cb) = 0; 226 227 static constexpr uint8_t kOptUseAdvertiserList = 0x01; 228 static constexpr uint8_t kOptReportsInitiallyEnabled = 0x02; 229 }; 230 231 #endif // BLE_SCANNER_HCI_INTERFACE_H 232