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