QBluetoothLocalDevice Class
The QBluetoothLocalDevice class enables access to the local Bluetooth device. More...
| Header: | #include <QBluetoothLocalDevice> |
| qmake: | QT += bluetooth |
| Since: | Qt 5.2 |
| Inherits: | QObject |
This class was introduced in Qt 5.2.
Public Types
| enum | Error { NoError, PairingError, UnknownError } |
| enum | HostMode { HostPoweredOff, HostConnectable, HostDiscoverable, HostDiscoverableLimitedInquiry } |
| enum | Pairing { Unpaired, Paired, AuthorizedPaired } |
Public Functions
| QBluetoothLocalDevice(const QBluetoothAddress &address, QObject *parent = 0) | |
| QBluetoothLocalDevice(QObject *parent = nullptr) | |
| virtual | ~QBluetoothLocalDevice() |
| QBluetoothAddress | address() const |
| QList<QBluetoothAddress> | connectedDevices() const |
| QBluetoothLocalDevice::HostMode | hostMode() const |
| bool | isValid() const |
| QString | name() const |
| QBluetoothLocalDevice::Pairing | pairingStatus(const QBluetoothAddress &address) const |
| void | powerOn() |
| void | requestPairing(const QBluetoothAddress &address, QBluetoothLocalDevice::Pairing pairing) |
| void | setHostMode(QBluetoothLocalDevice::HostMode mode) |
Public Slots
| void | pairingConfirmation(bool confirmation) |
Signals
| void | deviceConnected(const QBluetoothAddress &address) |
| void | deviceDisconnected(const QBluetoothAddress &address) |
| void | error(QBluetoothLocalDevice::Error error) |
| void | hostModeStateChanged(QBluetoothLocalDevice::HostMode state) |
| void | pairingDisplayConfirmation(const QBluetoothAddress &address, QString pin) |
| void | pairingDisplayPinCode(const QBluetoothAddress &address, QString pin) |
| void | pairingFinished(const QBluetoothAddress &address, QBluetoothLocalDevice::Pairing pairing) |
Static Public Members
| QList<QBluetoothHostInfo> | allDevices() |
Detailed Description
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.
Member Type Documentation
enum QBluetoothLocalDevice::Error
This enum describes errors that maybe returned
| Constant | Value | Description |
|---|---|---|
QBluetoothLocalDevice::NoError | 0 | No known error |
QBluetoothLocalDevice::PairingError | 1 | Error in pairing |
QBluetoothLocalDevice::UnknownError | 100 | Unknown error |
enum QBluetoothLocalDevice::HostMode
This enum describes the most of the local Bluetooth device.
| Constant | Value | Description |
|---|---|---|
QBluetoothLocalDevice::HostPoweredOff | 0 | Power off the device |
QBluetoothLocalDevice::HostConnectable | 1 | 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. |
QBluetoothLocalDevice::HostDiscoverable | 2 | 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. |
QBluetoothLocalDevice::HostDiscoverableLimitedInquiry | 3 | 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 hostMode() to HostConnectable or HostPoweredOff. |
Note: Starting from Android 13 (API level 33) the HostPoweredOff state relies on non-public Android API as the public one has been deprecated, see (disable()). This may change in a future version of Android.
Note: At least on Android 12 the device's Bluetooth visibility setting may dictate the result of setting either HostDiscoverable or HostConnectable. For example if the visibility is set off, it may not be possible to enter the HostDiscoverable mode, but HostConnectable will be used instead. This may change in future version of Android.
enum QBluetoothLocalDevice::Pairing
This enum describes the pairing state between the two Bluetooth devices.
| Constant | Value | Description |
|---|---|---|
QBluetoothLocalDevice::Unpaired | 0 | The Bluetooth devices are not paired. |
QBluetoothLocalDevice::Paired | 1 | The Bluetooth devices are paired. The system will prompt the user for authorization when the remote device initiates a connection to the local device. |
QBluetoothLocalDevice::AuthorizedPaired | 2 | 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. |
Member Function Documentation
QBluetoothLocalDevice::QBluetoothLocalDevice(const QBluetoothAddress &address, QObject *parent = 0)
Construct new QBluetoothLocalDevice for address. If address is default constructed the resulting local device selects the local default device.
Note: Starting from Android 12 (API level 31), the construction of this class requires bluetooth runtime permissions (BLUETOOTH_SCAN and BLUETOOTH_CONNECT). If the permissions are not granted, the device will not be valid.
See also isValid().
QBluetoothLocalDevice::QBluetoothLocalDevice(QObject *parent = nullptr)
Constructs a QBluetoothLocalDevice with parent.
Note: Starting from Android 12 (API level 31), the construction of this class requires bluetooth runtime permissions (BLUETOOTH_SCAN and BLUETOOTH_CONNECT). If the permissions are not granted, the device will not be valid.
See also isValid().
[signal] void QBluetoothLocalDevice::deviceConnected(const QBluetoothAddress &address)
This signal is emitted when the local device establishes a connection to a remote device with address.
This function was introduced in Qt 5.3.
See also deviceDisconnected() and connectedDevices().
[signal] void QBluetoothLocalDevice::deviceDisconnected(const QBluetoothAddress &address)
This signal is emitted when the local device disconnects from a remote Bluetooth device with address.
This function was introduced in Qt 5.3.
See also deviceConnected() and connectedDevices().
[signal] void QBluetoothLocalDevice::error(QBluetoothLocalDevice::Error error)
Signal emitted if there's an exceptional error while pairing.
[signal] void QBluetoothLocalDevice::hostModeStateChanged(QBluetoothLocalDevice::HostMode state)
The state of the host has transitioned to a different HostMode.
[slot] void QBluetoothLocalDevice::pairingConfirmation(bool confirmation)
To be called after getting a pairingDisplayConfirmation(). The confirmation parameter either accepts the pairing or rejects it.
Accepting a pairing always refers to the last pairing request issued via 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.
[signal] void QBluetoothLocalDevice::pairingDisplayConfirmation(const QBluetoothAddress &address, QString pin)
Signal by some platforms to display a pairing confirmation dialog for address. The user is asked to confirm the pin is the same on both devices. The 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 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.
See also pairingConfirmation().
[signal] void QBluetoothLocalDevice::pairingDisplayPinCode(const QBluetoothAddress &address, QString pin)
Signal by some platforms to display the pin to the user for address. The pin is automatically generated, and does not need to be confirmed.
This signal is only emitted for pairing requests issues by calling requestPairing().
[signal] void QBluetoothLocalDevice::pairingFinished(const QBluetoothAddress &address, QBluetoothLocalDevice::Pairing pairing)
Pairing or unpairing has completed with address. Current pairing status is in 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 requestPairing() of the current object instance.
[virtual] QBluetoothLocalDevice::~QBluetoothLocalDevice()
Destroys the QBluetoothLocalDevice.
QBluetoothAddress QBluetoothLocalDevice::address() const
Returns the MAC address of this Bluetooth device.
Note: On Android, this function always returns the constant value 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.
[static] QList<QBluetoothHostInfo> QBluetoothLocalDevice::allDevices()
Returns a list of all available local Bluetooth devices. On macOS, there is only the "default" local device.
QList<QBluetoothAddress> QBluetoothLocalDevice::connectedDevices() const
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.
This function was introduced in Qt 5.3.
See also deviceConnected() and deviceDisconnected().
QBluetoothLocalDevice::HostMode QBluetoothLocalDevice::hostMode() const
Returns the current host mode of this local Bluetooth device. On macOS, it is either HostPoweredOff or HostConnectable.
See also setHostMode().
bool QBluetoothLocalDevice::isValid() const
Returns 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.
Note: Starting from Android 12 (API level 31), the construction of this class requires bluetooth runtime permissions (BLUETOOTH_SCAN and BLUETOOTH_CONNECT). If the permissions are not granted, the device will not be valid.
See also allDevices().
QString QBluetoothLocalDevice::name() const
Returns the name assgined by the user to this Bluetooth device.
QBluetoothLocalDevice::Pairing QBluetoothLocalDevice::pairingStatus(const QBluetoothAddress &address) const
Returns the current bluetooth pairing status of address, if it's unpaired, paired, or paired and authorized.
void 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.
void QBluetoothLocalDevice::requestPairing(const QBluetoothAddress &address, QBluetoothLocalDevice::Pairing pairing)
Set the pairing status with 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, pairingFinished() is immediately emitted although the device remains paired. It is possible to request the pairing for a previously unpaired device. In addition AuthorizedPaired has the same behavior as Paired.
Caution: creating a pairing may take minutes, and may require the user to acknowledge.
void QBluetoothLocalDevice::setHostMode(QBluetoothLocalDevice::HostMode mode)
Sets the host mode of this local Bluetooth device to 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 hostMode(). A user can only switch Bluetooth on/off in the System Preferences. Please refer to the platform specific Bluetooth documentation for details.
See also hostMode().
© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
