Home | History | Annotate | Download | only in bluetooth
      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.
    122   Mode mode() const { return mode_; }
    123   void set_mode(Mode mode) { mode_ = mode; }
    124 
    125   // Returns the callback type.
    126   CallbackTypeBitField callback_type() const { return callback_type_; }
    127   void set_callback_type(CallbackTypeBitField type) { callback_type_ = type; }
    128 
    129   // Returns the scan result type.
    130   ResultType result_type() const { return result_type_; }
    131   void set_result_type(ResultType type) { result_type_ = type; }
    132 
    133   // Returns the report delay value in milliseconds.
    134   const base::TimeDelta& report_delay() const { return report_delay_ms_; }
    135   void set_report_delay(const base::TimeDelta& delay) {
    136     report_delay_ms_ = delay;
    137   }
    138 
    139   // Returns the hardware filter match mode.
    140   MatchMode match_mode() const { return match_mode_; }
    141   void set_match_mode(MatchMode mode) { match_mode_ = mode; }
    142 
    143   // Returns the count of advertisements to match per filter.
    144   MatchCount match_count_per_filter() const { return match_count_per_filter_; }
    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