QLowEnergyService Class

     //PreCondition: service details already discovered
     QLowEnergyCharacteristic batteryLevel = service->characteristic(
                 QBluetoothUuid::CharacteristicType::BatteryLevel);
     if (!batteryLevel.isValid())
         return;

     QLowEnergyDescriptor notification = batteryLevel.descriptor(
                 QBluetoothUuid::DescriptorType::ClientCharacteristicConfiguration);
     if (!notification.isValid())
         return;

     // establish hook into notifications
     connect(service, SIGNAL(characteristicChanged(QLowEnergyCharacteristic,QByteArray)),
             this, SLOT(characteristicChanged(QLowEnergyCharacteristic,QByteArray)));

     // enable notification
     service->writeDescriptor(notification, QByteArray::fromHex("0100"));

     // disable notification
     //service->writeDescriptor(notification, QByteArray::fromHex("0000"));

     // wait until descriptorWritten() signal is emitted
     // to confirm successful write

     QLowEnergyService *first, *second;
     QLowEnergyController control(remoteDevice);
     control.connectToDevice();

     // waiting for connection

     first = control.createServiceObject(QBluetoothUuid::ServiceClassUuid::BatteryService);
     second = control.createServiceObject(QBluetoothUuid::ServiceClassUuid::BatteryService);
     Q_ASSERT(first->state() == QLowEnergyService::RemoteService);
     Q_ASSERT(first->state() == second->state());

     first->discoverDetails();

     Q_ASSERT(first->state() == QLowEnergyService::RemoteServiceDiscovering);
     Q_ASSERT(first->state() == second->state());

Member Function Documentation

[signal] void QLowEnergyService::characteristicChanged(const QLowEnergyCharacteristic &characteristic, const QByteArray &newValue)

If the associated controller object is in the central role, this signal is emitted when the value of characteristic is changed by an event on the peripheral/device side. In that case, the signal emission implies that change notifications must have been activated via the characteristic's ClientCharacteristicConfiguration descriptor prior to the change event on the peripheral. More details on how this might be done can be found further above.

If the controller is in the peripheral role, that is, the service object was created via QLowEnergyController::addService, the signal is emitted when a GATT client has written the value of the characteristic using a write request or command.

The newValue parameter contains the updated value of the characteristic.

[signal, since 5.5] void QLowEnergyService::characteristicRead(const QLowEnergyCharacteristic &characteristic, const QByteArray &value)

This signal is emitted when the read request for characteristic successfully returned its value. The signal might be triggered by calling characteristicRead(). If the read operation is not successful, the error() signal is emitted using the CharacteristicReadError flag.

Note: This signal is only emitted for Central Role related use cases.

This function was introduced in Qt 5.5.

See also readCharacteristic().

[signal] void QLowEnergyService::characteristicWritten(const QLowEnergyCharacteristic &characteristic, const QByteArray &newValue)

This signal is emitted when the value of characteristic is successfully changed to newValue. The change must have been triggered by calling writeCharacteristic(). If the write operation is not successful, the error() signal is emitted using the CharacteristicWriteError flag.

The reception of the written signal can be considered as a sign that the target device received the to-be-written value and reports back the status of write request.

Note: If writeCharacteristic() is called using the WriteWithoutResponse mode, this signal and the error() are never emitted.

Note: This signal is only emitted for Central Role related use cases.

See also writeCharacteristic().

[signal, since 5.5] void QLowEnergyService::descriptorRead(const QLowEnergyDescriptor &descriptor, const QByteArray &value)

This signal is emitted when the read request for descriptor successfully returned its value. The signal might be triggered by calling descriptorRead(). If the read operation is not successful, the error() signal is emitted using the DescriptorReadError flag.

Note: This signal is only emitted for Central Role related use cases.

This function was introduced in Qt 5.5.

See also readDescriptor().

[signal] void QLowEnergyService::descriptorWritten(const QLowEnergyDescriptor &descriptor, const QByteArray &newValue)

This signal is emitted when the value of descriptor is successfully changed to newValue. If the associated controller object is in the central role, the change must have been caused by calling writeDescriptor(). Otherwise, the signal is the result of a write request or command from a GATT client to the respective descriptor.

See also writeDescriptor().

[signal, since 6.2] void QLowEnergyService::errorOccurred(QLowEnergyService::ServiceError newError)

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

This function was introduced in Qt 6.2.

[signal] void QLowEnergyService::stateChanged(QLowEnergyService::ServiceState newState)

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

See also state().

[virtual] QLowEnergyService::~QLowEnergyService()

Destroys the QLowEnergyService instance.

QLowEnergyCharacteristic QLowEnergyService::characteristic(const QBluetoothUuid &uuid) const

Returns the matching characteristic for uuid; otherwise an invalid characteristic.

The returned characteristic is invalid if this service instance's discoverDetails() was not yet called or there are no characteristics with a matching uuid.

See also characteristics().

QList<QLowEnergyCharacteristic> QLowEnergyService::characteristics() const

Returns all characteristics associated with this QLowEnergyService instance.

The returned list is empty if this service instance's discoverDetails() was not yet called or there are no known characteristics.

See also characteristic(), state(), and discoverDetails().

bool QLowEnergyService::contains(const QLowEnergyCharacteristic &characteristic) const

Returns true if characteristic belongs to this service; otherwise false.

A characteristic belongs to a service if characteristics() contains the characteristic.

bool QLowEnergyService::contains(const QLowEnergyDescriptor &descriptor) const

Returns true if descriptor belongs to this service; otherwise false.

void QLowEnergyService::discoverDetails(QLowEnergyService::DiscoveryMode mode = FullDiscovery)

Initiates discovery of the service's included services, characteristics, and their associated descriptors.

The discovery process is indicated via the stateChanged() signal. After creation, the service is in DiscoveryRequired state. When calling discoverDetails() it transitions to DiscoveringService. After completion of detail discovery, it transitions to ServiceDiscovered state. On each transition, the stateChanged() signal is emitted. Depending on the argument mode, a FullDiscovery or a SkipValueDiscovery is performed. In any case, all services and characteristics are discovered. A FullDiscovery proceeds and reads all characteristic values and descriptors. A SkipValueDiscovery does not read characteristic values and descriptors. A SkipValueDiscovery has two advantages. First, it is faster. Second, it circumvents bugs in some devices which wrongly advertise characteristics or descriptors as readable but nevertheless do not permit reads on them. This can trigger unpredictable behavior. After a SkipValueDiscovery, it is necessary to call readCharacteristic() / readDescriptor() and wait for them to finish successfully before accessing the value of a characteristic or descriptor.

The argument mode was introduced in Qt 6.2.

See also state().

QLowEnergyService::ServiceError QLowEnergyService::error() const

Returns the last occurred error or NoError.

QList<QBluetoothUuid> QLowEnergyService::includedServices() const

Returns the UUIDs of all services which are included by the current service.

The returned list is empty if this service instance's discoverDetails() was not yet called or there are no known characteristics.

It is possible that an included service contains yet another service. Such second level includes have to be obtained via their relevant first level QLowEnergyService instance. Technically, this could create a circular dependency.

QLowEnergyController::createServiceObject() should be used to obtain service instances for each of the UUIDs.

See also createServiceObject().

[since 5.5] void QLowEnergyService::readCharacteristic(const QLowEnergyCharacteristic &characteristic)

Reads the value of characteristic. If the operation is successful, the characteristicRead() signal is emitted; otherwise the CharacteristicReadError is set. In general, a characteristic is readable, if its QLowEnergyCharacteristic::Read property is set.

All descriptor and characteristic requests towards the same remote device are serialised. A queue is employed when issuing multiple requests at the same time. The queue does not eliminate duplicated read requests for the same characteristic.

A characteristic can only be read if the service is in the ServiceDiscovered state and belongs to the service. If one of these conditions is not true the QLowEnergyService::OperationError is set.

Note: Calling this function despite QLowEnergyCharacteristic::properties() reporting a non-readable property always attempts to read the characteristic's value on the hardware. If the hardware returns with an error the CharacteristicReadError is set.

This function was introduced in Qt 5.5.

See also characteristicRead() and writeCharacteristic().

[since 5.5] void QLowEnergyService::readDescriptor(const QLowEnergyDescriptor &descriptor)

Reads the value of descriptor. If the operation is successful, the descriptorRead() signal is emitted; otherwise the DescriptorReadError is set.

All descriptor and characteristic requests towards the same remote device are serialised. A queue is employed when issuing multiple requests at the same time. The queue does not eliminate duplicated read requests for the same descriptor.

A descriptor can only be read if the service is in the ServiceDiscovered state and the descriptor belongs to the service. If one of these conditions is not true the QLowEnergyService::OperationError is set.

This function was introduced in Qt 5.5.

See also descriptorRead() and writeDescriptor().

QString QLowEnergyService::serviceName() const

Returns the name of the service; otherwise an empty string.

The returned name can only be retrieved if serviceUuid() is a well-known UUID.

QBluetoothUuid QLowEnergyService::serviceUuid() const

Returns the UUID of the service; otherwise a null UUID.

QLowEnergyService::ServiceState QLowEnergyService::state() const

Returns the current state of the service.

If the device's service was instantiated for the first time, the object's state is DiscoveryRequired. The state of all service objects which point to the same service on the peripheral device are always equal. This is caused by the shared nature of the internal object data. Therefore any service object instance created after the first one has a state equal to already existing instances.

A service becomes invalid if the QLowEnergyController disconnects from the remote device. An invalid service retains its internal state at the time of the disconnect event. This implies that once the service details are discovered they can even be retrieved from an invalid service. This permits scenarios where the device connection is established, the service details are retrieved and the device immediately disconnected to permit the next device to connect to the peripheral device.

However, under normal circumstances the connection should remain to avoid repeated discovery of services and their details. The discovery may take a while and the client can subscribe to ongoing change notifications.

See also stateChanged().

QLowEnergyService::ServiceTypes QLowEnergyService::type() const

Returns the type of the service.

Note: The type attribute cannot be relied upon until the service has reached the ServiceDiscovered state. This field is initialised with PrimaryService.

Note: On Android, it is not possible to determine whether a service is a primary or secondary service. Therefore all services have the PrimaryService flag set.

void QLowEnergyService::writeCharacteristic(const QLowEnergyCharacteristic &characteristic, const QByteArray &newValue, QLowEnergyService::WriteMode mode = WriteWithResponse)

Writes newValue as value for the characteristic. The exact semantics depend on the role that the associated controller object is in.

Central role

The call results in a write request or command to a remote peripheral. If the operation is successful, the characteristicWritten() signal is emitted; otherwise the CharacteristicWriteError is set. Calling this function does not trigger the a characteristicChanged() signal unless the peripheral itself changes the value again after the current write request.

The mode parameter determines whether the remote device should send a write confirmation. The to-be-written characteristic must support the relevant write mode. The characteristic's supported write modes are indicated by its QLowEnergyCharacteristic::Write and QLowEnergyCharacteristic::WriteNoResponse properties.

All descriptor and characteristic write requests towards the same remote device are serialised. A queue is employed when issuing multiple write requests at the same time. The queue does not eliminate duplicated write requests for the same characteristic. For example, if the same descriptor is set to the value A and immediately afterwards to B, the two write request are executed in the given order.

Note: Currently, it is not possible to use signed or reliable writes as defined by the Bluetooth specification.

A characteristic can only be written if this service is in the ServiceDiscovered state and belongs to the service. If one of these conditions is not true the QLowEnergyService::OperationError is set.

Note: Calling this function despite QLowEnergyCharacteristic::properties() reporting a non-writable property always attempts to write to the hardware. Similarly, a WriteWithoutResponse is sent to the hardware too although the characteristic may only support WriteWithResponse. If the hardware returns with an error the CharacteristicWriteError is set.

Peripheral role

The call results in the value of the characteristic getting updated in the local database.

If a client is currently connected and it has enabled notifications or indications for the characteristic, the respective information will be sent. If a device has enabled notifications or indications for the characteristic and that device is currently not connected, but a bond exists between it and the local device, then the notification or indication will be sent on the next reconnection.

If there is a constraint on the length of the characteristic value and newValue does not adhere to that constraint, the behavior is unspecified.

Note: The mode argument is ignored in peripheral mode.

See also QLowEnergyService::characteristicWritten() and QLowEnergyService::readCharacteristic().

void QLowEnergyService::writeDescriptor(const QLowEnergyDescriptor &descriptor, const QByteArray &newValue)

Writes newValue as value for descriptor. The exact semantics depend on the role that the associated controller object is in.

Central role

A call to this function results in a write request to the remote device. If the operation is successful, the descriptorWritten() signal is emitted; otherwise the DescriptorWriteError is emitted.

All descriptor and characteristic requests towards the same remote device are serialised. A queue is employed when issuing multiple write requests at the same time. The queue does not eliminate duplicated write requests for the same descriptor. For example, if the same descriptor is set to the value A and immediately afterwards to B, the two write request are executed in the given order.

A descriptor can only be written if this service is in the ServiceDiscovered state, belongs to the service. If one of these conditions is not true the QLowEnergyService::OperationError is set.

Peripheral Role

The value is written to the local service database. If the contents of newValue are not valid for descriptor, the behavior is unspecified.

See also descriptorWritten() and readDescriptor().