1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtBluetooth module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#include "qbluetoothlocaldevice.h"
41#include "qbluetoothlocaldevice_p.h"
42#include "qbluetoothaddress.h"
43
44#include <QtCore/QString>
45
46QT_BEGIN_NAMESPACE
47
48/*!
49 \class QBluetoothLocalDevice
50 \inmodule QtBluetooth
51 \brief The QBluetoothLocalDevice class enables access to the local Bluetooth
52 device.
53
54 \since 5.2
55
56 QBluetoothLocalDevice provides functions for getting and setting the state of local Bluetooth
57 devices.
58
59 On iOS and Windows, this class cannot be used because the platform does not expose
60 any data or API which may provide information on the local Bluetooth device.
61*/
62
63/*!
64 \enum QBluetoothLocalDevice::Pairing
65
66 This enum describes the pairing state between the two Bluetooth devices.
67
68 \value Unpaired The Bluetooth devices are not paired.
69 \value Paired The Bluetooth devices are paired. The system will prompt the user for
70 authorization when the remote device initiates a connection to the
71 local device.
72 \value AuthorizedPaired The Bluetooth devices are paired. The system will not prompt the user
73 for authorization when the remote device initiates a connection to the
74 local device.
75*/
76
77/*!
78 \enum QBluetoothLocalDevice::Error
79
80 This enum describes errors that maybe returned
81
82 \value NoError No known error
83 \value PairingError Error in pairing
84 \value UnknownError Unknown error
85
86*/
87
88/*!
89 \enum QBluetoothLocalDevice::HostMode
90
91 This enum describes the most of the local Bluetooth device.
92
93 \value HostPoweredOff Power off the device
94 \value HostConnectable Remote Bluetooth devices can connect to the local Bluetooth device
95 if they have previously been paired with it or otherwise know its address. This powers up the
96 device if it was powered off.
97 \value HostDiscoverable Remote Bluetooth devices can discover the presence of the local
98 Bluetooth device. The device will also be connectable, and powered on. On Android, this mode can only be active
99 for a maximum of 5 minutes.
100 \value HostDiscoverableLimitedInquiry Remote Bluetooth devices can discover the presence of the local
101 Bluetooth device when performing a limited inquiry. This should be used for locating services that are
102 only made discoverable for a limited period of time. This can speed up discovery between gaming devices,
103 as service discovery can be skipped on devices not in LimitedInquiry mode. In this mode, the device will
104 be connectable and powered on, if required. This mode is is not supported on Android.
105 On \macos, it is not possible to set the \l hostMode() to HostConnectable or HostPoweredOff.
106
107*/
108
109void registerQBluetoothLocalDeviceMetaType()
110{
111 static bool initDone = false;
112 if (!initDone) {
113 qRegisterMetaType<QBluetoothLocalDevice::HostMode>();
114 qRegisterMetaType<QBluetoothLocalDevice::Pairing>();
115 qRegisterMetaType<QBluetoothLocalDevice::Error>();
116 initDone = true;
117 }
118}
119
120#ifndef QT_OSX_BLUETOOTH
121
122/*!
123 Destroys the QBluetoothLocalDevice.
124*/
125QBluetoothLocalDevice::~QBluetoothLocalDevice()
126{
127 delete d_ptr;
128}
129
130/*!
131 Returns \c true if the QBluetoothLocalDevice represents an available local Bluetooth device;
132 otherwise return false.
133
134 If the local Bluetooth adapter represented by an instance of this class
135 is removed from the system (e.g. removal of the underlying Bluetooth dongle)
136 then this instance will become invalid. An already invalid QBluetoothLocalDevice instance
137 remains invalid even if the same Bluetooth adapter is returned to
138 the system.
139
140 \sa allDevices()
141*/
142bool QBluetoothLocalDevice::isValid() const
143{
144 if (d_ptr)
145 return d_ptr->isValid();
146 return false;
147}
148
149#endif
150
151/*!
152 \fn void QBluetoothLocalDevice::setHostMode(QBluetoothLocalDevice::HostMode mode)
153
154 Sets the host mode of this local Bluetooth device to \a mode.
155
156 \note Due to varying security policies on the supported platforms, this method may have
157 differing behaviors on the various platforms. For example the system may ask the user for
158 confirmation before turning Bluetooth on or off and not all host modes may be supported.
159 On \macos, it is not possbile to programmatically change the \l hostMode().
160 A user can only switch Bluetooth on/off in the System Preferences.
161 Please refer to the platform specific Bluetooth documentation for details.
162*/
163
164/*!
165 \fn QBluetoothLocalDevice::HostMode QBluetoothLocalDevice::hostMode() const
166
167 Returns the current host mode of this local Bluetooth device. On \macos, it is either
168 HostPoweredOff or HostConnectable.
169*/
170
171/*!
172 \fn QBluetoothLocalDevice::name() const
173
174 Returns the name assgined by the user to this Bluetooth device.
175*/
176
177/*!
178 \fn QBluetoothLocalDevice::address() const
179
180 Returns the MAC address of this Bluetooth device.
181
182 \note On Android, this function always returns the constant
183 value \c {02:00:00:00:00:00} as local address starting with Android 6.0.
184 The programmatic access to the device's local MAC address was removed.
185*/
186
187/*!
188 \fn QList<QBluetoothLocalDevice> QBluetoothLocalDevice::allDevices()
189
190 Returns a list of all available local Bluetooth devices. On \macos, there is
191 only the "default" local device.
192*/
193
194/*!
195 \fn QBluetoothLocalDevice::powerOn()
196
197 Powers on the device after returning it to the hostMode() state, if it was powered off.
198
199 \note Due to varying security policies on the supported platforms, this method may have
200 differing behaviors on the various platforms. For example
201 the system may ask the user for confirmation before turning Bluetooth on or off.
202 On \macos it is not possible to power on/off Bluetooth.
203 Please refer to the platform specific Bluetooth documentation for details.
204*/
205
206/*!
207 \fn QBluetoothLocalDevice::QBluetoothLocalDevice(QObject *parent)
208 Constructs a QBluetoothLocalDevice with \a parent.
209*/
210
211/*!
212 \fn QBluetoothLocalDevice::hostModeStateChanged(QBluetoothLocalDevice::HostMode state)
213 The \a state of the host has transitioned to a different HostMode.
214*/
215
216/*!
217 \fn QBluetoothLocalDevice::deviceConnected(const QBluetoothAddress &address)
218 \since 5.3
219
220 This signal is emitted when the local device establishes a connection to a remote device
221 with \a address.
222
223 \sa deviceDisconnected(), connectedDevices()
224*/
225
226/*!
227 \fn QBluetoothLocalDevice::deviceDisconnected(const QBluetoothAddress &address)
228 \since 5.3
229
230 This signal is emitted when the local device disconnects from a remote Bluetooth device
231 with \a address.
232
233 \sa deviceConnected(), connectedDevices()
234*/
235
236/*!
237 \fn QList<QBluetoothAddress> QBluetoothLocalDevice::connectedDevices() const
238 \since 5.3
239
240 Returns the list of connected devices. This list is different from the list of currently
241 paired devices.
242
243 On Android and \macos, it is not possible to retrieve a list of connected devices. It is only possible to
244 listen to (dis)connect changes. For convenience, this class monitors all connect
245 and disconnect events since its instanciation and returns the current list when calling this function.
246 Therefore it is possible that this function returns an empty list shortly after creating an
247 instance.
248
249 \sa deviceConnected(), deviceDisconnected()
250*/
251
252/*!
253 \fn QBluetoothLocalDevice::pairingStatus(const QBluetoothAddress &address) const
254
255 Returns the current bluetooth pairing status of \a address, if it's unpaired, paired, or paired and authorized.
256*/
257
258/*!
259 \fn QBluetoothLocalDevice::pairingDisplayConfirmation(const QBluetoothAddress &address, QString pin)
260
261 Signal by some platforms to display a pairing confirmation dialog for \a address. The user
262 is asked to confirm the \a pin is the same on both devices. The \l pairingConfirmation() function
263 must be called to indicate if the user accepts or rejects the displayed pin.
264
265 This signal is only emitted for pairing requests issues by calling \l requestPairing().
266 On \macos, this method never gets called - there is a callback with a PIN (IOBluetooth),
267 but it expects immediate reply yes/no - and there is no time to show any dialog or compare PINs.
268
269 \sa pairingConfirmation()
270*/
271
272/*!
273 \fn QBluetoothLocalDevice::pairingConfirmation(bool confirmation)
274
275 To be called after getting a pairingDisplayConfirmation(). The \a confirmation parameter either
276 accepts the pairing or rejects it.
277
278 Accepting a pairing always refers to the last pairing request issued via \l requestPairing().
279
280 \note This function requires BLUETOOTH_PRIVILEGED permission on Android which is generally not
281 obtainable for 3rdparty. Android's default handler for pairing requests will do this on behalf
282 of the user and the application can ignore this call. Nevertheless the proper Android calls are made
283 in case the application does have the required permissions.
284*/
285
286/*!
287 \fn QBluetoothLocalDevice::pairingDisplayPinCode(const QBluetoothAddress &address, QString pin)
288
289 Signal by some platforms to display the \a pin to the user for \a address. The pin is automatically
290 generated, and does not need to be confirmed.
291
292 This signal is only emitted for pairing requests issues by calling \l requestPairing().
293*/
294
295/*!
296 \fn QBluetoothLocalDevice::requestPairing(const QBluetoothAddress &address, Pairing pairing)
297
298 Set the \a pairing status with \a address. The results are returned by the signal, pairingFinished().
299 On Android and \macos, AuthorizedPaired is not possible and will have the same behavior as Paired.
300
301 On \macos, it is not possible to unpair a device. If Unpaired is requested, \l pairingFinished()
302 is immediately emitted although the device remains paired. It is possible to request the pairing
303 for a previously unpaired device. In addition \l AuthorizedPaired has the same behavior as \l Paired.
304
305 Caution: creating a pairing may take minutes, and may require the user to acknowledge.
306*/
307
308/*!
309 \fn QBluetoothLocalDevice::pairingFinished(const QBluetoothAddress &address, QBluetoothLocalDevice::Pairing pairing)
310
311 Pairing or unpairing has completed with \a address. Current pairing status is in \a pairing.
312 If the pairing request was not successful, this signal will not be emitted. The error() signal
313 is emitted if the pairing request failed. The signal is only ever emitted for pairing requests
314 which have previously requested by calling \l requestPairing() of the current object instance.
315*/
316
317/*!
318 \fn QBluetoothLocalDevice::error(QBluetoothLocalDevice::Error error)
319 Signal emitted if there's an exceptional \a error while pairing.
320*/
321
322/*!
323 \fn QBluetoothLocalDevice::QBluetoothLocalDevice(const QBluetoothAddress &address, QObject *parent = 0)
324
325 Construct new QBluetoothLocalDevice for \a address. If \a address is default constructed
326 the resulting local device selects the local default device.
327*/
328
329QT_END_NAMESPACE
330
331#include "moc_qbluetoothlocaldevice.cpp"
332

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