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 * @class BluezQt::Device device.h <BluezQt/Device>
26 *
27 * Bluetooth device.
28 *
29 * This class represents a Bluetooth device.
30 */
31class 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
61public:
62 /**
63 * %Device types.
64 */
65 enum Type {
66 /** The device is a phone. */
67 Phone,
68 /** The device is a modem. */
69 Modem,
70 /** The device is a computer. */
71 Computer,
72 /** The device is a network. */
73 Network,
74 /** The device is a headset. */
75 Headset,
76 /** The device is a headphones. */
77 Headphones,
78 /** The device is an uncategorized audio video device. */
79 AudioVideo,
80 /** The device is a keyboard. */
81 Keyboard,
82 /** The device is a mouse. */
83 Mouse,
84 /** The device is a joypad. */
85 Joypad,
86 /** The device is a graphics tablet (input device). */
87 Tablet,
88 /** The device is an uncategorized peripheral device. */
89 Peripheral,
90 /** The device is a camera. */
91 Camera,
92 /** The device is a printer. */
93 Printer,
94 /** The device is an uncategorized imaging device. */
95 Imaging,
96 /** The device is a wearable device. */
97 Wearable,
98 /** The device is a toy. */
99 Toy,
100 /** The device is a health device. */
101 Health,
102 /** The device is not of any of the known types. */
103 Uncategorized,
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
382public 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
451Q_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
598private:
599 BLUEZQT_NO_EXPORT explicit Device(const QString &path, const QVariantMap &properties, AdapterPtr adapter);
600
601 std::unique_ptr<class DevicePrivate> const d;
602
603 friend class DevicePrivate;
604 friend class ManagerPrivate;
605 friend class Adapter;
606};
607
608} // namespace BluezQt
609
610Q_DECLARE_METATYPE(BluezQt::ManData)
611
612#endif // BLUEZQT_DEVICE_H
613

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