esp-nimble-cpp 2.3.3
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 "syscfg/syscfg.h"
22#if CONFIG_BT_NIMBLE_ENABLED && MYNEWT_VAL(BLE_ROLE_PERIPHERAL)
23
24class NimBLECharacteristicCallbacks;
25class NimBLEService;
26class NimBLECharacteristic;
27class NimBLEDescriptor;
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);
47 NimBLECharacteristic(const NimBLEUUID& uuid,
48 uint16_t properties = NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::WRITE,
49 uint16_t maxLen = BLE_ATT_ATTR_MAX_LEN,
50 NimBLEService* pService = nullptr);
51
52 ~NimBLECharacteristic();
53
54 std::string toString() const;
55 void addDescriptor(NimBLEDescriptor* pDescriptor);
56 void removeDescriptor(NimBLEDescriptor* pDescriptor, bool deleteDsc = false);
57 uint16_t getProperties() const;
58 void setCallbacks(NimBLECharacteristicCallbacks* pCallbacks);
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);
67 NimBLEDescriptor* createDescriptor(const NimBLEUUID& uuid,
68 uint32_t properties = NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::WRITE,
69 uint16_t maxLen = BLE_ATT_ATTR_MAX_LEN);
70 NimBLE2904* create2904();
71 NimBLEDescriptor* getDescriptorByUUID(const char* uuid) const;
72 NimBLEDescriptor* getDescriptorByUUID(const NimBLEUUID& uuid) const;
73 NimBLEDescriptor* getDescriptorByHandle(uint16_t handle) const;
74 NimBLEService* getService() const;
75
76 NimBLECharacteristicCallbacks* getCallbacks() const;
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
248class NimBLECharacteristicCallbacks {
249 public:
250 virtual ~NimBLECharacteristicCallbacks() {}
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_NIMBLE_ENABLED && MYNEWT_VAL(BLE_ROLE_PERIPHERAL)
258#endif // NIMBLE_CPP_CHARACTERISTIC_H_
NimBLEConnInfo
Connection information.
Definition NimBLEConnInfo.h:32
NimBLEUUID
A model of a BLE UUID.
Definition NimBLEUUID.h:41