forked from h2zero/esp-nimble-cpp
h2zero
e00dd88add
When sending an array of data with a length value the wrong overload/template was being used and the length value was being interpreted as the connection handle. This updates the template to disable it when an array is passed and will now also report the error.
258 lines
11 KiB
C++
258 lines
11 KiB
C++
/*
|
|
* Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
|
|
* esp-nimble-cpp, NimBLE-Arduino contributors.
|
|
*
|
|
* 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 NIMBLE_CPP_CHARACTERISTIC_H_
|
|
#define NIMBLE_CPP_CHARACTERISTIC_H_
|
|
#include "nimconfig.h"
|
|
#if defined(CONFIG_BT_ENABLED) && defined(CONFIG_BT_NIMBLE_ROLE_PERIPHERAL)
|
|
|
|
class NimBLECharacteristicCallbacks;
|
|
class NimBLEService;
|
|
class NimBLECharacteristic;
|
|
class NimBLEDescriptor;
|
|
class NimBLE2904;
|
|
|
|
# include "NimBLELocalValueAttribute.h"
|
|
|
|
# include <string>
|
|
# include <vector>
|
|
|
|
/**
|
|
* @brief The model of a BLE Characteristic.
|
|
*
|
|
* A BLE Characteristic is an identified value container that manages a value. It is exposed by a BLE service and
|
|
* can be read and written to by a BLE client.
|
|
*/
|
|
class NimBLECharacteristic : public NimBLELocalValueAttribute {
|
|
public:
|
|
NimBLECharacteristic(const char* uuid,
|
|
uint16_t properties = NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::WRITE,
|
|
uint16_t maxLen = BLE_ATT_ATTR_MAX_LEN,
|
|
NimBLEService* pService = nullptr);
|
|
NimBLECharacteristic(const NimBLEUUID& uuid,
|
|
uint16_t properties = NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::WRITE,
|
|
uint16_t maxLen = BLE_ATT_ATTR_MAX_LEN,
|
|
NimBLEService* pService = nullptr);
|
|
|
|
~NimBLECharacteristic();
|
|
|
|
std::string toString() const;
|
|
void addDescriptor(NimBLEDescriptor* pDescriptor);
|
|
void removeDescriptor(NimBLEDescriptor* pDescriptor, bool deleteDsc = false);
|
|
uint16_t getProperties() const;
|
|
void setCallbacks(NimBLECharacteristicCallbacks* pCallbacks);
|
|
bool indicate(uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const;
|
|
bool indicate(const uint8_t* value, size_t length, uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const;
|
|
bool notify(uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const;
|
|
bool notify(const uint8_t* value, size_t length, uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const;
|
|
|
|
NimBLEDescriptor* createDescriptor(const char* uuid,
|
|
uint32_t properties = NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::WRITE,
|
|
uint16_t maxLen = BLE_ATT_ATTR_MAX_LEN);
|
|
NimBLEDescriptor* createDescriptor(const NimBLEUUID& uuid,
|
|
uint32_t properties = NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::WRITE,
|
|
uint16_t maxLen = BLE_ATT_ATTR_MAX_LEN);
|
|
NimBLE2904* create2904();
|
|
NimBLEDescriptor* getDescriptorByUUID(const char* uuid) const;
|
|
NimBLEDescriptor* getDescriptorByUUID(const NimBLEUUID& uuid) const;
|
|
NimBLEDescriptor* getDescriptorByHandle(uint16_t handle) const;
|
|
NimBLEService* getService() const;
|
|
|
|
NimBLECharacteristicCallbacks* getCallbacks() const;
|
|
|
|
/*********************** Template Functions ************************/
|
|
|
|
# if __cplusplus < 201703L
|
|
/**
|
|
* @brief Template to send a notification with a value from a struct or array.
|
|
* @param [in] v The value to send.
|
|
* @param [in] connHandle Optional, a connection handle to send the notification to.
|
|
* @details <type\> size must be evaluatable by `sizeof()`.
|
|
*/
|
|
template <typename T>
|
|
# ifdef _DOXYGEN_
|
|
bool
|
|
# else
|
|
typename std::enable_if<!std::is_pointer<T>::value && !std::is_array<T>::value && !Has_c_str_length<T>::value &&
|
|
!Has_data_size<T>::value,
|
|
bool>::type
|
|
# endif
|
|
notify(const T& v, uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const {
|
|
return notify(reinterpret_cast<const uint8_t*>(&v), sizeof(T), connHandle);
|
|
}
|
|
|
|
/**
|
|
* @brief Template to send a notification with a value from a class that has a c_str() and length() method.
|
|
* @param [in] s The value to send.
|
|
* @param [in] connHandle Optional, a connection handle to send the notification to.
|
|
*/
|
|
template <typename T>
|
|
# ifdef _DOXYGEN_
|
|
bool
|
|
# else
|
|
typename std::enable_if<Has_c_str_length<T>::value && !Has_data_size<T>::value, bool>::type
|
|
# endif
|
|
notify(const T& s, uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const {
|
|
return notify(reinterpret_cast<const uint8_t*>(s.c_str()), s.length(), connHandle);
|
|
}
|
|
|
|
/**
|
|
* @brief Template to send a notification with a value from a class that has a data() and size() method.
|
|
* @param [in] v The value to send.
|
|
* @param [in] connHandle Optional, a connection handle to send the notification to.
|
|
*/
|
|
template <typename T>
|
|
# ifdef _DOXYGEN_
|
|
bool
|
|
# else
|
|
typename std::enable_if<Has_data_size<T>::value, bool>::type
|
|
# endif
|
|
notify(const T& v, uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const {
|
|
return notify(reinterpret_cast<const uint8_t*>(v.data()), v.size(), connHandle);
|
|
}
|
|
|
|
/**
|
|
* @brief Template to send an indication with a value from a struct or array.
|
|
* @param [in] v The value to send.
|
|
* @param [in] connHandle Optional, a connection handle to send the notification to.
|
|
* @details <type\> size must be evaluatable by `sizeof()`.
|
|
*/
|
|
template <typename T>
|
|
# ifdef _DOXYGEN_
|
|
bool
|
|
# else
|
|
typename std::enable_if<!std::is_pointer<T>::value && !std::is_array<T>::value && !Has_c_str_length<T>::value &&
|
|
!Has_data_size<T>::value,
|
|
bool>::type
|
|
# endif
|
|
indicate(const T& v, uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const {
|
|
return indicate(reinterpret_cast<const uint8_t*>(&v), sizeof(T), connHandle);
|
|
}
|
|
|
|
/**
|
|
* @brief Template to send a indication with a value from a class that has a c_str() and length() method.
|
|
* @param [in] s The value to send.
|
|
* @param [in] connHandle Optional, a connection handle to send the notification to.
|
|
*/
|
|
template <typename T>
|
|
# ifdef _DOXYGEN_
|
|
bool
|
|
# else
|
|
typename std::enable_if<Has_c_str_length<T>::value && !Has_data_size<T>::value, bool>::type
|
|
# endif
|
|
indicate(const T& s, uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const {
|
|
return indicate(reinterpret_cast<const uint8_t*>(s.c_str()), s.length(), connHandle);
|
|
}
|
|
|
|
/**
|
|
* @brief Template to send a indication with a value from a class that has a data() and size() method.
|
|
* @param [in] v The value to send.
|
|
* @param [in] connHandle Optional, a connection handle to send the notification to.
|
|
*/
|
|
template <typename T>
|
|
# ifdef _DOXYGEN_
|
|
bool
|
|
# else
|
|
typename std::enable_if<Has_data_size<T>::value, bool>::type
|
|
# endif
|
|
indicate(const T& v, uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const {
|
|
return indicate(reinterpret_cast<const uint8_t*>(v.data()), v.size(), connHandle);
|
|
}
|
|
|
|
# else
|
|
|
|
/**
|
|
* @brief Template to send a notification for classes which may have
|
|
* data()/size() or c_str()/length() methods. Falls back to sending
|
|
* the data by casting the first element of the array to a uint8_t
|
|
* pointer and getting the length of the array using sizeof.
|
|
* @tparam T The a reference to a class containing the data to send.
|
|
* @param[in] value The <type\>value to set.
|
|
* @param[in] connHandle The connection handle to send the notification to.
|
|
* @note This function is only available if the type T is not a pointer.
|
|
*/
|
|
template <typename T>
|
|
typename std::enable_if<!std::is_pointer<T>::value && !std::is_array<T>::value, bool>::type notify(
|
|
const T& value, uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const {
|
|
if constexpr (Has_data_size<T>::value) {
|
|
return notify(reinterpret_cast<const uint8_t*>(value.data()), value.size(), connHandle);
|
|
} else if constexpr (Has_c_str_length<T>::value) {
|
|
return notify(reinterpret_cast<const uint8_t*>(value.c_str()), value.length(), connHandle);
|
|
} else {
|
|
return notify(reinterpret_cast<const uint8_t*>(&value), sizeof(value), connHandle);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* @brief Template to send an indication for classes which may have
|
|
* data()/size() or c_str()/length() methods. Falls back to sending
|
|
* the data by casting the first element of the array to a uint8_t
|
|
* pointer and getting the length of the array using sizeof.
|
|
* @tparam T The a reference to a class containing the data to send.
|
|
* @param[in] value The <type\>value to set.
|
|
* @param[in] connHandle The connection handle to send the indication to.
|
|
* @note This function is only available if the type T is not a pointer.
|
|
*/
|
|
template <typename T>
|
|
typename std::enable_if<!std::is_pointer<T>::value && !std::is_array<T>::value, bool>::type indicate(
|
|
const T& value, uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const {
|
|
if constexpr (Has_data_size<T>::value) {
|
|
return indicate(reinterpret_cast<const uint8_t*>(value.data()), value.size(), connHandle);
|
|
} else if constexpr (Has_c_str_length<T>::value) {
|
|
return indicate(reinterpret_cast<const uint8_t*>(value.c_str()), value.length(), connHandle);
|
|
} else {
|
|
return indicate(reinterpret_cast<const uint8_t*>(&value), sizeof(value), connHandle);
|
|
}
|
|
}
|
|
# endif
|
|
|
|
private:
|
|
friend class NimBLEServer;
|
|
friend class NimBLEService;
|
|
|
|
void setService(NimBLEService* pService);
|
|
void readEvent(NimBLEConnInfo& connInfo) override;
|
|
void writeEvent(const uint8_t* val, uint16_t len, NimBLEConnInfo& connInfo) override;
|
|
bool sendValue(const uint8_t* value,
|
|
size_t length,
|
|
bool is_notification = true,
|
|
uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const;
|
|
|
|
NimBLECharacteristicCallbacks* m_pCallbacks{nullptr};
|
|
NimBLEService* m_pService{nullptr};
|
|
std::vector<NimBLEDescriptor*> m_vDescriptors{};
|
|
}; // NimBLECharacteristic
|
|
|
|
/**
|
|
* @brief Callbacks that can be associated with a %BLE characteristic to inform of events.
|
|
*
|
|
* When a server application creates a %BLE characteristic, we may wish to be informed when there is either
|
|
* a read or write request to the characteristic's value. An application can register a
|
|
* sub-classed instance of this class and will be notified when such an event happens.
|
|
*/
|
|
class NimBLECharacteristicCallbacks {
|
|
public:
|
|
virtual ~NimBLECharacteristicCallbacks() {}
|
|
virtual void onRead(NimBLECharacteristic* pCharacteristic, NimBLEConnInfo& connInfo);
|
|
virtual void onWrite(NimBLECharacteristic* pCharacteristic, NimBLEConnInfo& connInfo);
|
|
virtual void onStatus(NimBLECharacteristic* pCharacteristic, int code);
|
|
virtual void onSubscribe(NimBLECharacteristic* pCharacteristic, NimBLEConnInfo& connInfo, uint16_t subValue);
|
|
};
|
|
|
|
#endif /* CONFIG_BT_ENABLED && CONFIG_BT_NIMBLE_ROLE_PERIPHERAL */
|
|
#endif /*NIMBLE_CPP_CHARACTERISTIC_H_*/
|