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