1/*
2 * BluezQt - Asynchronous Bluez wrapper library
3 *
4 * SPDX-FileCopyrightText: 2021 Ivan Podkurkov <podkiva2@gmail.com>
5 *
6 * SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
7 */
8
9#ifndef BLUEZQT_GATTCHARACTERISTICREMOTE_H
10#define BLUEZQT_GATTCHARACTERISTICREMOTE_H
11
12#include "bluezqt_export.h"
13#include "gattdescriptorremote.h"
14#include "types.h"
15#include <QList>
16#include <QMap>
17#include <QObject>
18namespace BluezQt
19{
20
21class GattServiceRemote;
22class PendingCall;
23
24/**
25 * @class BluezQt::GattCharacteristicRemote gattcharacteristicremote.h <BluezQt/GattCharacteristicRemote>
26 *
27 * Bluetooth LE GATT characteristic.
28 *
29 * This class represents a Bluetooth LE GATT characteristic for the clients.
30 */
31class BLUEZQT_EXPORT GattCharacteristicRemote : public QObject
32{
33 Q_OBJECT
34 Q_PROPERTY(QString ubi READ ubi CONSTANT)
35 Q_PROPERTY(QString uuid READ uuid NOTIFY uuidChanged)
36 Q_PROPERTY(QByteArray value READ value NOTIFY valueChanged)
37 Q_PROPERTY(bool writeAcquired READ isWriteAcquired NOTIFY writeAcquiredChanged)
38 Q_PROPERTY(bool notifyAcquired READ isNotifyAcquired NOTIFY notifyAcquiredChanged)
39 Q_PROPERTY(bool notifying READ isNotifying NOTIFY notifyingChanged)
40 Q_PROPERTY(QStringList flags READ flags NOTIFY flagsChanged)
41 Q_PROPERTY(quint16 handle READ handle NOTIFY handleChanged)
42 Q_PROPERTY(quint16 MTU READ MTU NOTIFY MTUChanged)
43 Q_PROPERTY(GattServiceRemotePtr service READ service CONSTANT)
44 Q_PROPERTY(QList<GattDescriptorRemotePtr> descriptors READ descriptors NOTIFY descriptorsChanged)
45
46
47public:
48 /**
49 * Destroys a GattCharacteristic object.
50 */
51 ~GattCharacteristicRemote() override;
52
53 /**
54 * Returns a shared pointer from this.
55 *
56 * @return DevicePtr
57 */
58 GattCharacteristicRemotePtr toSharedPtr() const;
59
60 /**
61 * Returns an UBI of the GATT characteristic.
62 *
63 * Example UBI: "/org/bluez/hci0/dev_40_79_6A_0C_39_75"
64 *
65 * @return UBI of device
66 */
67 QString ubi() const;
68
69 /**
70 * Returns an uuid of the characteristic.
71 *
72 * @return uuid of the characteristic
73 */
74 QString uuid() const;
75
76 /**
77 * Returns an value of the characteristic.
78 *
79 * @return value of the characteristic
80 */
81 QByteArray value() const;
82
83 /**
84 * Returns whether writeAcquired for the characteristic.
85 *
86 * @return true if write is acquired
87 */
88 bool isWriteAcquired() const;
89
90 /**
91 * Returns whether notifyAcquired for the characteristic.
92 *
93 * @return true if notify is acquired
94 */
95 bool isNotifyAcquired() const;
96
97 /**
98 * Returns whether the characteristic is notifying.
99 *
100 * @return true if notifying
101 */
102 bool isNotifying() const;
103
104 /**
105 * Returns flags the characteristic.
106 *
107 * @return flags of characteristic
108 */
109 QStringList flags() const;
110
111 /**
112 * Returns characteristic handle.
113 *
114 * @return qint16 characteristic handle
115 */
116 quint16 handle() const;
117
118 /**
119 * Sets the characteristic handle.
120 *
121 * @param handle characteristic handle
122 * @return void pending call
123 */
124 PendingCall *setHandle(quint16 handle);
125
126 /**
127 * Returns characteristic MTU.
128 *
129 * @return qint16 characteristic MTU
130 */
131 quint16 MTU() const;
132
133 /**
134 * Returns a service that owns that characteristic.
135 *
136 * @return service of characteristic
137 */
138 GattServiceRemotePtr service() const;
139
140 /**
141 * Returns object paths representing the included
142 * services of this service.
143 *
144 * @return Object paths of included services
145 */
146 QList<GattDescriptorRemotePtr> descriptors() const;
147
148public Q_SLOTS:
149 /**
150 * Read the value of the GATT characteristic.
151 *
152 * Issues a request to read the value of the characteristic and
153 * returns the value if the operation was successful.
154 *
155 * Possible errors: PendingCall::NotReady, PendingCall::Failed,
156 * PendingCall::InProgress, PendingCall::AlreadyConnected
157 *
158 * @return QByteArray pending call
159 */
160 PendingCall *readValue(const QVariantMap &options);
161
162 /**
163 * Write the value of the GATT characteristic.
164 *
165 * Issues a request to write the value of the characteristic.
166 *
167 * Possible errors: PendingCall::NotReady, PendingCall::Failed,
168 * PendingCall::InProgress, PendingCall::AlreadyConnected
169 *
170 * @return void pending call
171 */
172 PendingCall *writeValue(const QByteArray &value, const QVariantMap &options);
173
174 /**
175 * Start notifying the value of the GATT characteristic.
176 *
177 * Starts a notification session from this characteristic if it supports
178 * value notifications or indications.
179 *
180 * Possible errors: PendingCall::NotReady, PendingCall::Failed,
181 * PendingCall::InProgress, PendingCall::AlreadyConnected
182 *
183 * @return void pending call
184 */
185 PendingCall *startNotify();
186
187 /**
188 * Stop notifying the value of the GATT characteristic.
189 *
190 * This method will cancel any previous StartNotify transaction.
191 * Note that notifications from a characteristic are shared between
192 * sessions thus calling StopNotify will release a single session.
193 *
194 * Possible errors: PendingCall::NotReady, PendingCall::Failed,
195 * PendingCall::InProgress, PendingCall::AlreadyConnected
196 *
197 * @return void pending call
198 */
199 PendingCall *stopNotify();
200
201 /**
202 * Confirmation that value of the characteristic was received.
203 *
204 * This method doesn't expect a reply so it is just a confirmation
205 * that value was received.
206 *
207 * Possible errors: PendingCall::NotReady, PendingCall::Failed,
208 * PendingCall::InProgress, PendingCall::AlreadyConnected
209 *
210 * @return void pending call
211 */
212 PendingCall *confirm();
213
214Q_SIGNALS:
215 /**
216 * Indicates that at least one of the characteristic's properties have changed.
217 */
218 void characteristicChanged(GattCharacteristicRemotePtr characteristic);
219
220 /**
221 * Indicates that a new descriptor was added (eg. found by connection).
222 */
223 void gattDescriptorAdded(GattDescriptorRemotePtr descriptor);
224
225 /**
226 * Indicates that characteristic descriptors list has changed
227 */
228 void descriptorsChanged(QList<GattDescriptorRemotePtr> descriptors);
229
230 /**
231 * Indicates that a descriptor was removed.
232 */
233 void gattDescriptorRemoved(GattDescriptorRemotePtr descriptor);
234
235 /**
236 * Indicates that at least one of the descriptor's properties have changed.
237 */
238 void gattDescriptorChanged(GattDescriptorRemotePtr descriptor);
239
240 /**
241 * Indicates that characteristic's uuid have changed.
242 */
243 void uuidChanged(const QString &uuid);
244
245 /**
246 * Indicates that characteristic's value have changed.
247 */
248 void valueChanged(const QByteArray value);
249
250 /**
251 * Indicates that characteristic's writeAcquired state have changed.
252 */
253 void writeAcquiredChanged(bool writeAcquired);
254
255 /**
256 * Indicates that characteristic's notifyAcquired state have changed.
257 */
258 void notifyAcquiredChanged(bool notifyAcquired);
259
260 /**
261 * Indicates that characteristic's notifying state have changed.
262 */
263 void notifyingChanged(bool notifying);
264
265 /**
266 * Indicates that characteristic's flags have changed.
267 */
268 void flagsChanged(QStringList flags);
269
270 /**
271 * Indicates that characteristic's handle have changed.
272 */
273 void handleChanged(quint16 handle);
274
275 /**
276 * Indicates that characteristic's MTU have changed.
277 */
278 void MTUChanged(quint16 MTU);
279
280private:
281 BLUEZQT_NO_EXPORT explicit GattCharacteristicRemote(const QString &path, const QVariantMap &properties, GattServiceRemotePtr service);
282
283 const std::unique_ptr<class GattCharacteristicRemotePrivate> d;
284
285 friend class DevicePrivate;
286 friend class GattServiceRemotePrivate;
287 friend class GattCharacteristicRemotePrivate;
288 friend class ManagerPrivate;
289 friend class Adapter;
290};
291
292} // namespace BluezQt
293
294#endif // BLUEZQT_GATTCHARACTERISTICREMOTE_H
295

source code of bluez-qt/src/gattcharacteristicremote.h