Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
Loading...
Searching...
No Matches
Public Types | Signals | Public Member Functions | Static Public Member Functions | List of all members
QBluetoothLocalDevice Class Reference

\inmodule QtBluetooth More...

#include <qbluetoothlocaldevice.h>

+ Inheritance diagram for QBluetoothLocalDevice:
+ Collaboration diagram for QBluetoothLocalDevice:

Public Types

enum  Pairing { Unpaired , Paired , AuthorizedPaired }
 This enum describes the pairing state between the two Bluetooth devices. More...
 
enum  HostMode { HostPoweredOff , HostConnectable , HostDiscoverable , HostDiscoverableLimitedInquiry }
 This enum describes the most of the local Bluetooth device. More...
 
enum  Error { NoError , PairingError , MissingPermissionsError , UnknownError = 100 }
 This enum describes errors that maybe returned. More...
 

Signals

void hostModeStateChanged (QBluetoothLocalDevice::HostMode state)
 The state of the host has transitioned to a different HostMode.
 
void deviceConnected (const QBluetoothAddress &address)
 
void deviceDisconnected (const QBluetoothAddress &address)
 
void pairingFinished (const QBluetoothAddress &address, QBluetoothLocalDevice::Pairing pairing)
 Pairing or unpairing has completed with address.
 
void errorOccurred (QBluetoothLocalDevice::Error error)
 Signal emitted if there's an exceptional error while pairing.
 
- Signals inherited from QObject
void destroyed (QObject *=nullptr)
 This signal is emitted immediately before the object obj is destroyed, after any instances of QPointer have been notified, and cannot be blocked.
 
void objectNameChanged (const QString &objectName, QPrivateSignal)
 This signal is emitted after the object's name has been changed.
 

Public Member Functions

 QBluetoothLocalDevice (QObject *parent=nullptr)
 Constructs a QBluetoothLocalDevice with parent.
 
 QBluetoothLocalDevice (const QBluetoothAddress &address, QObject *parent=nullptr)
 Construct new QBluetoothLocalDevice for address.
 
virtual ~QBluetoothLocalDevice ()
 Destroys the QBluetoothLocalDevice.
 
bool isValid () const
 
void requestPairing (const QBluetoothAddress &address, Pairing pairing)
 Set the pairing status with address.
 
Pairing pairingStatus (const QBluetoothAddress &address) const
 Returns the current bluetooth pairing status of address, if it's unpaired, paired, or paired and authorized.
 
void setHostMode (QBluetoothLocalDevice::HostMode mode)
 Sets the host mode of this local Bluetooth device to mode.
 
HostMode hostMode () const
 Returns the current host mode of this local Bluetooth device.
 
QList< QBluetoothAddress > connectedDevices () const
 
void powerOn ()
 Powers on the device after returning it to the hostMode() state, if it was powered off.
 
QString name () const
 Returns the name assgined by the user to this Bluetooth device.
 
QBluetoothAddress address () const
 Returns the MAC address of this Bluetooth device.
 
- Public Member Functions inherited from QObject
Q_INVOKABLE QObject (QObject *parent=nullptr)
 Constructs an object with parent object parent.
 
virtual ~QObject ()
 Destroys the object, deleting all its child objects.
 
virtual bool event (QEvent *event)
 This virtual function receives events to an object and should return true if the event e was recognized and processed.
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 Filters events if this object has been installed as an event filter for the watched object.
 
QString objectName () const
 
Q_WEAK_OVERLOAD void setObjectName (const QString &name)
 Sets the object's name to name.
 
void setObjectName (QAnyStringView name)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
QBindable< QString > bindableObjectName ()
 
bool isWidgetType () const
 Returns true if the object is a widget; otherwise returns false.
 
bool isWindowType () const
 Returns true if the object is a window; otherwise returns false.
 
bool isQuickItemType () const
 Returns true if the object is a QQuickItem; otherwise returns false.
 
bool signalsBlocked () const noexcept
 Returns true if signals are blocked; otherwise returns false.
 
bool blockSignals (bool b) noexcept
 If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it).
 
QThread * thread () const
 Returns the thread in which the object lives.
 
bool moveToThread (QThread *thread QT6_DECL_NEW_OVERLOAD_TAIL)
 Changes the thread affinity for this object and its children and returns true on success.
 
int startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
 This is an overloaded function that will start a timer of type timerType and a timeout of interval milliseconds.
 
int startTimer (std::chrono::nanoseconds time, Qt::TimerType timerType=Qt::CoarseTimer)
 
void killTimer (int id)
 Kills the timer with timer identifier, id.
 
void killTimer (Qt::TimerId id)
 
template<typename T >
T findChild (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 Returns the child of this object that can be cast into type T and that is called name, or \nullptr if there is no such object.
 
template<typename T >
QList< T > findChildren (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects.
 
template<typename T >
T findChild (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
template<typename T >
QList< T > findChildren (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
const QObjectList & children () const
 Returns a list of child objects.
 
void setParent (QObject *parent)
 Makes the object a child of parent.
 
void installEventFilter (QObject *filterObj)
 Installs an event filter filterObj on this object.
 
void removeEventFilter (QObject *obj)
 Removes an event filter object obj from this object.
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const
 
bool disconnect (const char *signal=nullptr, const QObject *receiver=nullptr, const char *member=nullptr) const
 
bool disconnect (const QObject *receiver, const char *member=nullptr) const
 
void dumpObjectTree () const
 Dumps a tree of children to the debug output.
 
void dumpObjectInfo () const
 Dumps information about signal connections, etc.
 
bool setProperty (const char *name, const QVariant &value)
 Sets the value of the object's name property to value.
 
bool setProperty (const char *name, QVariant &&value)
 
QVariant property (const char *name) const
 Returns the value of the object's name property.
 
QList< QByteArray > dynamicPropertyNames () const
 
QBindingStorage * bindingStorage ()
 
const QBindingStorage * bindingStorage () const
 
QObject * parent () const
 Returns a pointer to the parent object.
 
bool inherits (const char *classname) const
 Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false.
 

Static Public Member Functions

static QList< QBluetoothHostInfo > allDevices ()
 Returns a list of all available local Bluetooth devices.
 
- Static Public Member Functions inherited from QObject
static QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
 \threadsafe
 
static QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)
 
template<typename Func1 , typename Func2 >
static QMetaObject::Connection connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const typename QtPrivate::ContextTypeForFunctor< Func2 >::ContextType *context, Func2 &&slot, Qt::ConnectionType type=Qt::AutoConnection)
 
template<typename Func1 , typename Func2 >
static QMetaObject::Connection connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, Func2 &&slot)
 
static bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member)
 \threadsafe
 
static bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member)
 
static bool disconnect (const QMetaObject::Connection &)
 Disconnect a connection.
 
template<typename Func1 , typename Func2 >
static bool disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const typename QtPrivate::FunctionPointer< Func2 >::Object *receiver, Func2 slot)
 
template<typename Func1 >
static bool disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const QObject *receiver, void **zero)
 

Additional Inherited Members

- Public Slots inherited from QObject
void deleteLater ()
 \threadsafe
 
- Protected Member Functions inherited from QObject
QObject * sender () const
 Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns \nullptr.
 
int senderSignalIndex () const
 
int receivers (const char *signal) const
 Returns the number of receivers connected to the signal.
 
bool isSignalConnected (const QMetaMethod &signal) const
 
virtual void timerEvent (QTimerEvent *event)
 This event handler can be reimplemented in a subclass to receive timer events for the object.
 
virtual void childEvent (QChildEvent *event)
 This event handler can be reimplemented in a subclass to receive child events.
 
virtual void customEvent (QEvent *event)
 This event handler can be reimplemented in a subclass to receive custom events.
 
virtual void connectNotify (const QMetaMethod &signal)
 
virtual void disconnectNotify (const QMetaMethod &signal)
 
 QObject (QObjectPrivate &dd, QObject *parent=nullptr)
 
- Protected Attributes inherited from QObject
QScopedPointer< QObjectData > d_ptr
 
- Properties inherited from QObject
QString objectName
 the name of this object
 
- Related Symbols inherited from QObject
 Returns the given object cast to type T if the object is of type T (or of a subclass); otherwise returns \nullptr.
 
 
 
 \macro Q_CLASSINFO(Name, Value)
 

Detailed Description

\inmodule QtBluetooth

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, this class cannot be used because the platform does not expose any data or API which may provide information on the local Bluetooth device.

Definition at line 19 of file qbluetoothlocaldevice.h.

Member Enumeration Documentation

◆ Error

enum QBluetoothLocalDevice::Error

This enum describes errors that maybe returned.

\value NoError No known error \value PairingError Error in pairing \value [since 6.4] MissingPermissionsError The operating system requests permissions which were not granted by the user. \value UnknownError Unknown error

Enumerator
NoError 
PairingError 
MissingPermissionsError 
UnknownError 

Definition at line 39 of file qbluetoothlocaldevice.h.

◆ HostMode

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.

Note
On \macos, it is not possible to set the \l hostMode() to HostConnectable or HostPoweredOff.
On Windows, it is not possible to set the \l hostMode() to HostDiscoverable or HostDiscoverableLimitedInquiry. Using these modes is equivalent to HostConnectable.
Starting from Android 13 (API level 33) the HostPoweredOff state relies on non-public Android API as the public one has been deprecated, see (\l {https://developer.android.com/reference/android/bluetooth/BluetoothAdapter#disable()} {disable()}). This may change in a future version of Android.
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.
Enumerator
HostPoweredOff 
HostConnectable 
HostDiscoverable 
HostDiscoverableLimitedInquiry 

Definition at line 31 of file qbluetoothlocaldevice.h.

◆ Pairing

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.

Enumerator
Unpaired 
Paired 
AuthorizedPaired 

Definition at line 24 of file qbluetoothlocaldevice.h.

Constructor & Destructor Documentation

◆ QBluetoothLocalDevice() [1/2]

QBluetoothLocalDevice::QBluetoothLocalDevice ( QObject * parent = nullptr)
explicit

Constructs a QBluetoothLocalDevice with parent.

android-permissions-valid

See also
isValid()

Definition at line 146 of file qbluetoothlocaldevice_android.cpp.

◆ QBluetoothLocalDevice() [2/2]

QBluetoothLocalDevice::QBluetoothLocalDevice ( const QBluetoothAddress & address,
QObject * parent = nullptr )
explicit

Construct new QBluetoothLocalDevice for address.

If address is default constructed the resulting local device selects the local default device.

android-permissions-valid

See also
isValid()

Definition at line 152 of file qbluetoothlocaldevice_android.cpp.

◆ ~QBluetoothLocalDevice()

QBluetoothLocalDevice::~QBluetoothLocalDevice ( )
virtual

Destroys the QBluetoothLocalDevice.

Definition at line 112 of file qbluetoothlocaldevice.cpp.

Member Function Documentation

◆ address()

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.

Definition at line 166 of file qbluetoothlocaldevice_android.cpp.

References address(), and toString().

Referenced by address(), and connectedDevices().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ allDevices()

QList< QBluetoothHostInfo > QBluetoothLocalDevice::allDevices ( )
static

Returns a list of all available local Bluetooth devices.

On \macos, there is only the "default" local device.

Definition at line 287 of file qbluetoothlocaldevice_android.cpp.

References QBluetoothPermission::Access, ensureAndroidPermission(), getDefaultBluetoothAdapter(), info, o, and qCWarning.

Referenced by QBluetoothDeviceDiscoveryAgent::QBluetoothDeviceDiscoveryAgent(), QBluetoothServiceDiscoveryAgent::QBluetoothServiceDiscoveryAgent(), QBluetoothServiceDiscoveryAgentPrivate::QBluetoothServiceDiscoveryAgentPrivate(), QLowEnergyControllerPrivate::isValidLocalAdapter(), QBluetoothServer::listen(), QBluetoothServiceInfoPrivate::registerService(), and QBluetoothServer::serverAddress().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ connectedDevices()

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.

See also
deviceConnected(), deviceDisconnected()

Definition at line 378 of file qbluetoothlocaldevice_android.cpp.

References address(), connectedDevices(), and i.

Referenced by connectedDevices().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ deviceConnected

QBluetoothLocalDevice::deviceConnected ( const QBluetoothAddress & address)
signal
Since
5.3

This signal is emitted when the local device establishes a connection to a remote device with address.

See also
deviceDisconnected(), connectedDevices()

◆ deviceDisconnected

QBluetoothLocalDevice::deviceDisconnected ( const QBluetoothAddress & address)
signal
Since
5.3

This signal is emitted when the local device disconnects from a remote Bluetooth device with address.

See also
deviceConnected(), connectedDevices()

Referenced by QtBluezPeripheralConnectionManager::QtBluezPeripheralConnectionManager().

+ Here is the caller graph for this function:

◆ errorOccurred

QBluetoothLocalDevice::errorOccurred ( QBluetoothLocalDevice::Error error)
signal

Signal emitted if there's an exceptional error while pairing.

Since
6.2

Referenced by powerOn(), QBluetoothLocalDevicePrivate::requestPairing(), and setHostMode().

+ Here is the caller graph for this function:

◆ hostMode()

QBluetoothLocalDevice::HostMode QBluetoothLocalDevice::hostMode ( ) const

Returns the current host mode of this local Bluetooth device.

On \macos, it is either HostPoweredOff or HostConnectable.

Definition at line 267 of file qbluetoothlocaldevice_android.cpp.

References HostConnectable, HostDiscoverable, and HostPoweredOff.

Referenced by powerOn(), and setHostMode().

+ Here is the caller graph for this function:

◆ hostModeStateChanged

QBluetoothLocalDevice::hostModeStateChanged ( QBluetoothLocalDevice::HostMode state)
signal

The state of the host has transitioned to a different HostMode.

◆ isValid()

bool QBluetoothLocalDevice::isValid ( ) const 
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.

! [android-permissions-valid]

Note
Starting from Android 12 (API level 31), the construction of this class requires \l {https://developer.android.com/guide/topics/connectivity/bluetooth/permissions} {bluetooth runtime permissions} (BLUETOOTH_SCAN and BLUETOOTH_CONNECT). If the permissions are not granted, the device will not be valid. ! [android-permissions-valid] 
\sa allDevices()

Definition at line 136 of file qbluetoothlocaldevice.cpp.

References QBluetoothLocalDevicePrivate::isValid().

+ Here is the call graph for this function:

◆ name()

QString QBluetoothLocalDevice::name ( ) const

Returns the name assgined by the user to this Bluetooth device.

Definition at line 158 of file qbluetoothlocaldevice_android.cpp.

References toString().

+ Here is the call graph for this function:

◆ pairingFinished

QBluetoothLocalDevice::pairingFinished ( const QBluetoothAddress & address,
QBluetoothLocalDevice::Pairing pairing )
signal

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 errorOccurred() 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.

◆ pairingStatus()

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.

Definition at line 353 of file qbluetoothlocaldevice_android.cpp.

References Paired, and Unpaired.

Referenced by QWinRTLowEnergyConnectionHandler::connectToDevice(), and requestPairing().

+ Here is the caller graph for this function:

◆ powerOn()

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.

Definition at line 176 of file qbluetoothlocaldevice_android.cpp.

References emit, errorOccurred(), hostMode(), HostPoweredOff, qCWarning, and UnknownError.

+ Here is the call graph for this function:

◆ requestPairing()

void QBluetoothLocalDevice::requestPairing ( const QBluetoothAddress & address,
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 Windows the exact pairing mode decision is up to the operating system.

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.

Definition at line 308 of file qbluetoothlocaldevice_android.cpp.

References AuthorizedPaired, QMetaObject::invokeMethod(), Paired, PairingError, pairingStatus(), Q_ARG, qCWarning, qMakePair(), and Qt::QueuedConnection.

+ Here is the call graph for this function:

◆ setHostMode()

void QBluetoothLocalDevice::setHostMode ( QBluetoothLocalDevice::HostMode mode)

Sets the host mode of this local Bluetooth device to mode.

Some transitions such as turning the device on or off may take some time. Therefore subsequent calls should only be made once the \l hostModeStateChanged() signal has concluded the previous request. If this is ignored the result of such a series of calls is not well defined.

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. On Windows this method must be called from the UI thread because it might require user confirmation. Please refer to the platform specific Bluetooth documentation for details.

Definition at line 197 of file qbluetoothlocaldevice_android.cpp.

References QBluetoothPermission::Advertise, emit, ensureAndroidPermission(), errorOccurred(), HostConnectable, HostDiscoverable, HostDiscoverableLimitedInquiry, hostMode(), HostPoweredOff, MissingPermissionsError, qCWarning, setHostMode(), and UnknownError.

Referenced by setHostMode().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:
The documentation for this class was generated from the following files: