GapScanningParams.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 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 __GAP_SCANNING_PARAMS_H__
00018 #define __GAP_SCANNING_PARAMS_H__
00019 
00020 class GapScanningParams {
00021 public:
00022     static const unsigned SCAN_INTERVAL_MIN = 0x0004; /**< Minimum Scan interval in 625us units - 2.5ms. */
00023     static const unsigned SCAN_INTERVAL_MAX = 0x4000; /**< Maximum Scan interval in 625us units - 10.24s. */
00024     static const unsigned SCAN_WINDOW_MIN   = 0x0004; /**< Minimum Scan window in 625us units - 2.5ms. */
00025     static const unsigned SCAN_WINDOW_MAX   = 0x4000; /**< Maximum Scan window in 625us units - 10.24s. */
00026     static const unsigned SCAN_TIMEOUT_MIN  = 0x0001; /**< Minimum Scan timeout in seconds. */
00027     static const unsigned SCAN_TIMEOUT_MAX  = 0xFFFF; /**< Maximum Scan timeout in seconds. */
00028 
00029 public:
00030     /**
00031      * Construct an instance of GapScanningParams.
00032      *
00033      * @param[in] interval
00034      *              The scan interval in milliseconds. Default is
00035      *              GapScanningParams::SCAN_INTERVAL_MIN.
00036      * @param[in] window
00037      *              The scan window in milliseconds. Default is
00038      *              GapScanningParams::SCAN_WINDOW_MAX.
00039      * @param[in] timeout
00040      *              The scan timeout in seconds. Default is 0.
00041      * @param[in] activeScanning
00042      *              Set to True if active-scanning is required. This is used to
00043      *              fetch the scan response from a peer if possible. Default is
00044      *              false.
00045      */
00046     GapScanningParams(uint16_t interval       = SCAN_INTERVAL_MAX,
00047                       uint16_t window         = SCAN_WINDOW_MAX,
00048                       uint16_t timeout        = 0,
00049                       bool     activeScanning = false);
00050 
00051     static const uint16_t UNIT_0_625_MS = 625;  /**< Number of microseconds in 0.625 milliseconds. */
00052     /**
00053      * Convert milliseconds to units of 0.625ms.
00054      *
00055      * @param[in] durationInMillis
00056      *              The number of milliseconds to convert.
00057      *
00058      * @return The value of @p durationInMillis in units of 0.625ms.
00059      */
00060     static uint16_t MSEC_TO_SCAN_DURATION_UNITS(uint32_t durationInMillis) {
00061         return (durationInMillis * 1000) / UNIT_0_625_MS;
00062     }
00063 
00064     /**
00065      * Set the scan interval.
00066      *
00067      * @param[in] newIntervalInMS
00068      *              New scan interval in milliseconds.
00069      *
00070      * @return BLE_ERROR_NONE if the new scan interval was set successfully.
00071      */
00072     ble_error_t setInterval(uint16_t newIntervalInMS);
00073 
00074     /**
00075      * Set the scan window.
00076      *
00077      * @param[in] newWindowInMS
00078      *              New scan window in milliseconds.
00079      *
00080      * @return BLE_ERROR_NONE if the new scan window was set successfully.
00081      */
00082     ble_error_t setWindow(uint16_t newWindowInMS);
00083 
00084     /**
00085      * Set the scan timeout.
00086      *
00087      * @param[in] newTimeout
00088      *              New scan timeout in seconds.
00089      *
00090      * @return BLE_ERROR_NONE if the new scan window was set successfully.
00091      */
00092     ble_error_t setTimeout(uint16_t newTimeout);
00093 
00094     /**
00095      * Set active scanning. This is used to fetch the scan response from a peer
00096      * if possible.
00097      *
00098      * @param[in] activeScanning
00099      *              The new boolean value of active scanning.
00100      */
00101     void setActiveScanning(bool activeScanning);
00102 
00103 public:
00104     /**
00105      * Get the scan interval.
00106      *
00107      * @return the scan interval in units of 0.625ms.
00108      */
00109     uint16_t getInterval(void) const {
00110         return _interval;
00111     }
00112 
00113     /**
00114      * Get the scan window.
00115      *
00116      * @return the scan window in units of 0.625ms.
00117      */
00118     uint16_t getWindow(void) const {
00119         return _window;
00120     }
00121 
00122     /**
00123      * Get the scan timeout.
00124      *
00125      * @return The scan timeout in seconds.
00126      */
00127     uint16_t getTimeout(void) const {
00128         return _timeout;
00129     }
00130 
00131     /**
00132      * Check whether active scanning is set.
00133      *
00134      * @return True if active scanning is set, false otherwise.
00135      */
00136     bool getActiveScanning(void) const {
00137         return _activeScanning;
00138     }
00139 
00140 private:
00141     uint16_t _interval; /**< Scan interval in units of 625us (between 2.5ms and 10.24s). */
00142     uint16_t _window;   /**< Scan window in units of 625us (between 2.5ms and 10.24s). */
00143     uint16_t _timeout;  /**< Scan timeout between 0x0001 and 0xFFFF in seconds; 0x0000 disables timeout. */
00144     bool     _activeScanning; /**< Obtain the peer device's advertising data and (if possible) scanResponse. */
00145 
00146 private:
00147     /* Disallow copy constructor. */
00148     GapScanningParams(const GapScanningParams &);
00149     GapScanningParams& operator =(const GapScanningParams &in);
00150 };
00151 
00152 #endif /* ifndef __GAP_SCANNING_PARAMS_H__ */