BluezQt

device.h
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. */
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. */
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
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 */
456
457 /**
458 * Indicates that at least one of the device's properties have changed.
459 */
461
462 /**
463 * Indicates that a new service was added (eg. found by connection).
464 */
466
467 /**
468 * Indicates that device GATT services list has changed
469 */
471
472 /**
473 * Indicates that a service was removed.
474 */
476
477 /**
478 * Indicates that at least one of the device's services have changed.
479 */
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 */
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 */
577
578 /**
579 * Indicates that device's battery has changed.
580 */
582
583 /**
584 * Indicates that device's input have changed.
585 */
587
588 /**
589 * Indicates that device's media player have changed.
590 */
592
593 /**
594 * Indicates that device's media transport have changed.
595 */
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
Bluetooth adapter.
Bluetooth device.
void nameChanged(const QString &name)
Indicates that device's name have changed.
void modaliasChanged(const QString &modalias)
Indicates that device's modalias have changed.
Type
Device types.
Definition device.h:65
@ Modem
The device is a modem.
Definition device.h:69
@ Wearable
The device is a wearable device.
Definition device.h:97
@ Uncategorized
The device is not of any of the known types.
Definition device.h:103
@ Headset
The device is a headset.
Definition device.h:75
@ Imaging
The device is an uncategorized imaging device.
Definition device.h:95
@ Tablet
The device is a graphics tablet (input device).
Definition device.h:87
@ Camera
The device is a camera.
Definition device.h:91
@ Peripheral
The device is an uncategorized peripheral device.
Definition device.h:89
@ AudioVideo
The device is an uncategorized audio video device.
Definition device.h:79
@ Toy
The device is a toy.
Definition device.h:99
@ Network
The device is a network.
Definition device.h:73
@ Mouse
The device is a mouse.
Definition device.h:83
@ Phone
The device is a phone.
Definition device.h:67
@ Headphones
The device is a headphones.
Definition device.h:77
@ Computer
The device is a computer.
Definition device.h:71
@ Joypad
The device is a joypad.
Definition device.h:85
@ Printer
The device is a printer.
Definition device.h:93
@ Keyboard
The device is a keyboard.
Definition device.h:81
@ Health
The device is a health device.
Definition device.h:101
~Device() override
Destroys a Device object.
void deviceRemoved(DevicePtr device)
Indicates that the device was removed.
void typeChanged(Type type)
Indicates that device's type have changed.
void trustedChanged(bool trusted)
Indicates that device's trusted state have changed.
void mediaTransportChanged(MediaTransportPtr mediaTransport)
Indicates that device's media transport have changed.
void inputChanged(InputPtr input)
Indicates that device's input have changed.
void blockedChanged(bool blocked)
Indicates that device's blocked state have changed.
void iconChanged(const QString &icon)
Indicates that device's icon have changed.
void mediaPlayerChanged(MediaPlayerPtr mediaPlayer)
Indicates that device's media player have changed.
void gattServicesChanged(QList< GattServiceRemotePtr > services)
Indicates that device GATT services list has changed.
void appearanceChanged(quint16 appearance)
Indicates that device's appearance have changed.
void legacyPairingChanged(bool legacyPairing)
Indicates that device's legacy pairing state have changed.
void friendlyNameChanged(const QString &friendlyName)
Indicates that device's friendly name have changed.
void gattServiceChanged(GattServiceRemotePtr service)
Indicates that at least one of the device's services have changed.
void serviceDataChanged(const QHash< QString, QByteArray > &serviceData)
Indicates that the device's service data has changed.
void rssiChanged(qint16 rssi)
Indicates that device's RSSI have changed.
void remoteNameChanged(const QString &remoteName)
Indicates that device's remote name have changed.
void gattServiceRemoved(GattServiceRemotePtr service)
Indicates that a service was removed.
void connectedChanged(bool connected)
Indicates that device's connected state have changed.
void servicesResolvedChanged(bool servicesResolved)
Indicates that device's servicesResolved state have changed.
void pairedChanged(bool paired)
Indicates that device's paired state have changed.
void deviceClassChanged(quint32 deviceClass)
Indicates that device's class have changed.
void batteryChanged(BatteryPtr battery)
Indicates that device's battery has changed.
void uuidsChanged(const QStringList &uuids)
Indicates that device's UUIDs have changed.
void gattServiceAdded(GattServiceRemotePtr service)
Indicates that a new service was added (eg.
void manufacturerDataChanged(ManData man)
Indicates that device's manufacturer data have changed.
void deviceChanged(DevicePtr device)
Indicates that at least one of the device's properties have changed.
void addressChanged(const QString &address)
Indicates that device's address have changed.
Pending method call.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Nov 29 2024 11:46:08 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.