NimBLE-Arduino 2.3.2
Loading...
Searching...
No Matches
NimBLECharacteristic.h
1/*
2 * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
3 * esp-nimble-cpp, NimBLE-Arduino contributors.
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18#ifndef NIMBLE_CPP_CHARACTERISTIC_H_
19#define NIMBLE_CPP_CHARACTERISTIC_H_
20
21#include "nimconfig.h"
22#if CONFIG_BT_ENABLED && CONFIG_BT_NIMBLE_ROLE_PERIPHERAL
23
25class NimBLEService;
28class NimBLE2904;
29
30# include "NimBLELocalValueAttribute.h"
31
32# include <string>
33# include <vector>
34
41class NimBLECharacteristic : public NimBLELocalValueAttribute {
42 public:
43 NimBLECharacteristic(const char* uuid,
44 uint16_t properties = NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::WRITE,
45 uint16_t maxLen = BLE_ATT_ATTR_MAX_LEN,
46 NimBLEService* pService = nullptr);
48 uint16_t properties = NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::WRITE,
49 uint16_t maxLen = BLE_ATT_ATTR_MAX_LEN,
50 NimBLEService* pService = nullptr);
51
53
54 std::string toString() const;
55 void addDescriptor(NimBLEDescriptor* pDescriptor);
56 void removeDescriptor(NimBLEDescriptor* pDescriptor, bool deleteDsc = false);
57 uint16_t getProperties() const;
59 bool indicate(uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const;
60 bool indicate(const uint8_t* value, size_t length, uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const;
61 bool notify(uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const;
62 bool notify(const uint8_t* value, size_t length, uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const;
63
64 NimBLEDescriptor* createDescriptor(const char* uuid,
65 uint32_t properties = NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::WRITE,
66 uint16_t maxLen = BLE_ATT_ATTR_MAX_LEN);
68 uint32_t properties = NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::WRITE,
69 uint16_t maxLen = BLE_ATT_ATTR_MAX_LEN);
71 NimBLEDescriptor* getDescriptorByUUID(const char* uuid) const;
73 NimBLEDescriptor* getDescriptorByHandle(uint16_t handle) const;
75
77
78 /*********************** Template Functions ************************/
79
80# if __cplusplus < 201703L
87 template <typename T>
88# ifdef _DOXYGEN_
89 bool
90# else
91 typename std::enable_if<!std::is_pointer<T>::value && !std::is_array<T>::value && !Has_c_str_length<T>::value &&
92 !Has_data_size<T>::value,
93 bool>::type
94# endif
95 notify(const T& v, uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const {
96 return notify(reinterpret_cast<const uint8_t*>(&v), sizeof(T), connHandle);
97 }
98
104 template <typename T>
105# ifdef _DOXYGEN_
106 bool
107# else
108 typename std::enable_if<Has_c_str_length<T>::value && !Has_data_size<T>::value, bool>::type
109# endif
110 notify(const T& s, uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const {
111 return notify(reinterpret_cast<const uint8_t*>(s.c_str()), s.length(), connHandle);
112 }
113
119 template <typename T>
120# ifdef _DOXYGEN_
121 bool
122# else
123 typename std::enable_if<Has_data_size<T>::value, bool>::type
124# endif
125 notify(const T& v, uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const {
126 return notify(reinterpret_cast<const uint8_t*>(v.data()), v.size(), connHandle);
127 }
128
135 template <typename T>
136# ifdef _DOXYGEN_
137 bool
138# else
139 typename std::enable_if<!std::is_pointer<T>::value && !std::is_array<T>::value && !Has_c_str_length<T>::value &&
140 !Has_data_size<T>::value,
141 bool>::type
142# endif
143 indicate(const T& v, uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const {
144 return indicate(reinterpret_cast<const uint8_t*>(&v), sizeof(T), connHandle);
145 }
146
152 template <typename T>
153# ifdef _DOXYGEN_
154 bool
155# else
156 typename std::enable_if<Has_c_str_length<T>::value && !Has_data_size<T>::value, bool>::type
157# endif
158 indicate(const T& s, uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const {
159 return indicate(reinterpret_cast<const uint8_t*>(s.c_str()), s.length(), connHandle);
160 }
161
167 template <typename T>
168# ifdef _DOXYGEN_
169 bool
170# else
171 typename std::enable_if<Has_data_size<T>::value, bool>::type
172# endif
173 indicate(const T& v, uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const {
174 return indicate(reinterpret_cast<const uint8_t*>(v.data()), v.size(), connHandle);
175 }
176
177# else
178
189 template <typename T>
190 typename std::enable_if<!std::is_pointer<T>::value && !std::is_array<T>::value, bool>::type notify(
191 const T& value, uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const {
192 if constexpr (Has_data_size<T>::value) {
193 return notify(reinterpret_cast<const uint8_t*>(value.data()), value.size(), connHandle);
194 } else if constexpr (Has_c_str_length<T>::value) {
195 return notify(reinterpret_cast<const uint8_t*>(value.c_str()), value.length(), connHandle);
196 } else {
197 return notify(reinterpret_cast<const uint8_t*>(&value), sizeof(value), connHandle);
198 }
199 }
200
211 template <typename T>
212 typename std::enable_if<!std::is_pointer<T>::value && !std::is_array<T>::value, bool>::type indicate(
213 const T& value, uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const {
214 if constexpr (Has_data_size<T>::value) {
215 return indicate(reinterpret_cast<const uint8_t*>(value.data()), value.size(), connHandle);
216 } else if constexpr (Has_c_str_length<T>::value) {
217 return indicate(reinterpret_cast<const uint8_t*>(value.c_str()), value.length(), connHandle);
218 } else {
219 return indicate(reinterpret_cast<const uint8_t*>(&value), sizeof(value), connHandle);
220 }
221 }
222# endif
223
224 private:
225 friend class NimBLEServer;
226 friend class NimBLEService;
227
228 void setService(NimBLEService* pService);
229 void readEvent(NimBLEConnInfo& connInfo) override;
230 void writeEvent(const uint8_t* val, uint16_t len, NimBLEConnInfo& connInfo) override;
231 bool sendValue(const uint8_t* value,
232 size_t length,
233 bool is_notification = true,
234 uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE) const;
235
236 NimBLECharacteristicCallbacks* m_pCallbacks{nullptr};
237 NimBLEService* m_pService{nullptr};
238 std::vector<NimBLEDescriptor*> m_vDescriptors{};
239}; // NimBLECharacteristic
240
249 public:
251 virtual void onRead(NimBLECharacteristic* pCharacteristic, NimBLEConnInfo& connInfo);
252 virtual void onWrite(NimBLECharacteristic* pCharacteristic, NimBLEConnInfo& connInfo);
253 virtual void onStatus(NimBLECharacteristic* pCharacteristic, int code);
254 virtual void onSubscribe(NimBLECharacteristic* pCharacteristic, NimBLEConnInfo& connInfo, uint16_t subValue);
255};
256
257#endif // CONFIG_BT_ENABLED && CONFIG_BT_NIMBLE_ROLE_PERIPHERAL
258#endif // NIMBLE_CPP_CHARACTERISTIC_H_
Descriptor for Characteristic Presentation Format.
Definition NimBLE2904.h:39
Callbacks that can be associated with a BLE characteristic to inform of events.
Definition NimBLECharacteristic.h:248
virtual void onSubscribe(NimBLECharacteristic *pCharacteristic, NimBLEConnInfo &connInfo, uint16_t subValue)
Callback function called when a client changes subscription status.
Definition NimBLECharacteristic.cpp:411
virtual void onRead(NimBLECharacteristic *pCharacteristic, NimBLEConnInfo &connInfo)
Callback function to support a read request.
Definition NimBLECharacteristic.cpp:377
virtual void onStatus(NimBLECharacteristic *pCharacteristic, int code)
Callback function to support a Notify/Indicate Status report.
Definition NimBLECharacteristic.cpp:397
virtual void onWrite(NimBLECharacteristic *pCharacteristic, NimBLEConnInfo &connInfo)
Callback function to support a write request.
Definition NimBLECharacteristic.cpp:386
The model of a BLE Characteristic.
Definition NimBLECharacteristic.h:41
uint16_t getProperties() const
Get the properties of the characteristic.
Definition NimBLECharacteristic.cpp:199
NimBLEDescriptor * getDescriptorByHandle(uint16_t handle) const
Return the BLE Descriptor for the given handle.
Definition NimBLECharacteristic.cpp:186
void setCallbacks(NimBLECharacteristicCallbacks *pCallbacks)
Set the callback handlers for this characteristic.
Definition NimBLECharacteristic.cpp:338
void removeDescriptor(NimBLEDescriptor *pDescriptor, bool deleteDsc=false)
Remove a descriptor from the characteristic.
Definition NimBLECharacteristic.cpp:136
bool indicate(const T &s, uint16_t connHandle=BLE_HS_CONN_HANDLE_NONE) const
Template to send a indication with a value from a class that has a c_str() and length() method.
Definition NimBLECharacteristic.h:158
NimBLEDescriptor * getDescriptorByUUID(const char *uuid) const
Return the BLE Descriptor for the given UUID.
Definition NimBLECharacteristic.cpp:163
~NimBLECharacteristic()
Destructor.
Definition NimBLECharacteristic.cpp:53
NimBLEService * getService() const
Get the service that owns this characteristic.
Definition NimBLECharacteristic.cpp:206
bool notify(const T &v, uint16_t connHandle=BLE_HS_CONN_HANDLE_NONE) const
Template to send a notification with a value from a struct or array.
Definition NimBLECharacteristic.h:95
bool indicate(const T &v, uint16_t connHandle=BLE_HS_CONN_HANDLE_NONE) const
Template to send an indication with a value from a struct or array.
Definition NimBLECharacteristic.h:143
NimBLEDescriptor * createDescriptor(const char *uuid, uint32_t properties=NIMBLE_PROPERTY::READ|NIMBLE_PROPERTY::WRITE, uint16_t maxLen=BLE_ATT_ATTR_MAX_LEN)
Create a new BLE Descriptor associated with this characteristic.
Definition NimBLECharacteristic.cpp:66
bool indicate(uint16_t connHandle=BLE_HS_CONN_HANDLE_NONE) const
Send an indication.
Definition NimBLECharacteristic.cpp:220
bool notify(const T &s, uint16_t connHandle=BLE_HS_CONN_HANDLE_NONE) const
Template to send a notification with a value from a class that has a c_str() and length() method.
Definition NimBLECharacteristic.h:110
NimBLECharacteristicCallbacks * getCallbacks() const
Get the callback handlers for this characteristic.
Definition NimBLECharacteristic.cpp:349
bool notify(uint16_t connHandle=BLE_HS_CONN_HANDLE_NONE) const
Send a notification.
Definition NimBLECharacteristic.cpp:242
NimBLE2904 * create2904()
Create a Characteristic Presentation Format Descriptor for this characteristic.
Definition NimBLECharacteristic.cpp:94
void addDescriptor(NimBLEDescriptor *pDescriptor)
Add a descriptor to the characteristic.
Definition NimBLECharacteristic.cpp:104
std::string toString() const
Return a string representation of the characteristic.
Definition NimBLECharacteristic.cpp:357
Connection information.
Definition NimBLEConnInfo.h:32
A model of a BLE descriptor.
Definition NimBLEDescriptor.h:33
The model of a BLE server.
Definition NimBLEServer.h:62
The model of a BLE service.
Definition NimBLEService.h:34
A model of a BLE UUID.
Definition NimBLEUUID.h:41