GapAdvertisingParams.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_ADVERTISING_PARAMS_H__
00018 #define __GAP_ADVERTISING_PARAMS_H__
00019 
00020 /**
00021  *  This class provides a wrapper for the core advertising parameters,
00022  *  including the advertising type (Connectable Undirected,
00023  *  Non Connectable Undirected and so on), as well as the advertising and
00024  *  timeout intervals.
00025  */
00026 class GapAdvertisingParams {
00027 public:
00028     static const unsigned GAP_ADV_PARAMS_INTERVAL_MIN        = 0x0020;
00029     static const unsigned GAP_ADV_PARAMS_INTERVAL_MIN_NONCON = 0x00A0;
00030     static const unsigned GAP_ADV_PARAMS_INTERVAL_MAX        = 0x4000;
00031     static const unsigned GAP_ADV_PARAMS_TIMEOUT_MAX         = 0x3FFF;
00032 
00033     /*!
00034      * Encapsulates the peripheral advertising modes, which determine how
00035      * the device appears to other central devices in hearing range.
00036      */
00037     enum AdvertisingType_t  {
00038         ADV_CONNECTABLE_UNDIRECTED,     /**< Vol 3, Part C, Section 9.3.4 and Vol 6, Part B, Section 2.3.1.1 */
00039         ADV_CONNECTABLE_DIRECTED,       /**< Vol 3, Part C, Section 9.3.3 and Vol 6, Part B, Section 2.3.1.2 */
00040         ADV_SCANNABLE_UNDIRECTED,       /**< Include support for Scan Response payloads, see Vol 6, Part B, Section 2.3.1.4 */
00041         ADV_NON_CONNECTABLE_UNDIRECTED  /**< Vol 3, Part C, Section 9.3.2 and Vol 6, Part B, Section 2.3.1.3 */
00042     };
00043     typedef enum AdvertisingType_t  AdvertisingType; /* Deprecated type alias. */
00044 
00045 public:
00046     GapAdvertisingParams(AdvertisingType_t  advType  = ADV_CONNECTABLE_UNDIRECTED,
00047                          uint16_t          interval = GAP_ADV_PARAMS_INTERVAL_MIN_NONCON,
00048                          uint16_t          timeout  = 0) : _advType(advType), _interval(interval), _timeout(timeout) {
00049         /* Interval checks. */
00050         if (_advType == ADV_CONNECTABLE_DIRECTED) {
00051             /* Interval must be 0 in directed connectable mode. */
00052             _interval = 0;
00053         } else if (_advType == ADV_NON_CONNECTABLE_UNDIRECTED) {
00054             /* Min interval is slightly larger than in other modes. */
00055             if (_interval < GAP_ADV_PARAMS_INTERVAL_MIN_NONCON) {
00056                 _interval = GAP_ADV_PARAMS_INTERVAL_MIN_NONCON;
00057             }
00058             if (_interval > GAP_ADV_PARAMS_INTERVAL_MAX) {
00059                 _interval = GAP_ADV_PARAMS_INTERVAL_MAX;
00060             }
00061         } else {
00062             /* Stay within interval limits. */
00063             if (_interval < GAP_ADV_PARAMS_INTERVAL_MIN) {
00064                 _interval = GAP_ADV_PARAMS_INTERVAL_MIN;
00065             }
00066             if (_interval > GAP_ADV_PARAMS_INTERVAL_MAX) {
00067                 _interval = GAP_ADV_PARAMS_INTERVAL_MAX;
00068             }
00069         }
00070 
00071         /* Timeout checks. */
00072         if (timeout) {
00073             /* Stay within timeout limits. */
00074             if (_timeout > GAP_ADV_PARAMS_TIMEOUT_MAX) {
00075                 _timeout = GAP_ADV_PARAMS_TIMEOUT_MAX;
00076             }
00077         }
00078     }
00079 
00080     static const uint16_t UNIT_0_625_MS = 625;  /**< Number of microseconds in 0.625 milliseconds. */
00081     static uint16_t MSEC_TO_ADVERTISEMENT_DURATION_UNITS(uint32_t durationInMillis) {
00082         return (durationInMillis * 1000) / UNIT_0_625_MS;
00083     }
00084     static uint16_t ADVERTISEMENT_DURATION_UNITS_TO_MS(uint16_t gapUnits) {
00085         return (gapUnits * UNIT_0_625_MS) / 1000;
00086     }
00087 
00088     AdvertisingType_t  getAdvertisingType(void) const {
00089         return _advType;
00090     }
00091 
00092     /**
00093      * @return the advertisement interval (in milliseconds).
00094      */
00095     uint16_t getInterval (void) const {
00096         return ADVERTISEMENT_DURATION_UNITS_TO_MS(_interval);
00097     }
00098 
00099     /**
00100      * @return the advertisement interval in advertisement duration units (0.625ms units).
00101      */
00102     uint16_t getIntervalInADVUnits (void) const {
00103         return _interval;
00104     }
00105 
00106     uint16_t getTimeout(void) const {
00107         return _timeout;
00108     }
00109 
00110     void setAdvertisingType(AdvertisingType_t  newAdvType) {_advType = newAdvType;  }
00111     void setInterval(uint16_t newInterval)                {_interval = MSEC_TO_ADVERTISEMENT_DURATION_UNITS(newInterval);}
00112     void setTimeout(uint16_t newTimeout)                  {_timeout = newTimeout;  }
00113 
00114 private:
00115     AdvertisingType_t  _advType;
00116     uint16_t          _interval; /* In ADV duration units (i.e. 0.625ms). */
00117     uint16_t          _timeout;  /* In seconds. */
00118 };
00119 
00120 #endif // ifndef __GAP_ADVERTISING_PARAMS_H__