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

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