Member Function Documentation

QLowEnergyController::QLowEnergyController(const QBluetoothDeviceInfo &remoteDeviceInfo, QObject *parent = Q_NULLPTR)

Constructs a new instance of this class with parent.

The remoteDeviceInfo must contain the details of the remote Bluetooth Low Energy device to which this object should attempt to connect later on.

The controller uses the local default Bluetooth adapter for the connection management.

This function was introduced in Qt 5.5.

QLowEnergyController::~QLowEnergyController()

Destroys the QLowEnergyController instance.

void QLowEnergyController::connectToDevice()

Connects to the remote Bluetooth Low Energy device.

This function does nothing if the controller's state() is not equal to UnconnectedState. The connected() signal is emitted once the connection is successfully established.

On Linux/BlueZ systems, it is not possible to connect to the same remote device using two instances of this class. The second call to this function may fail with an error. This limitation may be removed in future releases.

See also disconnectFromDevice().

[signal] void QLowEnergyController::connected()

This signal is emitted when the controller successfully connects to the remote Low Energy device.

QLowEnergyService *QLowEnergyController::createServiceObject(const QBluetoothUuid &serviceUuid, QObject *parent = Q_NULLPTR)

Creates an instance of the service represented by serviceUuid. The serviceUuid parameter must have been obtained via services().

The caller takes ownership of the returned pointer and may pass a parent parameter as default owner.

This function returns a null pointer if no service with serviceUuid can be found on the remote device or the controller is disconnected.

This function can return instances for secondary services too. The include relationships between services can be expressed via QLowEnergyService::includedServices().

If this function is called multiple times using the same service UUID, the returned QLowEnergyService instances share their internal data. Therefore if one of the instances initiates the discovery of the service details, the other instances automatically transition into the discovery state too.

See also services().

void QLowEnergyController::disconnectFromDevice()

Disconnects from the remote device.

Any QLowEnergyService, QLowEnergyCharacteristic or QLowEnergyDescriptor instance that resulted from the current connection is automatically invalidated. Once any of those objects become invalid they remain invalid even if this controller object reconnects.

This function does nothing if the controller is in the UnconnectedState.

See also connectToDevice().

[signal] void QLowEnergyController::disconnected()

This signal is emitted when the controller disconnects from the remote Low Energy device.

void QLowEnergyController::discoverServices()

Initiates the service discovery process.

The discovery progress is indicated via the serviceDiscovered() signal. The discoveryFinished() signal is emitted when the process has finished.

If the controller instance is not connected or the controller has performed the service discovery already this function will do nothing.

Note: Some platforms internally cache the service list of a device which was discovered in the past. This can be problematic if the remote device changed its list of services or their inclusion tree. If this behavior is a problem, the best workaround is to temporarily turn Bluetooth off. This causes a reset of the cache data. Currently Android exhibits such a cache behavior.

[signal] void QLowEnergyController::discoveryFinished()

This signal is emitted when the running service discovery finishes. The signal is not emitted if the discovery process finishes with an error.

See also discoverServices() and error().

Error QLowEnergyController::error() const

Returns the last occurred error or NoError.

[signal] void QLowEnergyController::error(QLowEnergyController::Error newError)

This signal is emitted when an error occurs. The newError parameter describes the error that occurred.

Note: Signal error is overloaded in this class. To connect to this one using the function pointer syntax, you must specify the signal type in a static cast, as shown in this example:

connect(lowEnergyController, static_cast<void(QLowEnergyController::*)(QLowEnergyController::Error)>(&QLowEnergyController::error),
    [=](QLowEnergyController::Error newError){ /* ... */ });

See also error() and errorString().

QString QLowEnergyController::errorString() const

Returns a textual representation of the last occurred error. The string is translated.

QBluetoothAddress QLowEnergyController::localAddress() const

Returns the address of the local Bluetooth adapter being used for the communication.

If this class instance was requested to use the default adapter but there was no default adapter when creating this class instance, the returned QBluetoothAddress will be null.

See also QBluetoothAddress::isNull().

QBluetoothAddress QLowEnergyController::remoteAddress() const

Returns the address of the remote Bluetooth Low Energy device.

RemoteAddressType QLowEnergyController::remoteAddressType() const

Returns the type of remoteAddress(). By default, this value is initialized to PublicAddress.

See also setRemoteAddressType().

QString QLowEnergyController::remoteName() const

Returns the name of the remote Bluetooth Low Energy device.

This function was introduced in Qt 5.5.

[signal] void QLowEnergyController::serviceDiscovered(const QBluetoothUuid &newService)

This signal is emitted each time a new service is discovered. The newService parameter contains the UUID of the found service.

See also discoverServices() and discoveryFinished().

QList<QBluetoothUuid> QLowEnergyController::services() const

Returns the list of services offered by the remote device.

The list contains all primary and secondary services.

See also createServiceObject().

void QLowEnergyController::setRemoteAddressType(RemoteAddressType type)

Sets the remote address type. The type is required to connect to the remote Bluetooth Low Energy device.

See also remoteAddressType().

ControllerState QLowEnergyController::state() const

Returns the current state of the controller.

See also stateChanged().

[signal] void QLowEnergyController::stateChanged(QLowEnergyController::ControllerState state)

This signal is emitted when the controller's state changes. The new state can also be retrieved via state().

See also state().