1 // 2 // Copyright 2015 Google, Inc. 3 // 4 // Licensed under the Apache License, Version 2.0 (the "License"); 5 // you may not use this file except in compliance with the License. 6 // You may obtain a copy of the License at: 7 // 8 // http://www.apache.org/licenses/LICENSE-2.0 9 // 10 // Unless required by applicable law or agreed to in writing, software 11 // distributed under the License is distributed on an "AS IS" BASIS, 12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 // See the License for the specific language governing permissions and 14 // limitations under the License. 15 // 16 17 #pragma once 18 19 #include <base/time/time.h> 20 21 namespace bluetooth { 22 23 // ScanSettings encapsulates Bluetooth LE device scan parameters. This is the 24 // native equivalent of the Android framework class defined in 25 // frameworks/base/core/java/android/bluetooth/le/ScanSettings.java. 26 class ScanSettings { 27 public: 28 // A scan mode describes the power consumption involved in LE scans. 29 enum Mode { 30 // A special Bluetooth LE scan mode. Applications using this scan mode will 31 // passively listen for other scan results without starting BLE scans 32 // themselves. 33 MODE_OPPORTUNISTIC = -1, 34 35 // Perform Bluetooth LE scan in low power mode. This is the default scan 36 // mode as it consumes the least power. 37 MODE_LOW_POWER = 0, 38 39 // Perform Bluetooth LE scan in balanced power mode. Scan results are 40 // returned at a rate that provides a good trade-off between scan frequency 41 // and power consumption. 42 MODE_BALANCED = 1, 43 44 // Scan using the highest duty cycle. It's recommended to only use this mode 45 // when the application is running in the foreground. 46 MODE_LOW_LATENCY = 2, 47 }; 48 49 // A callback type describes how scan results will be reported to applications 50 // in asynchronous callbacks. 51 enum CallbackType { 52 // Trigger a callback for every Bluetooth advertisement found that matches 53 // the filter criteria. If no filter is active, all advertisement packets 54 // are reported. 55 CALLBACK_TYPE_ALL_MATCHES = 1, 56 57 // A result callback is only triggered for the first advertisement packet 58 // received that matches the filter criteria. This requires that the 59 // hardware support the offloaded filtering feature. 60 CALLBACK_TYPE_FIRST_MATCH = 2, 61 62 // Receive a callback when advertisements are no longer received from a 63 // device that has been previously reported by a first match callback. This 64 // requires that the hardware support the offloaded filtering feature. 65 CALLBACK_TYPE_MATCH_LOST = 4, 66 }; 67 using CallbackTypeBitField = int; 68 69 // Determines how many advertisements to match per filter. 70 enum MatchCount { 71 // Match one advertisement per filter. 72 MATCH_COUNT_ONE_ADVERTISEMENT = 1, 73 74 // Match few advertisements per filter depending on the current capability 75 // and availability of hardware resources. 76 MATCH_COUNT_FEW_ADVERTISEMENTS = 2, 77 78 // Match as many advertisements per filter as the underlying hardware can 79 // allow, depending on the current capability and availability of hardware 80 // resources. 81 MATCH_COUNT_MAX_ADVERTISEMENTS = 3, 82 }; 83 84 // Hardware filter match mode. 85 enum MatchMode { 86 // In aggressive mode the hardware will determine a match sooner even with 87 // feeble signal strength and a low number of sightings in a duration. 88 MATCH_MODE_AGGRESSIVE = 1, 89 90 // In sticky mode a higher threshold of signal strength and sightings is 91 // required before a scan result is reported by the hardware. 92 MATCH_MODE_STICKY = 2, 93 }; 94 95 // Scan result type describes the contents of each scan result. 96 enum ResultType { 97 // Request full scan results which contain the device name, RSSI, 98 // advertising data, scan response data, and the scan timestamp. 99 RESULT_TYPE_FULL = 0, 100 101 // Request abbreviated scan results which contain the device name, RSSI, and 102 // scan timestamp. 103 // Note: It is possible for an application to get more scan results than it 104 // asked for, if there are multiple apps using this type. 105 RESULT_TYPE_ABBREVIATED = 1, 106 }; 107 108 // The default constructor sets all fields to defaults: 109 // mode: MODE_LOW_POWER 110 // callback_type: CALLBACK_TYPE_ALL_MATCHES 111 // result_type: RESULT_TYPE_FULL 112 // report_delay_ms: 0 113 // match_mode: MATCH_MODE_AGGRESSIVE 114 // match_count_per_filter: MATCH_COUNT_MAX_ADVERTISEMENTS 115 ScanSettings(); 116 ScanSettings(Mode mode, CallbackTypeBitField callback_type, 117 ResultType result_type, base::TimeDelta report_delay_ms, 118 MatchMode match_mode, MatchCount match_count_per_filter); 119 virtual ~ScanSettings() = default; 120 121 // Returns the scan mode. mode()122 Mode mode() const { return mode_; } set_mode(Mode mode)123 void set_mode(Mode mode) { mode_ = mode; } 124 125 // Returns the callback type. callback_type()126 CallbackTypeBitField callback_type() const { return callback_type_; } set_callback_type(CallbackTypeBitField type)127 void set_callback_type(CallbackTypeBitField type) { callback_type_ = type; } 128 129 // Returns the scan result type. result_type()130 ResultType result_type() const { return result_type_; } set_result_type(ResultType type)131 void set_result_type(ResultType type) { result_type_ = type; } 132 133 // Returns the report delay value in milliseconds. report_delay()134 const base::TimeDelta& report_delay() const { return report_delay_ms_; } set_report_delay(const base::TimeDelta & delay)135 void set_report_delay(const base::TimeDelta& delay) { 136 report_delay_ms_ = delay; 137 } 138 139 // Returns the hardware filter match mode. match_mode()140 MatchMode match_mode() const { return match_mode_; } set_match_mode(MatchMode mode)141 void set_match_mode(MatchMode mode) { match_mode_ = mode; } 142 143 // Returns the count of advertisements to match per filter. match_count_per_filter()144 MatchCount match_count_per_filter() const { return match_count_per_filter_; } set_match_count_per_filter(MatchCount count)145 void set_match_count_per_filter(MatchCount count) { 146 match_count_per_filter_ = count; 147 } 148 149 // Comparison operator. 150 bool operator==(const ScanSettings& rhs) const; 151 152 protected: 153 Mode mode_; 154 CallbackTypeBitField callback_type_; 155 ResultType result_type_; 156 base::TimeDelta report_delay_ms_; 157 MatchMode match_mode_; 158 MatchCount match_count_per_filter_; 159 }; 160 161 } // namespace bluetooth 162