BluezQt

device.h
1 /*
2  * BluezQt - Asynchronous BlueZ wrapper library
3  *
4  * SPDX-FileCopyrightText: 2014-2015 David Rosca <[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_DEVICE_H
10 #define BLUEZQT_DEVICE_H
11 
12 #include <QObject>
13 
14 #include "bluezqt_export.h"
15 #include "gattserviceremote.h"
16 #include "input.h"
17 #include "mediaplayer.h"
18 #include "mediatransport.h"
19 namespace BluezQt
20 {
21 class Adapter;
22 class PendingCall;
23 
24 /**
25  * @class BluezQt::Device device.h <BluezQt/Device>
26  *
27  * Bluetooth device.
28  *
29  * This class represents a Bluetooth device.
30  */
31 class BLUEZQT_EXPORT Device : public QObject
32 {
33  Q_OBJECT
34 
35  Q_PROPERTY(QString ubi READ ubi)
36  Q_PROPERTY(QString address READ address NOTIFY addressChanged)
37  Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged)
38  Q_PROPERTY(QString friendlyName READ friendlyName NOTIFY friendlyNameChanged)
39  Q_PROPERTY(QString remoteName READ remoteName NOTIFY remoteNameChanged)
40  Q_PROPERTY(quint32 deviceClass READ deviceClass NOTIFY deviceClassChanged)
41  Q_PROPERTY(Type type READ type NOTIFY typeChanged)
42  Q_PROPERTY(quint16 appearance READ appearance NOTIFY appearanceChanged)
43  Q_PROPERTY(QString icon READ icon NOTIFY iconChanged)
44  Q_PROPERTY(bool paired READ isPaired NOTIFY pairedChanged)
45  Q_PROPERTY(bool trusted READ isTrusted WRITE setTrusted NOTIFY trustedChanged)
46  Q_PROPERTY(bool blocked READ isBlocked WRITE setBlocked NOTIFY blockedChanged)
47  Q_PROPERTY(bool legacyPairing READ hasLegacyPairing NOTIFY legacyPairingChanged)
48  Q_PROPERTY(qint16 rssi READ rssi NOTIFY rssiChanged)
49  Q_PROPERTY(ManData manufacturerData READ manufacturerData NOTIFY manufacturerDataChanged)
50  Q_PROPERTY(bool servicesResolved READ isServicesResolved NOTIFY servicesResolvedChanged)
51  Q_PROPERTY(bool connected READ isConnected NOTIFY connectedChanged)
52  Q_PROPERTY(QStringList uuids READ uuids NOTIFY uuidsChanged)
53  Q_PROPERTY(QString modalias READ modalias NOTIFY modaliasChanged)
54  Q_PROPERTY(BatteryPtr battery READ battery NOTIFY batteryChanged)
55  Q_PROPERTY(InputPtr input READ input NOTIFY inputChanged)
56  Q_PROPERTY(MediaPlayerPtr mediaPlayer READ mediaPlayer NOTIFY mediaPlayerChanged)
57  Q_PROPERTY(MediaTransportPtr mediaTransport READ mediaTransport NOTIFY mediaTransportChanged)
58  Q_PROPERTY(AdapterPtr adapter READ adapter)
59  Q_PROPERTY(QList<GattServiceRemotePtr> gattServices READ gattServices NOTIFY gattServicesChanged)
60 
61 public:
62  /**
63  * %Device types.
64  */
65  enum Type {
66  /** The device is a phone. */
68  /** The device is a modem. */
70  /** The device is a computer. */
72  /** The device is a network. */
74  /** The device is a headset. */
76  /** The device is a headphones. */
78  /** The device is an uncategorized audio video device. */
80  /** The device is a keyboard. */
82  /** The device is a mouse. */
84  /** The device is a joypad. */
86  /** The device is a graphics tablet (input device). */
88  /** The device is an uncategorized peripheral device. */
90  /** The device is a camera. */
92  /** The device is a printer. */
94  /** The device is an uncategorized imaging device. */
96  /** The device is a wearable device. */
98  /** The device is a toy. */
99  Toy,
100  /** The device is a health device. */
102  /** The device is not of any of the known types. */
104  };
105  Q_ENUM(Type)
106 
107  /**
108  * Destroys a Device object.
109  */
110  ~Device() override;
111 
112  /**
113  * Returns a shared pointer from this.
114  *
115  * @return DevicePtr
116  */
117  DevicePtr toSharedPtr() const;
118 
119  /**
120  * Returns an UBI of the device.
121  *
122  * Example UBI: "/org/bluez/hci0/dev_40_79_6A_0C_39_75"
123  *
124  * @return UBI of device
125  */
126  QString ubi() const;
127 
128  /**
129  * Returns an address of the device.
130  *
131  * Example address: "40:79:6A:0C:39:75"
132  *
133  * @return address of device
134  */
135  QString address() const;
136 
137  /**
138  * Returns a name of the device.
139  *
140  * If the name of the device wasn't previously changed,
141  * remoteName is returned.
142  *
143  * @return name of device
144  */
145  QString name() const;
146 
147  /**
148  * Sets the name of the device.
149  *
150  * @param name name for device
151  * @return void pending call
152  */
153  PendingCall *setName(const QString &name);
154 
155  /**
156  * Returns a friendly name of the device.
157  *
158  * Friendly name is a string "name (remoteName)".
159  * If the remoteName is same as name, it returns just name.
160  *
161  * @return friendly name of device
162  */
163  QString friendlyName() const;
164 
165  /**
166  * Returns a remote name of the device.
167  *
168  * @return remote name of device
169  */
170  QString remoteName() const;
171 
172  /**
173  * Returns a class of the device.
174  *
175  * In case of Bluetooth Low Energy only devices,
176  * device class is invalid (0).
177  *
178  * @see type() const
179  *
180  * @return class of device
181  */
182  quint32 deviceClass() const;
183 
184  /**
185  * Returns a type of the device.
186  *
187  * Type of device is deduced from its class (for Bluetooth Classic devices)
188  * or its appearance (for Bluetooth Low Energy devices).
189  *
190  * @see deviceClass() const
191  * @see appearance() const
192  *
193  * @return type of device
194  */
195  Device::Type type() const;
196 
197  /**
198  * Returns an appearance of the device.
199  *
200  * @return appearance of device
201  */
202  quint16 appearance() const;
203 
204  /**
205  * Returns an icon name of the device.
206  *
207  * In case the icon is empty, "preferences-system-bluetooth" is returned.
208  *
209  * @return icon name of device
210  */
211  QString icon() const;
212 
213  /**
214  * Returns whether the device is paired.
215  *
216  * @return true if device is paired
217  */
218  bool isPaired() const;
219 
220  /**
221  * Returns whether the device is trusted.
222  *
223  * @return true if device is trusted
224  */
225  bool isTrusted() const;
226 
227  /**
228  * Sets the trusted state of the device.
229  *
230  * @param trusted trusted state
231  * @return void pending call
232  */
233  PendingCall *setTrusted(bool trusted);
234 
235  /**
236  * Returns whether the device is blocked.
237  *
238  * @return true if device is blocked
239  */
240  bool isBlocked() const;
241 
242  /**
243  * Sets the blocked state of the device.
244  *
245  * @param blocked blocked state
246  * @return void pending call
247  */
248  PendingCall *setBlocked(bool blocked);
249 
250  /**
251  * Returns whether the device has legacy pairing.
252  *
253  * @return true if device has legacy pairing
254  */
255  bool hasLegacyPairing() const;
256 
257  /**
258  * Returns Received Signal Strength Indicator of the device.
259  *
260  * The bigger value indicates better signal strength.
261  *
262  * @note RSSI is only updated during discovery.
263  *
264  * @return RSSI of device
265  */
266  qint16 rssi() const;
267 
268  /**
269  * Returns manufacturer specific advertisement data.
270  *
271  * @note Keys are 16 bits Manufacturer ID followed by
272  * its byte array value.
273  *
274  * @return manufacturerData of device.
275  */
276  ManData manufacturerData() const;
277 
278  /**
279  * Returns whether or not service discovery has been resolved.
280  *
281  * @return true if servicesResolved
282  */
283  bool isServicesResolved() const;
284 
285  /**
286  * Returns whether the device is connected.
287  *
288  * @return true if connected
289  */
290  bool isConnected() const;
291 
292  /**
293  * Returns UUIDs of supported services by the device.
294  *
295  * UUIDs will always be returned in uppercase.
296  *
297  * @return UUIDs of supported services
298  */
299  QStringList uuids() const;
300 
301  /**
302  * Returns remote device ID in modalias format.
303  *
304  * @return device modalias
305  */
306  QString modalias() const;
307 
308  /**
309  * Returns the service advertisement data.
310  *
311  * @returns A hash with keys being the UUIDs in and values being the raw service data value.
312  * @since 5.72
313  */
314  QHash<QString, QByteArray> serviceData() const;
315 
316  /**
317  * Returns the battery interface for the device.
318  *
319  * @return null if device has no battery
320  * @since 5.66
321  */
322  BatteryPtr battery() const;
323 
324  /**
325  * Returns the input interface for the device.
326  *
327  * Only input devices will have valid input interface.
328  *
329  * @return null if device have no input
330  */
331  InputPtr input() const;
332 
333  /**
334  * Returns the media player interface for the device.
335  *
336  * Only devices with connected appropriate profile will
337  * have valid media player interface.
338  *
339  * @return null if device have no media player
340  */
341  MediaPlayerPtr mediaPlayer() const;
342 
343  /**
344  * Returns the media transport interface for the device.
345  *
346  * Only devices with connected appropriate profile will
347  * have valid media transport interface.
348  *
349  * @return null if device have no media transport
350  */
351  MediaTransportPtr mediaTransport() const;
352 
353  /**
354  * Returns an adapter that discovered this device.
355  *
356  * @return adapter of device
357  */
358  AdapterPtr adapter() const;
359 
360  /**
361  * Returns list of services known by the device.
362  *
363  * @return list of services
364  */
365  QList<GattServiceRemotePtr> gattServices() const;
366  /**
367  * Returns a string for device type.
368  *
369  * @param type device type
370  * @return device type string
371  */
372  static QString typeToString(Device::Type type);
373 
374  /**
375  * Returns a device type for string.
376  *
377  * @param typeString type string
378  * @return device type
379  */
380  static Device::Type stringToType(const QString &typeString);
381 
382 public Q_SLOTS:
383  /**
384  * Connects all auto-connectable profiles of the device.
385  *
386  * This method indicates success if at least one profile was connected.
387  *
388  * Possible errors: PendingCall::NotReady, PendingCall::Failed,
389  * PendingCall::InProgress, PendingCall::AlreadyConnected
390  *
391  * @return void pending call
392  */
393  PendingCall *connectToDevice();
394 
395  /**
396  * Disconnects all connected profiles of the device.
397  *
398  * This method can be used to cancel not-yet finished connectDevice() call.
399  *
400  * Possible errors: PendingCall::NotConnected
401  *
402  * @return void pending call
403  */
404  PendingCall *disconnectFromDevice();
405 
406  /**
407  * Connects a specific profile of the device.
408  *
409  * Possible errors: PendingCall::DoesNotExist, PendingCall::AlreadyConnected,
410  * PendingCall::ConnectFailed
411  *
412  * @param uuid service UUID
413  * @return void pending call
414  */
415  PendingCall *connectProfile(const QString &uuid);
416 
417  /**
418  * Disconnects a specific profile of the device.
419  *
420  * Possible errors: PendingCall::DoesNotExist, PendingCall::Failed,
421  * PendingCall::NotConnected, PendingCall::NotSupported
422  *
423  * @param uuid service UUID
424  * @return void pending call
425  */
426  PendingCall *disconnectProfile(const QString &uuid);
427 
428  /**
429  * Initiates a pairing with the device.
430  *
431  * Possible errors: PendingCall::InvalidArguments, PendingCall::Failed,
432  * PendingCall::AlreadyExists, PendingCall::AuthenticationCanceled,
433  * PendingCall::AuthenticationFailed, PendingCall::AuthenticationRejected,
434  * PendingCall::AuthenticationTimeout, PendingCall::ConnectionAttemptFailed
435  *
436  * @return void pending call
437  */
438  PendingCall *pair();
439 
440  /**
441  * Cancels a pairing with the device.
442  *
443  * This method can be used to cancel pairing operation initiated with pair().
444  *
445  * Possible errors: PendingCall::DoesNotExist, PendingCall::Failed
446  *
447  * @return void pending call
448  */
449  PendingCall *cancelPairing();
450 
451 Q_SIGNALS:
452  /**
453  * Indicates that the device was removed.
454  */
455  void deviceRemoved(DevicePtr device);
456 
457  /**
458  * Indicates that at least one of the device's properties have changed.
459  */
460  void deviceChanged(DevicePtr device);
461 
462  /**
463  * Indicates that a new service was added (eg. found by connection).
464  */
465  void gattServiceAdded(GattServiceRemotePtr service);
466 
467  /**
468  * Indicates that device GATT services list has changed
469  */
470  void gattServicesChanged(QList<GattServiceRemotePtr> services);
471 
472  /**
473  * Indicates that a service was removed.
474  */
475  void gattServiceRemoved(GattServiceRemotePtr service);
476 
477  /**
478  * Indicates that at least one of the device's services have changed.
479  */
480  void gattServiceChanged(GattServiceRemotePtr service);
481 
482  /**
483  * Indicates that device's name have changed.
484  */
485  void nameChanged(const QString &name);
486 
487  /**
488  * Indicates that device's address have changed.
489  */
490  void addressChanged(const QString &address);
491 
492  /**
493  * Indicates that device's friendly name have changed.
494  */
495  void friendlyNameChanged(const QString &friendlyName);
496 
497  /**
498  * Indicates that device's remote name have changed.
499  */
500  void remoteNameChanged(const QString &remoteName);
501 
502  /**
503  * Indicates that device's class have changed.
504  */
505  void deviceClassChanged(quint32 deviceClass);
506 
507  /**
508  * Indicates that device's type have changed.
509  */
510  void typeChanged(Type type);
511 
512  /**
513  * Indicates that device's appearance have changed.
514  */
515  void appearanceChanged(quint16 appearance);
516 
517  /**
518  * Indicates that device's icon have changed.
519  */
520  void iconChanged(const QString &icon);
521 
522  /**
523  * Indicates that device's paired state have changed.
524  */
525  void pairedChanged(bool paired);
526 
527  /**
528  * Indicates that device's trusted state have changed.
529  */
530  void trustedChanged(bool trusted);
531 
532  /**
533  * Indicates that device's blocked state have changed.
534  */
535  void blockedChanged(bool blocked);
536 
537  /**
538  * Indicates that device's legacy pairing state have changed.
539  */
540  void legacyPairingChanged(bool legacyPairing);
541 
542  /**
543  * Indicates that device's RSSI have changed.
544  */
545  void rssiChanged(qint16 rssi);
546 
547  /**
548  * Indicates that device's manufacturer data have changed.
549  */
550  void manufacturerDataChanged(ManData man);
551 
552  /**
553  * Indicates that device's servicesResolved state have changed.
554  */
555  void servicesResolvedChanged(bool servicesResolved);
556 
557  /**
558  * Indicates that device's connected state have changed.
559  */
560  void connectedChanged(bool connected);
561 
562  /**
563  * Indicates that device's UUIDs have changed.
564  */
565  void uuidsChanged(const QStringList &uuids);
566 
567  /**
568  * Indicates that device's modalias have changed.
569  */
570  void modaliasChanged(const QString &modalias);
571 
572  /**
573  * Indicates that the device's service data has changed.
574  * @since 5.72
575  */
576  void serviceDataChanged(const QHash<QString, QByteArray> &serviceData);
577 
578  /**
579  * Indicates that device's battery has changed.
580  */
581  void batteryChanged(BatteryPtr battery);
582 
583  /**
584  * Indicates that device's input have changed.
585  */
586  void inputChanged(InputPtr input);
587 
588  /**
589  * Indicates that device's media player have changed.
590  */
591  void mediaPlayerChanged(MediaPlayerPtr mediaPlayer);
592 
593  /**
594  * Indicates that device's media transport have changed.
595  */
596  void mediaTransportChanged(MediaTransportPtr mediaTransport);
597 
598 private:
599  explicit Device(const QString &path, const QVariantMap &properties, AdapterPtr adapter);
600 
601  class DevicePrivate *const d;
602 
603  friend class DevicePrivate;
604  friend class ManagerPrivate;
605  friend class Adapter;
606 };
607 
608 } // namespace BluezQt
609 
610 Q_DECLARE_METATYPE(BluezQt::ManData)
611 
612 #endif // BLUEZQT_DEVICE_H
@ Imaging
The device is an uncategorized imaging device.
Definition: device.h:95
@ Keyboard
The device is a keyboard.
Definition: device.h:81
Type
Device types.
Definition: device.h:65
@ Mouse
The device is a mouse.
Definition: device.h:83
@ Printer
The device is a printer.
Definition: device.h:93
@ AudioVideo
The device is an uncategorized audio video device.
Definition: device.h:79
@ Network
The device is a network.
Definition: device.h:73
@ Phone
The device is a phone.
Definition: device.h:67
@ Headset
The device is a headset.
Definition: device.h:75
@ Computer
The device is a computer.
Definition: device.h:71
@ Modem
The device is a modem.
Definition: device.h:69
@ Joypad
The device is a joypad.
Definition: device.h:85
@ Toy
The device is a toy.
Definition: device.h:99
@ Peripheral
The device is an uncategorized peripheral device.
Definition: device.h:89
@ Wearable
The device is a wearable device.
Definition: device.h:97
@ Health
The device is a health device.
Definition: device.h:101
@ Camera
The device is a camera.
Definition: device.h:91
@ Headphones
The device is a headphones.
Definition: device.h:77
@ Tablet
The device is a graphics tablet (input device).
Definition: device.h:87
@ Uncategorized
The device is not of any of the known types.
Definition: device.h:103
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sun Sep 25 2022 04:19:10 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.