ScanParameters.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2018-2018 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015 */
00016 
00017 #ifndef MBED_GAP_SCAN_PARAMETERS_H__
00018 #define MBED_GAP_SCAN_PARAMETERS_H__
00019 
00020 #include <stdint.h>
00021 #include "ble/blecommon.h"
00022 #include "BLETypes.h"
00023 
00024 namespace ble {
00025 
00026 /**
00027  * @addtogroup ble
00028  * @{
00029  * @addtogroup gap
00030  * @{
00031  */
00032 
00033 /**
00034  * Parameters defining the scan process.
00035  *
00036  * The scan process is defined by two main parameters:
00037  *   - The scan window that defines how long the device should scan.
00038  *   - The scan window that defines how frequently the device should scan.
00039  *
00040  * To scan continuously, the scan window and the scan interval should have the
00041  * same value.
00042  *
00043  * To get extra data from the advertising device, the scanner can send scan
00044  * requests to the advertiser; the advertiser may respond with scan responses.
00045  * It is possible to select what type of address is used to issue the scan request.
00046  *
00047  * With Bluetooth 5, devices can advertise on more physical channels, and by
00048  * extension, they can scan on more physical channels. It is possible to define
00049  * independent scan parameters for every scannable physical channel.
00050  */
00051 class ScanParameters {
00052 public:
00053 
00054     /**
00055      * Scan configuration of a physical channel.
00056      */
00057     struct phy_configuration_t {
00058         /**
00059          * Construct a phy_configuration_t.
00060          * @param scan_interval The scan interval.
00061          * @param scan_window The scan window.
00062          * @param active_scanning True if scan request should be sent and false
00063          * otherwise.
00064          */
00065         phy_configuration_t(
00066             scan_interval_t  scan_interval = scan_interval_t::min(),
00067             scan_window_t  scan_window = scan_window_t::min(),
00068             bool active_scanning = false
00069         ) :
00070             interval(scan_interval),
00071             window(scan_window),
00072             active_scanning(active_scanning)
00073         {
00074             if (window.value() > interval.value()) {
00075                 interval = window;
00076             }
00077         }
00078 
00079         /**
00080          * Get the scan interval.
00081          */
00082         const scan_window_t  &getInterval() const
00083         {
00084             return interval;
00085         }
00086 
00087         /**
00088          * Get the scan window.
00089          */
00090         const scan_interval_t  &getWindow() const
00091         {
00092             return window;
00093         }
00094 
00095         /**
00096          * Return if active scanning is set.
00097          */
00098         bool isActiveScanningSet() const
00099         {
00100             return active_scanning;
00101         }
00102 
00103     private:
00104         scan_window_t  interval;
00105         scan_interval_t  window;
00106         bool active_scanning;
00107     };
00108 
00109     /**
00110      * Construct a ScanParameters object that operates on a selected PHY.
00111      *
00112      * @param phy The phy to configure.
00113      * @param scan_interval The scan interval.
00114      * @param scan_window The scan window.
00115      * @param active_scanning active scanning flag.
00116      * @param own_address_type Address type used in scan requests.
00117      * @param scanning_filter_policy Filter applied.
00118      */
00119     ScanParameters(
00120         phy_t phy = phy_t::LE_1M,
00121         scan_window_t  scan_interval = scan_interval_t::min(),
00122         scan_interval_t  scan_window = scan_window_t::min(),
00123         bool active_scanning = false,
00124         own_address_type_t own_address_type = own_address_type_t::RANDOM,
00125         scanning_filter_policy_t scanning_filter_policy = scanning_filter_policy_t::NO_FILTER
00126     ) :
00127         own_address_type(own_address_type),
00128         scanning_filter_policy(scanning_filter_policy),
00129         phys(phy),
00130         phy_1m_configuration(),
00131         phy_coded_configuration()
00132     {
00133         phy_configuration_t conf(scan_interval, scan_window, active_scanning);
00134         if (phy == phy_t::LE_1M) {
00135             phy_1m_configuration = conf;
00136         }
00137 #if BLE_FEATURE_PHY_MANAGEMENT
00138         else if (phy == phy_t::LE_CODED) {
00139             phy_coded_configuration = conf;
00140         }
00141 #endif // BLE_FEATURE_PHY_MANAGEMENT
00142     }
00143 
00144     /**
00145      * Set the address type used for scan requests.
00146      * @param address The type of address to use during scan requests.
00147      * @return A reference to this object.
00148      */
00149     ScanParameters &setOwnAddressType(own_address_type_t address)
00150     {
00151         own_address_type = address;
00152         return *this;
00153     }
00154 
00155     /**
00156      * Get the address type used during scan requests.
00157      */
00158     own_address_type_t getOwnAddressType() const
00159     {
00160         return own_address_type;
00161     }
00162 
00163     /**
00164      * Set the filter to apply during scanning.
00165      * @param filter_policy The filter to apply during scanning.
00166      * @return A reference to this object.
00167      */
00168     ScanParameters &setFilter(scanning_filter_policy_t filter_policy)
00169     {
00170         scanning_filter_policy = filter_policy;
00171         return *this;
00172     }
00173 
00174     /**
00175      * Get the filter to use during scanning
00176      */
00177     scanning_filter_policy_t getFilter() const
00178     {
00179 #if BLE_FEATURE_WHITELIST
00180         return scanning_filter_policy;
00181 #else
00182         return scanning_filter_policy_t::NO_FILTER;
00183 #endif // BLE_FEATURE_WHITELIST
00184     }
00185 
00186     /**
00187      * Enable or disable PHYs that should be used during scanning.
00188      * @param enable_1m True to enable the 1M phy and false to disable it.
00189      * @param enable_coded True to enable the coded phy and false to disable it.
00190      * @return A reference to this object.
00191      */
00192     ScanParameters &setPhys(bool enable_1m, bool enable_coded)
00193     {
00194 #if BLE_FEATURE_PHY_MANAGEMENT
00195         phys.set_1m(enable_1m);
00196         phys.set_coded(enable_coded);
00197 #endif // BLE_FEATURE_PHY_MANAGEMENT
00198         return *this;
00199     }
00200 
00201     /**
00202      * Get the PHYs to use during scanning.
00203      */
00204     phy_set_t getPhys() const
00205     {
00206         return phys;
00207     }
00208 
00209     /**
00210      * Set the 1M scan configuration.
00211      * @param interval The scan interval to use.
00212      * @param window The scan window to use.
00213      * @param active_scanning The active scanning flag.
00214      * @return A reference to this object.
00215      */
00216     ScanParameters &set1mPhyConfiguration(
00217         scan_interval_t  interval,
00218         scan_window_t  window,
00219         bool active_scanning
00220     )
00221     {
00222         phys.set_1m(true);
00223         phy_1m_configuration = phy_configuration_t(
00224             interval, window, active_scanning
00225         );
00226         return *this;
00227     }
00228 
00229     /**
00230      * Get the 1M scan configuration.
00231      */
00232     phy_configuration_t get1mPhyConfiguration() const
00233     {
00234         return phy_1m_configuration;
00235     }
00236 
00237     /**
00238      * Set the coded PHY scan configuration.
00239      * @param interval The scan interval to use.
00240      * @param window The scan window to use.
00241      * @param active_scanning The active scanning flag.
00242      * @return A reference to this object.
00243      */
00244     ScanParameters &setCodedPhyConfiguration(
00245         scan_interval_t  interval,
00246         scan_window_t  window,
00247         bool active_scanning
00248     )
00249     {
00250 #if BLE_FEATURE_PHY_MANAGEMENT
00251         phys.set_coded(true);
00252         phy_coded_configuration = phy_configuration_t(
00253             interval, window, active_scanning
00254         );
00255 #endif // BLE_FEATURE_PHY_MANAGEMENT
00256         return *this;
00257     }
00258 
00259     /**
00260      * Get the coded PHY scan configuration.
00261      */
00262     phy_configuration_t getCodedPhyConfiguration() const
00263     {
00264         return phy_1m_configuration;
00265     }
00266 
00267 private:
00268     own_address_type_t own_address_type;
00269     scanning_filter_policy_t scanning_filter_policy;
00270 
00271     phy_set_t phys;
00272 
00273     phy_configuration_t phy_1m_configuration;
00274     phy_configuration_t phy_coded_configuration;
00275 };
00276 
00277 /**
00278  * @}
00279  * @}
00280  */
00281 
00282 } // namespace ble
00283 
00284 #endif /* ifndef MBED_GAP_SCAN_PARAMETERS_H__ */