1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qbluetoothlocaldevice.h"
5#include "qbluetoothlocaldevice_p.h"
6#include "qbluetoothaddress.h"
7
8#include <QtCore/QString>
9
10QT_BEGIN_NAMESPACE
11
12QT_IMPL_METATYPE_EXTERN_TAGGED(QBluetoothLocalDevice::Pairing, QBluetoothLocalDevice__Pairing)
13QT_IMPL_METATYPE_EXTERN_TAGGED(QBluetoothLocalDevice::HostMode, QBluetoothLocalDevice__HostMode)
14QT_IMPL_METATYPE_EXTERN_TAGGED(QBluetoothLocalDevice::Error, QBluetoothLocalDevice__Error)
15
16/*!
17 \class QBluetoothLocalDevice
18 \inmodule QtBluetooth
19 \brief The QBluetoothLocalDevice class enables access to the local Bluetooth
20 device.
21
22 \since 5.2
23
24 QBluetoothLocalDevice provides functions for getting and setting the state of local Bluetooth
25 devices.
26
27 On iOS, this class cannot be used because the platform does not expose
28 any data or API which may provide information on the local Bluetooth device.
29*/
30
31/*!
32 \enum QBluetoothLocalDevice::Pairing
33
34 This enum describes the pairing state between the two Bluetooth devices.
35
36 \value Unpaired The Bluetooth devices are not paired.
37 \value Paired The Bluetooth devices are paired. The system will prompt the user for
38 authorization when the remote device initiates a connection to the
39 local device.
40 \value AuthorizedPaired The Bluetooth devices are paired. The system will not prompt the user
41 for authorization when the remote device initiates a connection to the
42 local device.
43*/
44
45/*!
46 \enum QBluetoothLocalDevice::Error
47
48 This enum describes errors that maybe returned
49
50 \value NoError No known error
51 \value PairingError Error in pairing
52 \value [since 6.4] MissingPermissionsError The operating system requests
53 permissions which were not
54 granted by the user.
55 \value UnknownError Unknown error
56
57*/
58
59/*!
60 \enum QBluetoothLocalDevice::HostMode
61
62 This enum describes the most of the local Bluetooth device.
63
64 \value HostPoweredOff Power off the device
65 \value HostConnectable Remote Bluetooth devices can connect to the local Bluetooth device
66 if they have previously been paired with it or otherwise know its address. This powers up the
67 device if it was powered off.
68 \value HostDiscoverable Remote Bluetooth devices can discover the presence of the local
69 Bluetooth device. The device will also be connectable, and powered on. On Android, this mode can only be active
70 for a maximum of 5 minutes.
71 \value HostDiscoverableLimitedInquiry Remote Bluetooth devices can discover the presence of the local
72 Bluetooth device when performing a limited inquiry. This should be used for locating services that are
73 only made discoverable for a limited period of time. This can speed up discovery between gaming devices,
74 as service discovery can be skipped on devices not in LimitedInquiry mode. In this mode, the device will
75 be connectable and powered on, if required. This mode is is not supported on Android.
76
77 \note On \macos, it is not possible to set the \l hostMode(). The
78 reported host modes are limited to HostPoweredOff and HostConnectable.
79
80 \note On Windows, it is not possible to set the \l hostMode() to
81 HostDiscoverable or HostDiscoverableLimitedInquiry. Using these modes is
82 equivalent to HostConnectable.
83
84 \note Starting from Android 13 (API level 33) the HostPoweredOff state relies on
85 non-public Android API as the public one has been deprecated, see
86 (\l {https://developer.android.com/reference/android/bluetooth/BluetoothAdapter#disable()}
87 {disable()}). This may change in a future version of Android.
88
89 \note At least on Android 12 the device's Bluetooth visibility setting may dictate the result
90 of setting either HostDiscoverable or HostConnectable. For example if the visibility is set
91 \e off, it may not be possible to enter the HostDiscoverable mode, but HostConnectable will be
92 used instead. This may change in future version of Android.
93
94*/
95
96void registerQBluetoothLocalDeviceMetaType()
97{
98 static bool initDone = false;
99 if (!initDone) {
100 qRegisterMetaType<QBluetoothLocalDevice::HostMode>();
101 qRegisterMetaType<QBluetoothLocalDevice::Pairing>();
102 qRegisterMetaType<QBluetoothLocalDevice::Error>();
103 initDone = true;
104 }
105}
106
107#ifndef QT_OSX_BLUETOOTH
108
109/*!
110 Destroys the QBluetoothLocalDevice.
111*/
112QBluetoothLocalDevice::~QBluetoothLocalDevice()
113{
114 delete d_ptr;
115}
116
117/*!
118 Returns \c true if the QBluetoothLocalDevice represents an available local Bluetooth device;
119 otherwise return false.
120
121 If the local Bluetooth adapter represented by an instance of this class
122 is removed from the system (e.g. removal of the underlying Bluetooth dongle)
123 then this instance will become invalid. An already invalid QBluetoothLocalDevice instance
124 remains invalid even if the same Bluetooth adapter is returned to
125 the system.
126
127//! [android-permissions-valid]
128 \note Starting from Android 12 (API level 31), the construction of this class requires
129 \l {https://developer.android.com/guide/topics/connectivity/bluetooth/permissions}
130 {bluetooth runtime permissions} (\e BLUETOOTH_SCAN and \e BLUETOOTH_CONNECT). If the
131 permissions are not granted, the device will not be valid.
132//! [android-permissions-valid]
133
134 \sa allDevices()
135*/
136bool QBluetoothLocalDevice::isValid() const
137{
138 if (d_ptr)
139 return d_ptr->isValid();
140 return false;
141}
142
143#endif
144
145/*!
146 \fn void QBluetoothLocalDevice::setHostMode(QBluetoothLocalDevice::HostMode mode)
147
148 Sets the host mode of this local Bluetooth device to \a mode.
149
150 Some transitions such as turning the device on or off may take some time. Therefore
151 subsequent calls should only be made once the \l hostModeStateChanged() signal
152 has concluded the previous request. If this is ignored the result of such a series
153 of calls is not well defined.
154
155 \note Due to varying security policies on the supported platforms, this method may have
156 differing behaviors on the various platforms. For example the system may ask the user for
157 confirmation before turning Bluetooth on or off and not all host modes may be supported.
158 On \macos, it is not possbile to programmatically change the \l hostMode().
159 A user can only switch Bluetooth on/off in the System Preferences.
160 On Windows this method \e must be called from the UI thread because it might
161 require user confirmation.
162 Please refer to the platform specific Bluetooth documentation for details.
163*/
164
165/*!
166 \fn QBluetoothLocalDevice::HostMode QBluetoothLocalDevice::hostMode() const
167
168 Returns the current host mode of this local Bluetooth device. On \macos, it is either
169 HostPoweredOff or HostConnectable.
170*/
171
172/*!
173 \fn QBluetoothLocalDevice::name() const
174
175 Returns the name assgined by the user to this Bluetooth device.
176*/
177
178/*!
179 \fn QBluetoothLocalDevice::address() const
180
181 Returns the MAC address of this Bluetooth device.
182
183 \note On Android, this function always returns the constant
184 value \c {02:00:00:00:00:00} as local address starting with Android 6.0.
185 The programmatic access to the device's local MAC address was removed.
186*/
187
188/*!
189 \fn QList<QBluetoothLocalDevice> QBluetoothLocalDevice::allDevices()
190
191 Returns a list of all available local Bluetooth devices. On \macos, there is
192 only the "default" local device.
193*/
194
195/*!
196 \fn QBluetoothLocalDevice::powerOn()
197
198 Powers on the device after returning it to the hostMode() state, if it was powered off.
199
200 \note Due to varying security policies on the supported platforms, this method may have
201 differing behaviors on the various platforms. For example
202 the system may ask the user for confirmation before turning Bluetooth on or off.
203 On \macos it is not possible to power on/off Bluetooth.
204 Please refer to the platform specific Bluetooth documentation for details.
205*/
206
207/*!
208 \fn QBluetoothLocalDevice::QBluetoothLocalDevice(QObject *parent)
209 Constructs a QBluetoothLocalDevice with \a parent.
210
211 \include qbluetoothlocaldevice.cpp android-permissions-valid
212 \sa isValid()
213*/
214
215/*!
216 \fn QBluetoothLocalDevice::hostModeStateChanged(QBluetoothLocalDevice::HostMode state)
217 The \a state of the host has transitioned to a different HostMode.
218*/
219
220/*!
221 \fn QBluetoothLocalDevice::deviceConnected(const QBluetoothAddress &address)
222 \since 5.3
223
224 This signal is emitted when the local device establishes a connection to a remote device
225 with \a address.
226
227 \sa deviceDisconnected(), connectedDevices()
228*/
229
230/*!
231 \fn QBluetoothLocalDevice::deviceDisconnected(const QBluetoothAddress &address)
232 \since 5.3
233
234 This signal is emitted when the local device disconnects from a remote Bluetooth device
235 with \a address.
236
237 \sa deviceConnected(), connectedDevices()
238*/
239
240/*!
241 \fn QList<QBluetoothAddress> QBluetoothLocalDevice::connectedDevices() const
242 \since 5.3
243
244 Returns the list of connected devices. This list is different from the list of currently
245 paired devices.
246
247 On Android and \macos, it is not possible to retrieve a list of connected devices. It is only possible to
248 listen to (dis)connect changes. For convenience, this class monitors all connect
249 and disconnect events since its instanciation and returns the current list when calling this function.
250 Therefore it is possible that this function returns an empty list shortly after creating an
251 instance.
252
253 \sa deviceConnected(), deviceDisconnected()
254*/
255
256/*!
257 \fn QBluetoothLocalDevice::pairingStatus(const QBluetoothAddress &address) const
258
259 Returns the current bluetooth pairing status of \a address, if it's unpaired, paired, or paired and authorized.
260*/
261
262/*!
263 \fn QBluetoothLocalDevice::requestPairing(const QBluetoothAddress &address, Pairing pairing)
264
265 Set the \a pairing status with \a address. The results are returned by the signal, pairingFinished().
266
267 On Android and \macos, AuthorizedPaired is not possible and will have the same behavior as Paired.
268 On Windows the exact pairing mode decision is up to the operating system.
269
270 On \macos, it is not possible to unpair a device. If Unpaired is requested, \l pairingFinished()
271 is immediately emitted although the device remains paired. It is possible to request the pairing
272 for a previously unpaired device. In addition \l AuthorizedPaired has the same behavior as \l Paired.
273
274 Caution: creating a pairing may take minutes, and may require the user to acknowledge.
275*/
276
277/*!
278 \fn QBluetoothLocalDevice::pairingFinished(const QBluetoothAddress &address,
279 QBluetoothLocalDevice::Pairing pairing)
280
281 Pairing or unpairing has completed with \a address. Current pairing status is in \a pairing.
282 If the pairing request was not successful, this signal will not be emitted. The errorOccurred()
283 signal is emitted if the pairing request failed. The signal is only ever emitted for pairing
284 requests which have previously requested by calling \l requestPairing() of the current object
285 instance.
286*/
287
288/*!
289 \fn QBluetoothLocalDevice::errorOccurred(QBluetoothLocalDevice::Error error)
290 Signal emitted if there's an exceptional \a error while pairing.
291
292 \since 6.2
293*/
294
295/*!
296 \fn QBluetoothLocalDevice::QBluetoothLocalDevice(const QBluetoothAddress &address, QObject *parent = 0)
297
298 Construct new QBluetoothLocalDevice for \a address. If \a address is default constructed
299 the resulting local device selects the local default device.
300
301 \include qbluetoothlocaldevice.cpp android-permissions-valid
302 \sa isValid()
303*/
304
305QT_END_NAMESPACE
306
307#include "moc_qbluetoothlocaldevice.cpp"
308

source code of qtconnectivity/src/bluetooth/qbluetoothlocaldevice.cpp