BluezQt

gattcharacteristicremote.h
1 /*
2  * BluezQt - Asynchronous Bluez wrapper library
3  *
4  * SPDX-FileCopyrightText: 2021 Ivan Podkurkov <[email protected]>
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>
18 namespace BluezQt
19 {
20 
21 class GattServiceRemote;
22 class 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  */
31 class 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 
47 public:
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 
148 public 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 
214 Q_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 
280 private:
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
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Wed Sep 27 2023 04:04:48 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.