mirror of https://github.com/ARMmbed/mbed-os.git
448 lines
15 KiB
C++
448 lines
15 KiB
C++
/* 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__ */
|