BluezQt

manager.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_MANAGER_H
10#define BLUEZQT_MANAGER_H
11
12#include <QObject>
13
14#include "bluezqt_export.h"
15#include "rfkill.h"
16#include "types.h"
17
18#include <memory>
19
20namespace BluezQt
21{
22class Device;
23class Adapter;
24class Agent;
25class Profile;
26class PendingCall;
27class InitManagerJob;
28
29/**
30 * @class BluezQt::Manager manager.h <BluezQt/Manager>
31 *
32 * Bluetooth manager.
33 *
34 * The entry point to communicate with system BlueZ daemon.
35 *
36 * The typical usecase is to work with usableAdapter() (any powered adapter),
37 * but it is also possible to use specific adapter.
38 *
39 * You must call init() before other functions can be used.
40 *
41 * The only functions that can be used before initialization are two rfkill-related
42 * functions: isBluetoothBlocked() and setBluetoothBlocked().
43 *
44 * Example use in C++ code:
45 * @code
46 * BluezQt::Manager *manager = new BluezQt::Manager();
47 * BluezQt::InitManagerJob *job = manager->init();
48 * job->start();
49 * connect(job, &BluezQt::InitManagerJob::result, ...);
50 * @endcode
51 *
52 * In QML, manager is a singleton and initialization is started when first using
53 * the manager. You don't need to track initialized state, just use property binding.
54 *
55 * Example use in QML code:
56 * @code
57 * import QtQuick
58 * import org.kde.bluezqt as BluezQt
59 *
60 * Item {
61 * readonly property BluezQt.Manager manager: BluezQt.Manager
62 * property devicesCount: manager.devices.length
63 * property adaptersCount: manager.adapters.length
64 *
65 * Component.onCompleted: {
66 * console.log("Manager operational:", manager.operational)
67 * }
68 * }
69 * @endcode
70 *
71 * @note All communication with BlueZ daemon happens asynchronously. Almost all methods
72 * returns PendingCall to help track the call progress and to check for any errors.
73 *
74 * @note If manager is not operational, all methods that returns a PendingCall will fail
75 * with PendingCall::InternalError.
76 *
77 * @see InitManagerJob
78 */
79class BLUEZQT_EXPORT Manager : public QObject
80{
81 Q_OBJECT
82
83 Q_PROPERTY(bool initialized READ isInitialized)
84 Q_PROPERTY(bool operational READ isOperational NOTIFY operationalChanged)
85 Q_PROPERTY(bool bluetoothOperational READ isBluetoothOperational NOTIFY bluetoothOperationalChanged)
86 Q_PROPERTY(bool bluetoothBlocked READ isBluetoothBlocked WRITE setBluetoothBlocked NOTIFY bluetoothBlockedChanged)
87 Q_PROPERTY(AdapterPtr usableAdapter READ usableAdapter NOTIFY usableAdapterChanged)
88 Q_PROPERTY(QList<AdapterPtr> adapters READ adapters)
89 Q_PROPERTY(QList<DevicePtr> devices READ devices)
90 Q_PROPERTY(BluezQt::Rfkill *rfkill READ rfkill CONSTANT)
91
92public:
93 /**
94 * Creates a new Manager object.
95 *
96 * @param parent
97 */
98 explicit Manager(QObject *parent = nullptr);
99
100 /**
101 * Destroys a Manager object.
102 */
103 ~Manager() override;
104
105 /**
106 * Creates a new init job.
107 *
108 * @return init manager job
109 */
110 InitManagerJob *init();
111
112 /**
113 * Returns whether the manager is initialized.
114 *
115 * @return true if manager is initialized
116 */
117 bool isInitialized() const;
118
119 /**
120 * Returns whether the manager is operational.
121 *
122 * The manager is operational when initialization was successful and
123 * BlueZ system daemon is running.
124 *
125 * @return true if manager is operational
126 */
127 bool isOperational() const;
128
129 /**
130 * Returns whether Bluetooth is operational.
131 *
132 * Bluetooth is operational when manager is operational and there is
133 * a valid usable adapter.
134 *
135 * @return true if Bluetooth is operational
136 */
137 bool isBluetoothOperational() const;
138
139 /**
140 * Returns whether Bluetooth is blocked.
141 *
142 * Bluetooth is blocked if rfkill state for Bluetooth is either
143 * SOFT_BLOCKED or HARD_BLOCKED.
144 *
145 * @note This requires read access to /dev/rfkill.
146 *
147 * @return true if Bluetooth is blocked
148 */
149 bool isBluetoothBlocked() const;
150
151 /**
152 * Sets a Bluetooth blocked state.
153 *
154 * This may fail either due to insufficient permissions or
155 * because rfkill state is HARD_BLOCKED. In that case,
156 * this function returns false.
157 *
158 * @note This requires write access to /dev/rfkill.
159 */
160 void 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 Rfkill *rfkill() const;
288
289Q_SIGNALS:
290 /**
291 * Indicates that operational state have changed.
292 */
293 void operationalChanged(bool operational);
294
295 /**
296 * Indicates that Bluetooth operational state have changed.
297 */
298 void bluetoothOperationalChanged(bool operational);
299
300 /**
301 * Indicates that Bluetooth blocked state have changed.
302 */
303 void bluetoothBlockedChanged(bool blocked);
304
305 /**
306 * Indicates that adapter was added.
307 */
309
310 /**
311 * Indicates that adapter was removed.
312 */
314
315 /**
316 * Indicates that at least one of the adapter's properties have changed.
317 */
319
320 /**
321 * Indicates that a new device was added (eg. found by discovery).
322 */
323 void deviceAdded(DevicePtr device);
324
325 /**
326 * Indicates that a device was removed.
327 */
329
330 /**
331 * Indicates that at least one of the device's properties have changed.
332 */
334
335 /**
336 * Indicates that usable adapter have changed.
337 */
339
340 /**
341 * Indicates that all adapters were removed.
342 */
344
345private:
346 std::unique_ptr<class ManagerPrivate> const d;
347
348 friend class ManagerPrivate;
349 friend class InitManagerJobPrivate;
350};
351
352} // namespace BluezQt
353
354#endif // BLUEZQT_MANAGER_H
Init manager job.
Bluetooth manager.
void deviceAdded(DevicePtr device)
Indicates that a new device was added (eg.
void adapterChanged(AdapterPtr adapter)
Indicates that at least one of the adapter's properties have changed.
void adapterRemoved(AdapterPtr adapter)
Indicates that adapter was removed.
void bluetoothOperationalChanged(bool operational)
Indicates that Bluetooth operational state have changed.
void operationalChanged(bool operational)
Indicates that operational state have changed.
void usableAdapterChanged(AdapterPtr adapter)
Indicates that usable adapter have changed.
void bluetoothBlockedChanged(bool blocked)
Indicates that Bluetooth blocked state have changed.
~Manager() override
Destroys a Manager object.
void deviceChanged(DevicePtr device)
Indicates that at least one of the device's properties have changed.
void deviceRemoved(DevicePtr device)
Indicates that a device was removed.
void adapterAdded(AdapterPtr adapter)
Indicates that adapter was added.
void allAdaptersRemoved()
Indicates that all adapters were removed.
Pending method call.
Bluetooth profile.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:01:36 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.