File content as of revision 0:b74591d5ab33:

/* mbed Microcontroller Library
 * Copyright (c) 2006-2013 ARM Limited
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
*/

#ifndef MBED_GAP_ADVERTISING_PARAMS_H__
#define MBED_GAP_ADVERTISING_PARAMS_H__

/**
 * @addtogroup ble
 * @{
 * @addtogroup gap
 * @{
 */

/**
 * Parameters defining the advertising process.
 *
 * Advertising parameters are a triplet of three value:
 *   - The Advertising mode modeled after AdvertisingType_t. It defines
 *     if the device is connectable and scannable. This value can be set at
 *     construction time, updated with setAdvertisingType() and queried by
 *     getAdvertisingType().
 *   - Time interval between advertisement. It can be set at construction time,
 *     updated by setInterval() and obtained from getInterval().
 *   - Duration of the advertising process. As others, it can be set at
 *     construction time, modified by setTimeout() and retrieved by getTimeout().
 */
class GapAdvertisingParams {
public:

    /**
     * Minimum Advertising interval for connectable undirected and connectable
     * directed events in 625us units.
     *
     * @note Equal to 20 ms.
     */
    static const unsigned GAP_ADV_PARAMS_INTERVAL_MIN = 0x0020;

    /**
     * Minimum Advertising interval for scannable and nonconnectable
     * undirected events in 625us units.
     *
     * @note Equal to 100ms.
     */
    static const unsigned GAP_ADV_PARAMS_INTERVAL_MIN_NONCON = 0x00A0;

    /**
     * Maximum Advertising interval in 625us units.
     *
     * @note Equal to 10.24s.
     */
    static const unsigned GAP_ADV_PARAMS_INTERVAL_MAX = 0x4000;

    /**
     * Maximum advertising timeout allowed; in seconds.
     */
    static const unsigned GAP_ADV_PARAMS_TIMEOUT_MAX = 0x3FFF;

    /**
     * Encapsulates the peripheral advertising modes.
     *
     * It determine how the device appears to other scanner and peripheral
     * devices in the scanning range.
     */
    enum AdvertisingType_t {
        /**
         * Device is connectable, scannable and doesn't expect connection from a
         * specific peer.
         *
         * @see Vol 3, Part C, Section 9.3.4 and Vol 6, Part B, Section 2.3.1.1.
         */
        ADV_CONNECTABLE_UNDIRECTED,

        /**
         * Device is connectable and expects connection from a specific peer.
         *
         * @see Vol 3, Part C, Section 9.3.3 and Vol 6, Part B, Section 2.3.1.2.
         */
        ADV_CONNECTABLE_DIRECTED,

        /**
         * Device is scannable but not connectable.
         *
         * @see Vol 6, Part B, Section 2.3.1.4.
         */
        ADV_SCANNABLE_UNDIRECTED,

        /**
         * Device is not connectable and not scannable.
         *
         * @see Vol 3, Part C, Section 9.3.2 and Vol 6, Part B, Section 2.3.1.3.
         */
        ADV_NON_CONNECTABLE_UNDIRECTED
    };

    /**
     * Alias for GapAdvertisingParams::AdvertisingType_t.
     *
     * @deprecated  Future releases will drop this type alias.
     */
    typedef enum AdvertisingType_t AdvertisingType;

public:
    /**
     * Construct an instance of GapAdvertisingParams.
     *
     * @param[in] advType Type of advertising.
     * @param[in] interval Time interval between two advertisement in units of
     * 0.625ms.
     * @param[in] timeout Duration in seconds of the advertising process. A
     * value of 0 indicate that there is no timeout of the advertising process.
     *
     * @note If value in input are out of range, they will be normalized.
     */
    GapAdvertisingParams(
        AdvertisingType_t advType  = ADV_CONNECTABLE_UNDIRECTED,
        uint16_t interval = GAP_ADV_PARAMS_INTERVAL_MIN_NONCON,
        uint16_t timeout = 0
    ) :
        _advType(advType),
        _interval(interval),
        _timeout(timeout)
    {
        /* Interval checks. */
        if (_advType == ADV_CONNECTABLE_DIRECTED) {
            /* Interval must be 0 in directed connectable mode. */
            _interval = 0;
        } else if (_advType == ADV_NON_CONNECTABLE_UNDIRECTED) {
            /* Min interval is slightly larger than in other modes. */
            if (_interval < GAP_ADV_PARAMS_INTERVAL_MIN_NONCON) {
                _interval = GAP_ADV_PARAMS_INTERVAL_MIN_NONCON;
            }
            if (_interval > GAP_ADV_PARAMS_INTERVAL_MAX) {
                _interval = GAP_ADV_PARAMS_INTERVAL_MAX;
            }
        } else {
            /* Stay within interval limits. */
            if (_interval < GAP_ADV_PARAMS_INTERVAL_MIN) {
                _interval = GAP_ADV_PARAMS_INTERVAL_MIN;
            }
            if (_interval > GAP_ADV_PARAMS_INTERVAL_MAX) {
                _interval = GAP_ADV_PARAMS_INTERVAL_MAX;
            }
        }

        /* Timeout checks. */
        if (timeout) {
            /* Stay within timeout limits. */
            if (_timeout > GAP_ADV_PARAMS_TIMEOUT_MAX) {
                _timeout = GAP_ADV_PARAMS_TIMEOUT_MAX;
            }
        }
    }

    /**
     * Number of microseconds in 0.625 milliseconds.
     */
    static const uint16_t UNIT_0_625_MS = 625;

    /**
     * Convert milliseconds to units of 0.625ms.
     *
     * @param[in] durationInMillis Number of milliseconds to convert.
     *
     * @return The value of @p durationInMillis in units of 0.625ms.
     */
    static uint16_t MSEC_TO_ADVERTISEMENT_DURATION_UNITS(uint32_t durationInMillis)
    {
        return (durationInMillis * 1000) / UNIT_0_625_MS;
    }

    /**
     * Convert units of 0.625ms to milliseconds.
     *
     * @param[in] gapUnits The number of units of 0.625ms to convert.
     *
     * @return The value of @p gapUnits in milliseconds.
     */
    static uint16_t ADVERTISEMENT_DURATION_UNITS_TO_MS(uint16_t gapUnits)
    {
        return (gapUnits * UNIT_0_625_MS) / 1000;
    }

    /**
     * Get the advertising type.
     *
     * @return The advertising type.
     */
    AdvertisingType_t getAdvertisingType(void) const
    {
        return _advType;
    }

    /**
     * Get the advertising interval in milliseconds.
     *
     * @return The advertisement interval (in milliseconds).
     */
    uint16_t getInterval(void) const
    {
        return ADVERTISEMENT_DURATION_UNITS_TO_MS(_interval);
    }

    /**
     * Get the advertisement interval in units of 0.625ms.
     *
     * @return The advertisement interval in advertisement duration units
     * (0.625ms units).
     */
    uint16_t getIntervalInADVUnits(void) const
    {
        return _interval;
    }

    /**
     * Get the advertising timeout.
     *
     * @return The advertising timeout (in seconds).
     */
    uint16_t getTimeout(void) const
    {
        return _timeout;
    }

    /**
     * Update the advertising type.
     *
     * @param[in] newAdvType The new advertising type.
     */
    void setAdvertisingType(AdvertisingType_t newAdvType)
    {
        _advType = newAdvType;
    }

    /**
     * Update the advertising interval in milliseconds.
     *
     * @param[in] newInterval The new advertising interval in milliseconds.
     */
    void setInterval(uint16_t newInterval)
    {
        _interval = MSEC_TO_ADVERTISEMENT_DURATION_UNITS(newInterval);
    }

    /**
     * Update the advertising timeout.
     *
     * @param[in] newTimeout The new advertising timeout (in seconds).
     *
     * @note 0 is a special value meaning the advertising process never ends.
     */
    void setTimeout(uint16_t newTimeout)
    {
        _timeout = newTimeout;
    }

private:
    /**
     * The advertising type.
     */
    AdvertisingType_t _advType;

    /**
     * The advertising interval in ADV duration units (in other words, 0.625ms).
     */
    uint16_t _interval;

    /**
     * The advertising timeout in seconds.
     */
    uint16_t _timeout;
};

/**
 * @}
 * @}
 */

#endif /* ifndef MBED_GAP_ADVERTISING_PARAMS_H__ */