\inmodule QtBluetooth More...

#include <qlowenergycharacteristic.h>

Collaboration diagram for QLowEnergyCharacteristic:

Public Types
enum	PropertyType { Unknown = 0x00 , Broadcasting = 0x01 , Read = 0x02 , WriteNoResponse = 0x04 , Write = 0x08 , Notify = 0x10 , Indicate = 0x20 , WriteSigned = 0x40 , ExtendedProperty = 0x80 }
	This enum describes the properties of a characteristic. More...

Public Member Functions
	QLowEnergyCharacteristic ()
	Construct a new QLowEnergyCharacteristic.

	QLowEnergyCharacteristic (const QLowEnergyCharacteristic &other)
	Construct a new QLowEnergyCharacteristic that is a copy of other.

	~QLowEnergyCharacteristic ()
	Destroys the QLowEnergyCharacteristic object.

QLowEnergyCharacteristic &	operator= (const QLowEnergyCharacteristic &other)
	Makes a copy of other and assigns it to this \l QLowEnergyCharacteristic object.

QString	name () const
	Returns the human-readable name of the characteristic.

QBluetoothUuid	uuid () const
	Returns the UUID of the characteristic if \l isValid() returns `true`; otherwise a \l {QUuid::isNull()}{null} UUID.

QByteArray	value () const
	Returns the cached value of the characteristic.

QLowEnergyCharacteristic::PropertyTypes	properties () const
	Returns the properties of the characteristic.

QLowEnergyDescriptor	descriptor (const QBluetoothUuid &uuid) const
	Returns the descriptor for uuid or an invalid \l QLowEnergyDescriptor instance.

QList< QLowEnergyDescriptor >	descriptors () const
	Returns the list of descriptors belonging to this characteristic; otherwise an empty list.

QLowEnergyDescriptor	clientCharacteristicConfiguration () const
	Returns the Client Characteristic Configuration Descriptor or an invalid \l QLowEnergyDescriptor instance if no Client Characteristic Configuration Descriptor exists.

bool	isValid () const
	Returns `true` if the QLowEnergyCharacteristic object is valid, otherwise returns `false`.

Static Public Attributes
static const QByteArray	CCCDDisable = QByteArray::fromHex("0000")
	\variable QLowEnergyCharacteristic::CCCDDisable

static const QByteArray	CCCDEnableNotification = QByteArray::fromHex("0100")

static const QByteArray	CCCDEnableIndication = QByteArray::fromHex("0200")

Friends
class	QLowEnergyService

class	QLowEnergyControllerPrivate

class	QLowEnergyControllerPrivateAndroid

class	QLowEnergyControllerPrivateBluez

class	QLowEnergyControllerPrivateBluezDBus

class	QLowEnergyControllerPrivateCommon

class	QLowEnergyControllerPrivateDarwin

class	QLowEnergyControllerPrivateWinRT

bool	operator== (const QLowEnergyCharacteristic &a, const QLowEnergyCharacteristic &b)
	Returns `true` if a is equal to b, otherwise `false`.

bool	operator!= (const QLowEnergyCharacteristic &a, const QLowEnergyCharacteristic &b)
	Returns `true` if a and b are not equal; otherwise `false`.

Detailed Description

\inmodule QtBluetooth

The QLowEnergyCharacteristic class stores information about a Bluetooth Low Energy service characteristic.

Since: 5.4

QLowEnergyCharacteristic provides information about a Bluetooth Low Energy service characteristic's name(), uuid(), value(), properties(), and descriptors(). To obtain the characteristic's specification and information, it is necessary to connect to the device using the QLowEnergyService and QLowEnergyController classes.

The characteristic value may be written via the \l QLowEnergyService instance that manages the service to which this characteristic belongs. The \l {QLowEnergyService::writeCharacteristic()} function writes the new value. The \l {QLowEnergyService::characteristicWritten()} signal is emitted upon success. The value() of this object is automatically updated accordingly.

Characteristics may contain none, one or more descriptors. They can be individually retrieved using the \l descriptor() function. The \l descriptors() function returns all descriptors as a list. The general purpose of a descriptor is to add contextual information to the characteristic. For example, the descriptor might provide format or range information specifying how the characteristic's value is to be\ interpreted.

See also: QLowEnergyService, QLowEnergyDescriptor

Definition at line 18 of file qlowenergycharacteristic.h.

Member Enumeration Documentation

◆ PropertyType

enum QLowEnergyCharacteristic::PropertyType

This enum describes the properties of a characteristic.

\value Unknown The type is not known. \value Broadcasting Allow for the broadcasting of Generic Attributes (GATT) characteristic values. \value Read Allow the characteristic values to be read. \value WriteNoResponse Allow characteristic values without responses to be written. \value Write Allow for characteristic values to be written. \value Notify Permits notification of characteristic values. \value Indicate Permits indications of characteristic values. \value WriteSigned Permits signed writes of the GATT characteristic values. \value ExtendedProperty Additional characteristic properties are defined in the characteristic's extended properties descriptor.

It is not recommended to set both Notify and Indicate properties on the same characteristic as the underlying Bluetooth stack behaviors differ from platform to platform. Please see \l QLowEnergyCharacteristic::clientCharacteristicConfiguration

See also: properties()

Enumerator
Unknown
Broadcasting
Read
WriteNoResponse
Write
Notify
Indicate
WriteSigned
ExtendedProperty

Definition at line 22 of file qlowenergycharacteristic.h.

Constructor & Destructor Documentation

◆ QLowEnergyCharacteristic() [1/2]

QLowEnergyCharacteristic::QLowEnergyCharacteristic ( )

Construct a new QLowEnergyCharacteristic.

A default-constructed instance of this class is always invalid.

See also: isValid()

Definition at line 77 of file qlowenergycharacteristic.cpp.

◆ QLowEnergyCharacteristic() [2/2]

QLowEnergyCharacteristic::QLowEnergyCharacteristic ( const QLowEnergyCharacteristic & other )

Construct a new QLowEnergyCharacteristic that is a copy of other.

The two copies continue to share the same underlying data which does not detach upon write.

Definition at line 89 of file qlowenergycharacteristic.cpp.

References other().

Here is the call graph for this function:

◆ ~QLowEnergyCharacteristic()

QLowEnergyCharacteristic::~QLowEnergyCharacteristic ( )

Destroys the QLowEnergyCharacteristic object.

Definition at line 112 of file qlowenergycharacteristic.cpp.

Member Function Documentation

◆ clientCharacteristicConfiguration()

QLowEnergyDescriptor QLowEnergyCharacteristic::clientCharacteristicConfiguration ( ) const

Returns the Client Characteristic Configuration Descriptor or an invalid \l QLowEnergyDescriptor instance if no Client Characteristic Configuration Descriptor exists.

BTLE characteristics can support notifications and/or indications. In both cases, the peripheral will inform the central on each change of the characteristic's value. In the BTLE attribute protocol, notification messages are not confirmed by the central, while indications are confirmed. Notifications are considered faster, but unreliable, while indications are slower and more reliable.

If a characteristic supports notification or indication, these can be enabled by writing special bit patterns to the Client Characteristic Configuration Descriptor. For convenience, these bit patterns are provided as \l QLowEnergyCharacteristic::CCCDDisable, \l QLowEnergyCharacteristic::CCCDEnableNotification, and \l QLowEnergyCharacteristic::CCCDEnableIndication.

Enabling e.g. notification for a characteristic named mycharacteristic in a service called myservice could be done using the following code.

auto cccd = mycharacteristic.clientCharacteristicConfiguration();
if (!cccd.isValid()) {
    // your error handling
    return error;
}
myservice->writeDescriptor(cccd, QLowEnergyCharacteristic::CCCDEnableNotification);

Note: Calling characteristic.clientCharacteristicConfiguration() is equivalent to calling characteristic.descriptor(QBluetoothUuid::DescriptorType::ClientCharacteristicConfiguration).; It is not recommended to use both notifications and indications on the same characteristic. This applies to both server-side when setting up the characteristics, as well as client-side when enabling them. The bluetooth stack behavior differs from platform to platform and the cross-platform behavior will likely be inconsistent. As an example a Bluez Linux client might unconditionally try to enable both mechanisms if both are supported, whereas a macOS client might unconditionally enable just the notifications. If both are needed consider creating two separate characteristics.

Since: 6.2

See also: descriptor()

Definition at line 395 of file qlowenergycharacteristic.cpp.

References QBluetoothUuid::ClientCharacteristicConfiguration, and descriptor().

Here is the call graph for this function:

◆ descriptor()

QLowEnergyDescriptor QLowEnergyCharacteristic::descriptor ( const QBluetoothUuid & uuid ) const

Returns the descriptor for uuid or an invalid \l QLowEnergyDescriptor instance.

See also: descriptors()

Definition at line 324 of file qlowenergycharacteristic.cpp.

References QLowEnergyServicePrivate::characteristicList, QHash< QLowEnergyHandle, QLowEnergyServicePrivate::DescData >::const_iterator, QHash< QLowEnergyHandle, QLowEnergyServicePrivate::CharData >::const_iterator, QSharedPointer< T >::isNull(), uuid(), QLowEnergyServicePrivate::DescData::value, and QLowEnergyServicePrivate::CharData::value.

Referenced by clientCharacteristicConfiguration(), and descriptors().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ descriptors()

QList< QLowEnergyDescriptor > QLowEnergyCharacteristic::descriptors ( ) const

Returns the list of descriptors belonging to this characteristic; otherwise an empty list.

See also: descriptor()

Definition at line 406 of file qlowenergycharacteristic.cpp.

References QLowEnergyServicePrivate::characteristicList, descriptor(), and QSharedPointer< T >::isNull().

Here is the call graph for this function:

◆ isValid()

bool QLowEnergyCharacteristic::isValid ( ) const

Returns true if the QLowEnergyCharacteristic object is valid, otherwise returns false.

An invalid characteristic object is not associated with any service (default-constructed) or the associated service is no longer valid due to a disconnect from the underlying Bluetooth Low Energy device, for example. Once the object is invalid it cannot become valid anymore.

Note: If a \l QLowEnergyCharacteristic instance turns invalid due to a disconnect from the underlying device, the information encapsulated by the current instance remains as it was at the time of the disconnect. Therefore it can be retrieved after the disconnect event.

Definition at line 288 of file qlowenergycharacteristic.cpp.

References QLowEnergyService::InvalidService, QSharedPointer< T >::isNull(), and QLowEnergyServicePrivate::state.

Here is the call graph for this function:

◆ name()

QString QLowEnergyCharacteristic::name ( ) const

Returns the human-readable name of the characteristic.

The name is based on the characteristic's \l uuid() which must have been standardized. The complete list of characteristic types can be found under \l {https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicsHome.aspx}{Bluetooth.org Characteristics}.

The returned string is empty if the \l uuid() is unknown.

See also: QBluetoothUuid::characteristicToString()

Definition at line 128 of file qlowenergycharacteristic.cpp.

References QBluetoothUuid::characteristicToString(), and uuid().

Here is the call graph for this function:

◆ operator=()

QLowEnergyCharacteristic & QLowEnergyCharacteristic::operator= ( const QLowEnergyCharacteristic & other )

Makes a copy of other and assigns it to this \l QLowEnergyCharacteristic object.

The two copies continue to share the same service and controller details.

Definition at line 210 of file qlowenergycharacteristic.cpp.

References other().

Here is the call graph for this function:

◆ properties()

QLowEnergyCharacteristic::PropertyTypes QLowEnergyCharacteristic::properties ( ) const

Returns the properties of the characteristic.

The properties define the access permissions for the characteristic.

Definition at line 152 of file qlowenergycharacteristic.cpp.

References QLowEnergyServicePrivate::characteristicList, QSharedPointer< T >::isNull(), and Unknown.

Here is the call graph for this function:

◆ uuid()

QBluetoothUuid QLowEnergyCharacteristic::uuid ( ) const

Returns the UUID of the characteristic if \l isValid() returns true; otherwise a \l {QUuid::isNull()}{null} UUID.

Definition at line 138 of file qlowenergycharacteristic.cpp.

References QLowEnergyServicePrivate::characteristicList, and QSharedPointer< T >::isNull().

Referenced by descriptor(), name(), and QLowEnergyControllerPrivateBluezDBus::writeCharacteristic().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ value()

QByteArray QLowEnergyCharacteristic::value ( ) const

Returns the cached value of the characteristic.

If the characteristic's \l properties() permit writing of new values, the value can be updated using \l QLowEnergyService::writeCharacteristic().

The cache is updated during the associated service's \l {QLowEnergyService::discoverDetails()} {detail discovery}, a successful \l {QLowEnergyService::readCharacteristic()}{read}/\l {QLowEnergyService::writeCharacteristic()}{write} operation or when an update notification is received.

The returned \l QByteArray always remains empty if the characteristic does not have the \l {QLowEnergyCharacteristic::Read}{read permission}. In such cases only the \l QLowEnergyService::characteristicChanged() or \l QLowEnergyService::characteristicWritten() may provice information about the value of this characteristic.

Definition at line 178 of file qlowenergycharacteristic.cpp.

References QLowEnergyServicePrivate::characteristicList, QSharedPointer< T >::isNull(), and QByteArray().

Here is the call graph for this function:

Friends And Related Symbol Documentation

◆ operator!=

bool QLowEnergyCharacteristic::operator!=	(	const QLowEnergyCharacteristic &	a,
		const QLowEnergyCharacteristic &	b )

friend

Returns true if a and b are not equal; otherwise false.

Two QLowEnergyCharcteristic instances are considered to be equal if they refer to the same characteristic on the same remote Bluetooth Low Energy device or both instances have been default-constructed.

Definition at line 44 of file qlowenergycharacteristic.h.

◆ operator==

bool QLowEnergyCharacteristic::operator==	(	const QLowEnergyCharacteristic &	a,
		const QLowEnergyCharacteristic &	b )

friend

Returns true if a is equal to b, otherwise false.

Two \l QLowEnergyCharacteristic instances are considered to be equal if they refer to the same characteristic on the same remote Bluetooth Low Energy device or both instances have been default-constructed.

Definition at line 40 of file qlowenergycharacteristic.h.