1 //
2 //  Copyright (C) 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