Mbed OS Reference | AdvertisingDataBuilder.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 MBED_GAP_ADVERTISING_DATA_H__
 #define MBED_GAP_ADVERTISING_DATA_H__
 
 #include <cstdint>
 #include <cstring>
 #include <cstdlib>
 #include "platform/NonCopyable.h"
 
 #include "ble/common/UUID.h"
 #include "ble/common/BLETypes.h"
 #include "ble/common/blecommon.h"
 #include "ble/gap/AdvertisingDataTypes.h"
 #include "ble/gap/Types.h"
 
 namespace ble {
 
 /**
  * @addtogroup ble
  * @{
  * @addtogroup gap
  * @{
  */
 
 /**
  * Build advertising data.
  *
  * The builder accepts an array of bytes in input and returns the result of the
  * construction with getAdvertisingData().
  */
 class AdvertisingDataBuilder {
 public:
     /** Advertising data needs a user-provided buffer to store the data.
      *
      * @param buffer Buffer used to store the data.
      * @note Use Gap::getMaxAdvertisingDataLength() to find out how much can be accepted.
      */
     AdvertisingDataBuilder(mbed::Span<uint8_t> buffer);
 
     /** Advertising data needs a user provided buffer to store the data.
      *
      * @param buffer Pointer to buffer to be used for storing advertising data.
      * @param buffer_size Size of the buffer.
      * @note Use Gap::getMaxAdvertisingDataLength() to find out how much can be accepted.
      */
     AdvertisingDataBuilder(uint8_t *buffer, size_t buffer_size);
 
     /**
      * Get the subspan of the buffer containing valid data.
      *
      * @return A Span containing the payload.
      */
     mbed::Span<const uint8_t> getAdvertisingData() const;
 
     /**
      * Add a new field into the payload. Returns an error 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.
      *
      * @retval BLE_ERROR_NONE on success.
      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
      * @retval BLE_ERROR_OPERATION_NOT_PERMITTED if data type already present.
      * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
      */
     ble_error_t addData(
         adv_data_type_t advDataType,
         mbed::Span<const uint8_t> fieldData
     );
 
     /**
      * Replace a new field into the payload. Will fail if type is not 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.
      *
      * @retval BLE_ERROR_NONE on success.
      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
      * @retval BLE_ERROR_NOT_FOUND if data type not present.
      * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
      */
     ble_error_t replaceData(
         adv_data_type_t advDataType,
         mbed::Span<const uint8_t> fieldData
     );
 
     /**
      * Append data to an existing field in the payload. Will fail if type is not 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.
      *
      * @retval BLE_ERROR_NONE on success.
      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
      * @retval BLE_ERROR_NOT_FOUND if data type not present.
      * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
      */
     ble_error_t appendData(
         adv_data_type_t advDataType,
         mbed::Span<const uint8_t> fieldData
     );
 
     /**
      * Remove existing date of given type. Will return an error if type is not present.
      *
      * @param[in] advDataType The type of the field to remove.
      *
      * @return BLE_ERROR_NONE returned on success, BLE_ERROR_INVALID_PARAM if field doesn't exist
      */
     ble_error_t removeData(adv_data_type_t advDataType);
 
     /**
      * Adds a new field into the payload. If the supplied advertising data type is
      * already present in the advertising payload, then the value is replaced.
      *
      * @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.
      *
      * @retval BLE_ERROR_NONE on success.
      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
      * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
      */
     ble_error_t addOrReplaceData(
         adv_data_type_t advDataType,
         mbed::Span<const uint8_t> fieldData
     );
 
     /**
      * Adds a new field into the payload. If the supplied advertising data type is
      * already present in the advertising payload, then the value is replaced.
      *
      * @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.
      *
      * @retval BLE_ERROR_NONE on success.
      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
      * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
      */
     ble_error_t addOrAppendData(
         adv_data_type_t advDataType,
         mbed::Span<const uint8_t> fieldData
     );
 
     /**
      * Clears the advertising data payload.
      *
      * @post getPayloadLen() returns 0.
      */
     void clear();
 
     /**
      * Add device appearance in the advertising payload.
      *
      * @param[in] appearance The appearance to advertise.
      *
      * @retval BLE_ERROR_NONE on success.
      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
      *
      * @note This call is equivalent to calling addOrReplaceData() with
      * adv_data_type_t::APPEARANCE as the field type.
      */
     ble_error_t setAppearance(adv_data_appearance_t appearance);
 
     /**
      * Add BLE flags in the advertising payload.
      *
      * @param[in] flags Bitfield describing the capability of the device. See
      * allowed flags in Flags_t.
      *
      * @retval BLE_ERROR_NONE on success.
      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
      *
      * @note This call is equivalent to calling addOrReplaceData() with
      * adv_data_type_t::FLAGS as the field type.
      */
     ble_error_t setFlags(
         adv_data_flags_t flags = adv_data_flags_t::default_flags
     );
 
     /**
      * Add the advertising TX in the advertising payload.
      *
      * @param[in] txPower Transmission power level in dB.
      *
      * @retval BLE_ERROR_NONE on success.
      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
      *
      * @note This call is equivalent to calling addOrReplaceData() with
      * adv_data_type_t::TX_POWER_LEVEL as the field type.
      */
     ble_error_t setTxPowerAdvertised(advertising_power_t txPower);
 
     /**
      * 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
      *
      * @retval BLE_ERROR_NONE on success.
      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
      * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
      */
     ble_error_t setName(const char *name, bool complete = true);
 
     /**
      * 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.
      *
      * @retval BLE_ERROR_NONE on success.
      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
      * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual
      *                                 data field or the data is too small (must contain
      *                                 2 bytes of manufacturer ID)
      */
     ble_error_t setManufacturerSpecificData(mbed::Span<const uint8_t> data);
 
     /**
      * Add advertising interval to the payload. This field can only carry 2 bytes.
      *
      * @param interval Interval to advertise. Cannot be larger than 0xFFFF.
 
      * @retval BLE_ERROR_NONE on success.
      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
      * @retval BLE_ERROR_INVALID_PARAM if interval value outside of valid range.
      */
     ble_error_t setAdvertisingInterval(adv_interval_t interval);
 
     /**
      * Add connection interval preferences to the payload
      *
      * @param min Minimum connection interval to advertise.
      * @param max Maximum connection interval to advertise.
 
      * @retval BLE_ERROR_NONE on success.
      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
      */
     ble_error_t setConnectionIntervalPreference(
         conn_interval_t min,
         conn_interval_t max
     );
 
     /**
      * Add service data 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.
      *
      * @retval BLE_ERROR_NONE on success.
      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
      * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
      */
     ble_error_t setServiceData(UUID service, mbed::Span<const uint8_t> data);
 
     /**
      * 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.
      *
      * @retval BLE_ERROR_NONE on success.
      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
      * @retval BLE_ERROR_INVALID_PARAM if number of UUIDs of any one type is too high.
      */
     ble_error_t setLocalServiceList(
         mbed::Span<const UUID> data,
         bool complete = true
     );
 
     /**
      * 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.
      *
      * @retval BLE_ERROR_NONE on success.
      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
      * @retval BLE_ERROR_INVALID_PARAM if number of UUIDs of any one type is too high.
      */
     ble_error_t setRequestedServiceList(mbed::Span<const UUID> data);
 
     /**
      * Return a span of data containing the the type of data requested.
      *
      * @param[out] data Span used to return the requested data.
      * @param[in] advDataType Data type to return.
      *
      * @return BLE_ERROR_NONE if data was found and BLE_ERROR_NOT_FOUND if not.
      */
     ble_error_t getData(
         mbed::Span<const uint8_t> &data,
         adv_data_type_t advDataType
     );
 
 private:
     /**
     * Search advertisement data for a specific field.
     *
     * @param[in] type The type of the field to find.
     *
     * @return A pointer to the first element in the field if found. The first
     * element being the length of the field followed by the value of the field.
     * NULL if the field is not present in the payload.
     */
     uint8_t *findField(adv_data_type_t type);
 
     /**
      * Get field size (includes type and size bytes)
      *
      * @param type The field type.
      *
      * @return Size of the whole field including type and size bytes.
      */
     uint8_t getFieldSize(adv_data_type_t type);
 
     /**
      * Append advertising data based on the specified type.
      *
      * @note Data size for individual types cannot exceed 255 bytes.
      *
      * @param[in] advDataType Type of the new data.
      * @param[in] fieldData Span of data to add.
      *
      * @retval BLE_ERROR_NONE on success.
      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
      */
     ble_error_t addField(
         adv_data_type_t advDataType,
         mbed::Span<const uint8_t> fieldData
     );
 
     /**
      * Append data to a field in the advertising payload.
      *
      * @note Data size for individual types cannot exceed 255 bytes.
      *
      * @param[in] fieldData Span of data to add.
      * @param[in] field Pointer to the field in the advertising buffer.
      *
      * @return BLE_ERROR_NONE on success.
      */
     ble_error_t appendToField(
         mbed::Span<const uint8_t> fieldData,
         uint8_t *field
     );
 
     /**
      * Update in place the value of a field in the advertising payload.
      *
      * @note Data size for individual types cannot exceed 255 bytes.
      *
      * @param[in] advDataType Type of the new data.
      * @param[in] fieldData Span of data to add.
      * @param[in] field Pointer to the field of type @p advDataType in the
      * advertising buffer.
      *
      * @retval BLE_ERROR_NONE on success.
      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
      */
     ble_error_t replaceField(
         adv_data_type_t advDataType,
         mbed::Span<const uint8_t> fieldData,
         uint8_t *field
     );
 
     /**
      * Remove the field.
      *
      * @param[in] field Pointer to the field in the advertising buffer.
      *
      * @return BLE_ERROR_NONE on success.
      */
     ble_error_t removeField(uint8_t *field);
 
     /**
      * Add a list of UUIDs to given types.
      *
      * @note Data size for individual types cannot exceed 255 bytes.
      *
      * @param[in] data List of 128 or 16 bit service UUIDs.
      * @param[in] shortType Type of field to add the short UUIDs to.
      * @param[in] longType Type of field to add the long UUIDs to.
      *
      * @retval BLE_ERROR_NONE on success.
      * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
      * @retval BLE_ERROR_INVALID_PARAM if number of UUIDs of any one type is too high.
      */
     ble_error_t setUUIDData(
         mbed::Span<const UUID> data,
         adv_data_type_t shortType,
         adv_data_type_t longType
     );
 
 private:
     /** The memory backing the the data provided by the user. */
     mbed::Span<uint8_t> _buffer;
 
     /** Length of the data added to the advertising buffer. */
     uint8_t _payload_length;
 };
 
 /**
  * @}
  * @}
  */
 
 } // namespace ble
 
 #endif /* ifndef MBED_GAP_ADVERTISING_DATA_H__ */
Important Information for this Arm website
