BluezQt

manager.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_MANAGER_H
10 #define BLUEZQT_MANAGER_H
11 
12 #include <QObject>
13 
14 #include "adapter.h"
15 #include "bluezqt_export.h"
16 #include "media.h"
17 #include "rfkill.h"
18 
19 namespace BluezQt
20 {
21 class Device;
22 class Agent;
23 class Profile;
24 class PendingCall;
25 class InitManagerJob;
26 
27 /**
28  * @class BluezQt::Manager manager.h <BluezQt/Manager>
29  *
30  * Bluetooth manager.
31  *
32  * The entry point to communicate with system BlueZ daemon.
33  *
34  * The typical usecase is to work with usableAdapter() (any powered adapter),
35  * but it is also possible to use specific adapter.
36  *
37  * You must call init() before other functions can be used.
38  *
39  * The only functions that can be used before initialization are two rfkill-related
40  * functions: isBluetoothBlocked() and setBluetoothBlocked().
41  *
42  * Example use in C++ code:
43  * @code
44  * BluezQt::Manager *manager = new BluezQt::Manager();
45  * BluezQt::InitManagerJob *job = manager->init();
46  * job->start();
47  * connect(job, &BluezQt::InitManagerJob::result, ...);
48  * @endcode
49  *
50  * In QML, manager is a singleton and initialization is started when first using
51  * the manager. You don't need to track initialized state, just use property binding.
52  *
53  * Example use in QML code:
54  * @code
55  * import QtQuick 2.2
56  * import org.kde.bluezqt 1.0 as BluezQt
57  *
58  * Item {
59  * property QtObject manager : BluezQt.Manager
60  * property devicesCount : manager.devices.length
61  * property adaptersCount : manager.adapters.length
62  *
63  * Component.onCompleted: {
64  * console.log("Manager operational:", manager.operational)
65  * }
66  * }
67  * @endcode
68  *
69  * @note All communication with BlueZ daemon happens asynchronously. Almost all methods
70  * returns PendingCall to help track the call progress and to check for any errors.
71  *
72  * @note If manager is not operational, all methods that returns a PendingCall will fail
73  * with PendingCall::InternalError.
74  *
75  * @see InitManagerJob
76  */
77 class BLUEZQT_EXPORT Manager : public QObject
78 {
79  Q_OBJECT
80 
81  Q_PROPERTY(bool initialized READ isInitialized)
82  Q_PROPERTY(bool operational READ isOperational NOTIFY operationalChanged)
83  Q_PROPERTY(bool bluetoothOperational READ isBluetoothOperational NOTIFY bluetoothOperationalChanged)
84  Q_PROPERTY(bool bluetoothBlocked READ isBluetoothBlocked WRITE setBluetoothBlocked NOTIFY bluetoothBlockedChanged)
85  Q_PROPERTY(AdapterPtr usableAdapter READ usableAdapter NOTIFY usableAdapterChanged)
86  Q_PROPERTY(QList<AdapterPtr> adapters READ adapters)
87  Q_PROPERTY(QList<DevicePtr> devices READ devices)
88  Q_PROPERTY(Rfkill *rfkill READ rfkill CONSTANT)
89 
90 public:
91  /**
92  * Creates a new Manager object.
93  *
94  * @param parent
95  */
96  explicit Manager(QObject *parent = nullptr);
97 
98  /**
99  * Destroys a Manager object.
100  */
101  ~Manager() override;
102 
103  /**
104  * Creates a new init job.
105  *
106  * @return init manager job
107  */
108  InitManagerJob *init();
109 
110  /**
111  * Returns whether the manager is initialized.
112  *
113  * @return true if manager is initialized
114  */
115  bool isInitialized() const;
116 
117  /**
118  * Returns whether the manager is operational.
119  *
120  * The manager is operational when initialization was successful and
121  * BlueZ system daemon is running.
122  *
123  * @return true if manager is operational
124  */
125  bool isOperational() const;
126 
127  /**
128  * Returns whether Bluetooth is operational.
129  *
130  * Bluetooth is operational when manager is operational and there is
131  * a valid usable adapter.
132  *
133  * @return true if Bluetooth is operational
134  */
135  bool isBluetoothOperational() const;
136 
137  /**
138  * Returns whether Bluetooth is blocked.
139  *
140  * Bluetooth is blocked if rfkill state for Bluetooth is either
141  * SOFT_BLOCKED or HARD_BLOCKED.
142  *
143  * @note This requires read access to /dev/rfkill.
144  *
145  * @return true if Bluetooth is blocked
146  */
147  bool isBluetoothBlocked() const;
148 
149  /**
150  * Sets a Bluetooth blocked state.
151  *
152  * This may fail either due to insufficient permissions or
153  * because rfkill state is HARD_BLOCKED. In that case,
154  * this function returns false.
155  *
156  * @note This requires write access to /dev/rfkill.
157  *
158  * @return true if unblocking rfkill devices succeeded
159  */
160  bool setBluetoothBlocked(bool blocked);
161 
162  /**
163  * Returns a usable adapter.
164  *
165  * Usable adapter is any adapter that is currently powered on.
166  *
167  * @return usable adapter
168  */
169  AdapterPtr usableAdapter() const;
170 
171  /**
172  * Returns a list of all adapters.
173  *
174  * @return list of adapters
175  */
176  QList<AdapterPtr> adapters() const;
177 
178  /**
179  * Returns a list of all devices.
180  *
181  * @return list of devices
182  */
183  QList<DevicePtr> devices() const;
184 
185  /**
186  * Attempts to start org.bluez service by D-Bus activation.
187  *
188  * Possible return values are 1 if the service was started,
189  * 2 if the service is already running or error if the service
190  * could not be started.
191  *
192  * @return quint32 pending call
193  */
194  static PendingCall *startService();
195 
196  /**
197  * Returns an adapter for specified address.
198  *
199  * @param address address of adapter (eg. "1C:E5:C3:BC:94:7E")
200  * @return null if there is no adapter with specified address
201  */
202  AdapterPtr adapterForAddress(const QString &address) const;
203 
204  /**
205  * Returns an adapter for specified UBI.
206  *
207  * @param ubi UBI of adapter (eg. "/org/bluez/hci0")
208  * @return null if there is no adapter with specified UBI
209  */
210  AdapterPtr adapterForUbi(const QString &ubi) const;
211 
212  /**
213  * Returns a device for specified address.
214  *
215  * @note There may be more devices with the same address (same device
216  * in multiple adapters). In this case, the first found device will
217  * be returned while preferring powered adapters in search.
218  *
219  * @param address address of device (eg. "40:79:6A:0C:39:75")
220  * @return null if there is no device with specified address
221  */
222  DevicePtr deviceForAddress(const QString &address) const;
223 
224  /**
225  * Returns a device for specified UBI.
226  *
227  * @param ubi UBI of device (eg. "/org/bluez/hci0/dev_40_79_6A_0C_39_75")
228  * @return null if there is no device with specified UBI
229  */
230  DevicePtr deviceForUbi(const QString &ubi) const;
231 
232  /**
233  * Registers agent.
234  *
235  * This agent will be used for for all actions triggered by the application.
236  * Eg. show a PIN code in pairing process.
237  *
238  * Possible errors: PendingCall::InvalidArguments, PendingCall::AlreadyExists
239  *
240  * @param agent agent to be registered
241  * @return void pending call
242  */
243  PendingCall *registerAgent(Agent *agent);
244 
245  /**
246  * Unregisters agent.
247  *
248  * Possible errors: PendingCall::DoesNotExist
249  *
250  * @param agent agent to be unregistered
251  * @return void pending call
252  */
253  PendingCall *unregisterAgent(Agent *agent);
254 
255  /**
256  * Requests default agent.
257  *
258  * This requests to make the application agent the default agent.
259  *
260  * Possible errors: PendingCall::DoesNotExist
261  *
262  * @param agent registered agent
263  * @return void pending call
264  */
265  PendingCall *requestDefaultAgent(Agent *agent);
266 
267  /**
268  * Registers profile.
269  *
270  * Possible errors: PendingCall::InvalidArguments, PendingCall::AlreadyExists
271  *
272  * @param profile profile to be registered
273  * @return void pending call
274  */
275  PendingCall *registerProfile(Profile *profile);
276 
277  /**
278  * Unregisters profile.
279  *
280  * Possible errors: PendingCall::DoesNotExist
281  *
282  * @param profile profile to be unregistered
283  * @return void pending call
284  */
285  PendingCall *unregisterProfile(Profile *profile);
286 
287 #if BLUEZQT_ENABLE_DEPRECATED_SINCE(5, 57)
288  /**
289  * Returns the media interface.
290  *
291  * @return media
292  * @deprecated since 5.57, use Adapter::media() instead.
293  */
294  BLUEZQT_DEPRECATED_VERSION(5, 57, "Use Adapter::media()")
295  MediaPtr media() const;
296 #endif
297 
298  Rfkill *rfkill() const;
299 
300 Q_SIGNALS:
301  /**
302  * Indicates that operational state have changed.
303  */
304  void operationalChanged(bool operational);
305 
306  /**
307  * Indicates that Bluetooth operational state have changed.
308  */
309  void bluetoothOperationalChanged(bool operational);
310 
311  /**
312  * Indicates that Bluetooth blocked state have changed.
313  */
314  void bluetoothBlockedChanged(bool blocked);
315 
316  /**
317  * Indicates that adapter was added.
318  */
319  void adapterAdded(AdapterPtr adapter);
320 
321  /**
322  * Indicates that adapter was removed.
323  */
324  void adapterRemoved(AdapterPtr adapter);
325 
326  /**
327  * Indicates that at least one of the adapter's properties have changed.
328  */
329  void adapterChanged(AdapterPtr adapter);
330 
331  /**
332  * Indicates that a new device was added (eg. found by discovery).
333  */
334  void deviceAdded(DevicePtr device);
335 
336  /**
337  * Indicates that a device was removed.
338  */
339  void deviceRemoved(DevicePtr device);
340 
341  /**
342  * Indicates that at least one of the device's properties have changed.
343  */
344  void deviceChanged(DevicePtr device);
345 
346  /**
347  * Indicates that usable adapter have changed.
348  */
349  void usableAdapterChanged(AdapterPtr adapter);
350 
351  /**
352  * Indicates that all adapters were removed.
353  */
354  void allAdaptersRemoved();
355 
356 private:
357  class ManagerPrivate *const d;
358 
359  friend class ManagerPrivate;
360  friend class InitManagerJobPrivate;
361 };
362 
363 } // namespace BluezQt
364 
365 #endif // BLUEZQT_MANAGER_H
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Thu Nov 30 2023 04:07:43 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.