Mbed OS Reference | AdvertisingDataSimpleBuilder.h Source File

 /* mbed Microcontroller Library
  * Copyright (c) 2006-2020 ARM Limited
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * 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 BLE_GAP_SIMPLEADVERTISINGDATABUILDER_H
 #define BLE_GAP_SIMPLEADVERTISINGDATABUILDER_H
 
 #include "platform/Span.h"
 
 #include "ble/common/UUID.h"
 #include "ble/gap/AdvertisingDataBuilder.h"
 
 namespace ble {
 
 /**
  * @addtogroup ble
  * @{
  * @addtogroup gap
  * @{
  */
 
 /**
  * Build advertising data.
  *
  * It is a simplified version of AdvertisingDataBuilder that can generate
  * advertising data "inline".
  *
  * It differs from AdvertisingDataBuilder on the following points:
  *   - The buffer used to build the advertising data is embedded in the object.
  *   - If insertion fails, an assertion is raised. Outside of debug mode, if an
  *   insertion fails, the buffer is not modified.
  *   - The API is fluent.
  *   - It hides advanced functions.
  *
  * @code
     void setupAdvertisingData(ble::Gap& gap)
     {
         using namespace ble;
         gap.setAdvertisingPayload(
             LEGACY_ADVERTISING_HANDLE,
             AdvertisingDataSimpleBuilder<LEGACY_ADVERTISING_MAX_SIZE>()
                 .setFlags()
                 .setName("My device", true)
                 .setAppearance(adv_data_appearance_t::GENERIC_HEART_RATE_SENSOR)
                 .setLocalService(ATT_UUID_HEART_RATE_SERVICE)
                 .getAdvertisingData()
         );
     }
  * @endcode
  */
 template<size_t DataSize>
 class AdvertisingDataSimpleBuilder {
 public:
     /**
      * Construct a AdvertisingDataSimpleBuilder
      */
     AdvertisingDataSimpleBuilder() : _buffer(), _builder(_buffer)
     {
     }
 
     /**
      * Add device appearance in the advertising payload.
      *
      * @param[in] appearance The appearance to advertise.
      *
      * @return A reference to this object.
      *
      * @note If the field is already present in the payload, it is replaced.
      */
     AdvertisingDataSimpleBuilder &setAppearance(adv_data_appearance_t appearance)
     {
         ble_error_t res = _builder.setAppearance(appearance);
         MBED_ASSERT(res == BLE_ERROR_NONE);
         return *this;
     }
 
     /**
      * Add BLE flags in the advertising payload.
      *
      * @param[in] flags Bitfield describing the capability of the device. See
      * allowed flags in Flags_t.
      *
      * @return A reference to this object.
      *
      * @note If the field is already present in the payload, it is replaced.
      */
     AdvertisingDataSimpleBuilder &setFlags(
         adv_data_flags_t flags = adv_data_flags_t::default_flags
     )
     {
         ble_error_t res = _builder.setFlags(flags);
         MBED_ASSERT(res == BLE_ERROR_NONE);
         return *this;
     }
 
     /**
      * Add the advertising TX in the advertising payload.
      *
      * @param[in] txPower Transmission power level in dB.
      *
      * @return A reference to this object.
      *
      * @note If the field is already present in the payload, it is replaced.
      */
     AdvertisingDataSimpleBuilder &setTxPowerAdvertised(advertising_power_t txPower)
     {
         ble_error_t res = _builder.setTxPowerAdvertised(txPower);
         MBED_ASSERT(res == BLE_ERROR_NONE);
         return *this;
     }
 
     /**
      * Add device name to the advertising payload.
      *
      * @note Data size for individual types cannot exceed 255 bytes.
      *
      * @param[in] name Null terminated string containing the name.
      * @param[in] complete Complete local name if true, otherwise
      *
      * @return A reference to this object.
      *
      * @note If the field is already present in the payload, it is replaced.
      */
     AdvertisingDataSimpleBuilder &setName(const char *name, bool complete = true)
     {
         ble_error_t res = _builder.setName(name, complete);
         MBED_ASSERT(res == BLE_ERROR_NONE);
         return *this;
     }
 
     /**
      * Add manufacturer specific data to the advertising payload.
      *
      * @note Data size for individual types cannot exceed 255 bytes.
      *
      * @param[in] data New data to be added.
      *
      * @return a reference to this object.
      */
     AdvertisingDataSimpleBuilder &setManufacturerSpecificData(mbed::Span<const uint8_t> data)
     {
         ble_error_t res = _builder.setManufacturerSpecificData(data);
         MBED_ASSERT(res == BLE_ERROR_NONE);
         return *this;
     }
 
     /**
      * Add advertising interval to the payload. This field can only carry 2 bytes.
      *
      * @param interval Interval to advertise. Cannot be larger than 0xFFFF.
      *
      * @return a reference to this object.
      */
     AdvertisingDataSimpleBuilder &setAdvertisingInterval(adv_interval_t interval)
     {
         ble_error_t res = _builder.setAdvertisingInterval(interval);
         MBED_ASSERT(res == BLE_ERROR_NONE);
         return *this;
     }
 
     /**
      * Add connection interval preferences to the payload
      *
      * @param min Minimum connection interval to advertise.
      * @param max Maximum connection interval to advertise.
      *
      * @return a reference to this object.
      */
     AdvertisingDataSimpleBuilder &setConnectionIntervalPreference(
         conn_interval_t min,
         conn_interval_t max
     )
     {
         ble_error_t res = _builder.setConnectionIntervalPreference(min, max);
         MBED_ASSERT(res == BLE_ERROR_NONE);
         return *this;
     }
 
     /**
      * Add service data to the advertising payload.
      *
      * @note Data size for individual types cannot exceed 255 bytes.
      *
      * @param[in] service UUID of the service.
      * @param[in] data New data to be added.
      *
      * @return A reference to this object.
      */
     AdvertisingDataSimpleBuilder &setServiceData(const UUID& service, mbed::Span<const uint8_t> data)
     {
         ble_error_t res = _builder.setServiceData(service, data);
         MBED_ASSERT(res == BLE_ERROR_NONE);
         return *this;
     }
 
     /**
      * Add local service ID to the advertising payload. If the data can't fit,
      * no modification will take place.
      *
      * @note Data size for individual types cannot exceed 255 bytes.
      *
      * @param[in] data New data to be added.
      * @param[in] complete True if this is a complete list.
      *
      * @return A reference to this object.
      */
     AdvertisingDataSimpleBuilder &setLocalService(
         const UUID& data,
         bool complete = true
     )
     {
         ble_error_t res = _builder.setLocalServiceList(
                 mbed::make_Span(&data, 1), complete
             );
         MBED_ASSERT(res == BLE_ERROR_NONE);
         return *this;
     }
 
 
     /**
      * Add local service IDs to the advertising payload. If the data can't fit,
      * no modification will take place.
      *
      * @note Data size for individual types cannot exceed 255 bytes.
      *
      * @param[in] data New data to be added.
      * @param[in] complete True if this is a complete list.
      *
      * @return A reference to this object.
      */
     AdvertisingDataSimpleBuilder &setLocalServiceList(
         mbed::Span<const UUID> data,
         bool complete = true
     )
     {
         ble_error_t res = _builder.setLocalServiceList(data, complete);
         MBED_ASSERT(res == BLE_ERROR_NONE);
         return *this;
     }
 
     /**
      * Add a UUID of a solicited service.
      *
      * @note Data size for individual types cannot exceed 255 bytes.
      *
      * @param[in] data List of 128 or 16 bit service UUIDs.
      *
      * @return A reference to this object.
      */
     AdvertisingDataSimpleBuilder &setRequestedService(const UUID& data)
     {
         ble_error_t res = _builder.setRequestedServiceList(mbed::make_Span(&data, 1));
         MBED_ASSERT(res == BLE_ERROR_NONE);
         return *this;
     }
 
     /**
      * Add a list of UUIDs of solicited services.
      *
      * @note Data size for individual types cannot exceed 255 bytes.
      *
      * @param[in] data List of 128 or 16 bit service UUIDs.
      *
      * @return A reference to this object.
      */
     AdvertisingDataSimpleBuilder &setRequestedServiceList(mbed::Span<const UUID> data)
     {
         ble_error_t res = _builder.setRequestedServiceList(data);
         MBED_ASSERT(res == BLE_ERROR_NONE);
         return *this;
     }
 
     /**
      * Add a new field into the payload. The operation fails if type is already present.
      *
      * @note Data size for individual types cannot exceed 255 bytes.
      *
      * @param[in] advDataType The type of the field to add.
      * @param[in] fieldData Span of data to add.
      *
      * @return A reference to this object.
      */
     AdvertisingDataSimpleBuilder& addData(
         adv_data_type_t advDataType,
         mbed::Span<const uint8_t> fieldData
     )
     {
         ble_error_t res = _builder.addData(advDataType, fieldData);
         MBED_ASSERT(res == BLE_ERROR_NONE);
         return *this;
     }
 
     /**
      * Get the subspan of the buffer containing valid data.
      *
      * @return A Span containing the payload.
      */
     mbed::Span<const uint8_t> getAdvertisingData() const
     {
         return _builder.getAdvertisingData();
     }
 
 private:
     uint8_t _buffer[DataSize];
     AdvertisingDataBuilder _builder;
 };
 
 /**
  * @}
  * @}
  */
 
 } // namespace ble
 
 
 #endif //BLE_GAP_SIMPLEADVERTISINGDATABUILDER_H
Important Information for this Arm website
