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

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