| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the QtBluetooth module of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:LGPL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Lesser General Public License Usage |
| ** Alternatively, this file may be used under the terms of the GNU Lesser |
| ** General Public License version 3 as published by the Free Software |
| ** Foundation and appearing in the file LICENSE.LGPL3 included in the |
| ** packaging of this file. Please review the following information to |
| ** ensure the GNU Lesser General Public License version 3 requirements |
| ** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. |
| ** |
| ** GNU General Public License Usage |
| ** Alternatively, this file may be used under the terms of the GNU |
| ** General Public License version 2.0 or (at your option) the GNU General |
| ** Public license version 3 or any later version approved by the KDE Free |
| ** Qt Foundation. The licenses are as published by the Free Software |
| ** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 |
| ** included in the packaging of this file. Please review the following |
| ** information to ensure the GNU General Public License requirements will |
| ** be met: https://www.gnu.org/licenses/gpl-2.0.html and |
| ** https://www.gnu.org/licenses/gpl-3.0.html. |
| ** |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| #include "qbluetoothlocaldevice.h" |
| #include "qbluetoothlocaldevice_p.h" |
| #include "qbluetoothaddress.h" |
| |
| #include <QtCore/QString> |
| |
| QT_BEGIN_NAMESPACE |
| |
| /*! |
| \class QBluetoothLocalDevice |
| \inmodule QtBluetooth |
| \brief The QBluetoothLocalDevice class enables access to the local Bluetooth |
| device. |
| |
| \since 5.2 |
| |
| QBluetoothLocalDevice provides functions for getting and setting the state of local Bluetooth |
| devices. |
| |
| On iOS and Windows, this class cannot be used because the platform does not expose |
| any data or API which may provide information on the local Bluetooth device. |
| */ |
| |
| /*! |
| \enum QBluetoothLocalDevice::Pairing |
| |
| This enum describes the pairing state between the two Bluetooth devices. |
| |
| \value Unpaired The Bluetooth devices are not paired. |
| \value Paired The Bluetooth devices are paired. The system will prompt the user for |
| authorization when the remote device initiates a connection to the |
| local device. |
| \value AuthorizedPaired The Bluetooth devices are paired. The system will not prompt the user |
| for authorization when the remote device initiates a connection to the |
| local device. |
| */ |
| |
| /*! |
| \enum QBluetoothLocalDevice::Error |
| |
| This enum describes errors that maybe returned |
| |
| \value NoError No known error |
| \value PairingError Error in pairing |
| \value UnknownError Unknown error |
| |
| */ |
| |
| /*! |
| \enum QBluetoothLocalDevice::HostMode |
| |
| This enum describes the most of the local Bluetooth device. |
| |
| \value HostPoweredOff Power off the device |
| \value HostConnectable Remote Bluetooth devices can connect to the local Bluetooth device |
| if they have previously been paired with it or otherwise know its address. This powers up the |
| device if it was powered off. |
| \value HostDiscoverable Remote Bluetooth devices can discover the presence of the local |
| Bluetooth device. The device will also be connectable, and powered on. On Android, this mode can only be active |
| for a maximum of 5 minutes. |
| \value HostDiscoverableLimitedInquiry Remote Bluetooth devices can discover the presence of the local |
| Bluetooth device when performing a limited inquiry. This should be used for locating services that are |
| only made discoverable for a limited period of time. This can speed up discovery between gaming devices, |
| as service discovery can be skipped on devices not in LimitedInquiry mode. In this mode, the device will |
| be connectable and powered on, if required. This mode is is not supported on Android. |
| On \macos, it is not possible to set the \l hostMode() to HostConnectable or HostPoweredOff. |
| |
| */ |
| |
| void registerQBluetoothLocalDeviceMetaType() |
| { |
| static bool initDone = false; |
| if (!initDone) { |
| qRegisterMetaType<QBluetoothLocalDevice::HostMode>(); |
| qRegisterMetaType<QBluetoothLocalDevice::Pairing>(); |
| qRegisterMetaType<QBluetoothLocalDevice::Error>(); |
| initDone = true; |
| } |
| } |
| |
| #ifndef QT_OSX_BLUETOOTH |
| |
| /*! |
| Destroys the QBluetoothLocalDevice. |
| */ |
| QBluetoothLocalDevice::~QBluetoothLocalDevice() |
| { |
| delete d_ptr; |
| } |
| |
| /*! |
| Returns \c true if the QBluetoothLocalDevice represents an available local Bluetooth device; |
| otherwise return false. |
| |
| If the local Bluetooth adapter represented by an instance of this class |
| is removed from the system (e.g. removal of the underlying Bluetooth dongle) |
| then this instance will become invalid. An already invalid QBluetoothLocalDevice instance |
| remains invalid even if the same Bluetooth adapter is returned to |
| the system. |
| |
| \sa allDevices() |
| */ |
| bool QBluetoothLocalDevice::isValid() const |
| { |
| if (d_ptr) |
| return d_ptr->isValid(); |
| return false; |
| } |
| |
| #endif |
| |
| /*! |
| \fn void QBluetoothLocalDevice::setHostMode(QBluetoothLocalDevice::HostMode mode) |
| |
| Sets the host mode of this local Bluetooth device to \a mode. |
| |
| \note Due to varying security policies on the supported platforms, this method may have |
| differing behaviors on the various platforms. For example the system may ask the user for |
| confirmation before turning Bluetooth on or off and not all host modes may be supported. |
| On \macos, it is not possbile to programmatically change the \l hostMode(). |
| A user can only switch Bluetooth on/off in the System Preferences. |
| Please refer to the platform specific Bluetooth documentation for details. |
| */ |
| |
| /*! |
| \fn QBluetoothLocalDevice::HostMode QBluetoothLocalDevice::hostMode() const |
| |
| Returns the current host mode of this local Bluetooth device. On \macos, it is either |
| HostPoweredOff or HostConnectable. |
| */ |
| |
| /*! |
| \fn QBluetoothLocalDevice::name() const |
| |
| Returns the name assgined by the user to this Bluetooth device. |
| */ |
| |
| /*! |
| \fn QBluetoothLocalDevice::address() const |
| |
| Returns the MAC address of this Bluetooth device. |
| |
| \note On Android, this function always returns the constant |
| value \c {02:00:00:00:00:00} as local address starting with Android 6.0. |
| The programmatic access to the device's local MAC address was removed. |
| */ |
| |
| /*! |
| \fn QList<QBluetoothLocalDevice> QBluetoothLocalDevice::allDevices() |
| |
| Returns a list of all available local Bluetooth devices. On \macos, there is |
| only the "default" local device. |
| */ |
| |
| /*! |
| \fn QBluetoothLocalDevice::powerOn() |
| |
| Powers on the device after returning it to the hostMode() state, if it was powered off. |
| |
| \note Due to varying security policies on the supported platforms, this method may have |
| differing behaviors on the various platforms. For example |
| the system may ask the user for confirmation before turning Bluetooth on or off. |
| On \macos it is not possible to power on/off Bluetooth. |
| Please refer to the platform specific Bluetooth documentation for details. |
| */ |
| |
| /*! |
| \fn QBluetoothLocalDevice::QBluetoothLocalDevice(QObject *parent) |
| Constructs a QBluetoothLocalDevice with \a parent. |
| */ |
| |
| /*! |
| \fn QBluetoothLocalDevice::hostModeStateChanged(QBluetoothLocalDevice::HostMode state) |
| The \a state of the host has transitioned to a different HostMode. |
| */ |
| |
| /*! |
| \fn QBluetoothLocalDevice::deviceConnected(const QBluetoothAddress &address) |
| \since 5.3 |
| |
| This signal is emitted when the local device establishes a connection to a remote device |
| with \a address. |
| |
| \sa deviceDisconnected(), connectedDevices() |
| */ |
| |
| /*! |
| \fn QBluetoothLocalDevice::deviceDisconnected(const QBluetoothAddress &address) |
| \since 5.3 |
| |
| This signal is emitted when the local device disconnects from a remote Bluetooth device |
| with \a address. |
| |
| \sa deviceConnected(), connectedDevices() |
| */ |
| |
| /*! |
| \fn QList<QBluetoothAddress> QBluetoothLocalDevice::connectedDevices() const |
| \since 5.3 |
| |
| Returns the list of connected devices. This list is different from the list of currently |
| paired devices. |
| |
| On Android and \macos, it is not possible to retrieve a list of connected devices. It is only possible to |
| listen to (dis)connect changes. For convenience, this class monitors all connect |
| and disconnect events since its instanciation and returns the current list when calling this function. |
| Therefore it is possible that this function returns an empty list shortly after creating an |
| instance. |
| |
| \sa deviceConnected(), deviceDisconnected() |
| */ |
| |
| /*! |
| \fn QBluetoothLocalDevice::pairingStatus(const QBluetoothAddress &address) const |
| |
| Returns the current bluetooth pairing status of \a address, if it's unpaired, paired, or paired and authorized. |
| */ |
| |
| /*! |
| \fn QBluetoothLocalDevice::pairingDisplayConfirmation(const QBluetoothAddress &address, QString pin) |
| |
| Signal by some platforms to display a pairing confirmation dialog for \a address. The user |
| is asked to confirm the \a pin is the same on both devices. The \l pairingConfirmation() function |
| must be called to indicate if the user accepts or rejects the displayed pin. |
| |
| This signal is only emitted for pairing requests issues by calling \l requestPairing(). |
| On \macos, this method never gets called - there is a callback with a PIN (IOBluetooth), |
| but it expects immediate reply yes/no - and there is no time to show any dialog or compare PINs. |
| |
| \sa pairingConfirmation() |
| */ |
| |
| /*! |
| \fn QBluetoothLocalDevice::pairingConfirmation(bool confirmation) |
| |
| To be called after getting a pairingDisplayConfirmation(). The \a confirmation parameter either |
| accepts the pairing or rejects it. |
| |
| Accepting a pairing always refers to the last pairing request issued via \l requestPairing(). |
| |
| \note This function requires BLUETOOTH_PRIVILEGED permission on Android which is generally not |
| obtainable for 3rdparty. Android's default handler for pairing requests will do this on behalf |
| of the user and the application can ignore this call. Nevertheless the proper Android calls are made |
| in case the application does have the required permissions. |
| */ |
| |
| /*! |
| \fn QBluetoothLocalDevice::pairingDisplayPinCode(const QBluetoothAddress &address, QString pin) |
| |
| Signal by some platforms to display the \a pin to the user for \a address. The pin is automatically |
| generated, and does not need to be confirmed. |
| |
| This signal is only emitted for pairing requests issues by calling \l requestPairing(). |
| */ |
| |
| /*! |
| \fn QBluetoothLocalDevice::requestPairing(const QBluetoothAddress &address, Pairing pairing) |
| |
| Set the \a pairing status with \a address. The results are returned by the signal, pairingFinished(). |
| On Android and \macos, AuthorizedPaired is not possible and will have the same behavior as Paired. |
| |
| On \macos, it is not possible to unpair a device. If Unpaired is requested, \l pairingFinished() |
| is immediately emitted although the device remains paired. It is possible to request the pairing |
| for a previously unpaired device. In addition \l AuthorizedPaired has the same behavior as \l Paired. |
| |
| Caution: creating a pairing may take minutes, and may require the user to acknowledge. |
| */ |
| |
| /*! |
| \fn QBluetoothLocalDevice::pairingFinished(const QBluetoothAddress &address, QBluetoothLocalDevice::Pairing pairing) |
| |
| Pairing or unpairing has completed with \a address. Current pairing status is in \a pairing. |
| If the pairing request was not successful, this signal will not be emitted. The error() signal |
| is emitted if the pairing request failed. The signal is only ever emitted for pairing requests |
| which have previously requested by calling \l requestPairing() of the current object instance. |
| */ |
| |
| /*! |
| \fn QBluetoothLocalDevice::error(QBluetoothLocalDevice::Error error) |
| Signal emitted if there's an exceptional \a error while pairing. |
| */ |
| |
| /*! |
| \fn QBluetoothLocalDevice::QBluetoothLocalDevice(const QBluetoothAddress &address, QObject *parent = 0) |
| |
| Construct new QBluetoothLocalDevice for \a address. If \a address is default constructed |
| the resulting local device selects the local default device. |
| */ |
| |
| QT_END_NAMESPACE |
| |
| #include "moc_qbluetoothlocaldevice.cpp" |