\inmodule QtBluetooth More...

#include <qlowenergyservice.h>

Inheritance diagram for QLowEnergyService:

Collaboration diagram for QLowEnergyService:

Public Types
enum	ServiceType { PrimaryService = 0x0001 , IncludedService = 0x0002 }
	This enum describes the type of the service. More...

enum	ServiceError { NoError = 0 , OperationError , CharacteristicWriteError , DescriptorWriteError , UnknownError , CharacteristicReadError , DescriptorReadError }
	This enum describes all possible error conditions during the service's existence. More...

enum	ServiceState { InvalidService = 0 , RemoteService , RemoteServiceDiscovering , RemoteServiceDiscovered , LocalService }
	This enum describes the \l state() of the service object. More...

enum	DiscoveryMode { FullDiscovery , SkipValueDiscovery }
	This enum lists service discovery modes. More...

enum	WriteMode { WriteWithResponse = 0 , WriteWithoutResponse , WriteSigned }
	This enum describes the mode to be used when writing a characteristic value. More...

Signals
void	stateChanged (QLowEnergyService::ServiceState newState)
	This signal is emitted when the service's state changes.

void	characteristicChanged (const QLowEnergyCharacteristic &info, const QByteArray &value)
	If the associated controller object is in the \l {QLowEnergyController::CentralRole}{central} role, this signal is emitted when the value of characteristic is changed by an event on the peripheral/device side.

void	characteristicRead (const QLowEnergyCharacteristic &info, const QByteArray &value)
	This signal is emitted when the read request for characteristic successfully returned its value.

void	characteristicWritten (const QLowEnergyCharacteristic &info, const QByteArray &value)
	This signal is emitted when the value of characteristic is successfully changed to newValue.

void	descriptorRead (const QLowEnergyDescriptor &info, const QByteArray &value)
	This signal is emitted when the read request for descriptor successfully returned its value.

void	descriptorWritten (const QLowEnergyDescriptor &info, const QByteArray &value)
	This signal is emitted when the value of descriptor is successfully changed to newValue.

void	errorOccurred (QLowEnergyService::ServiceError error)
	This signal is emitted when an error occurrs.

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
	~QLowEnergyService ()
	Destroys the \l QLowEnergyService instance.

QList< QBluetoothUuid >	includedServices () const
	Returns the UUIDs of all services which are included by the current service.

QLowEnergyService::ServiceTypes	type () const
	Returns the type of the service.

QLowEnergyService::ServiceState	state () const
	Returns the current state of the service.

QLowEnergyCharacteristic	characteristic (const QBluetoothUuid &uuid) const
	Returns the matching characteristic for uuid; otherwise an invalid characteristic.

QList< QLowEnergyCharacteristic >	characteristics () const
	Returns all characteristics associated with this `QLowEnergyService` instance.

QBluetoothUuid	serviceUuid () const
	Returns the UUID of the service; otherwise a null UUID.

QString	serviceName () const
	Returns the name of the service; otherwise an empty string.

void	discoverDetails (DiscoveryMode mode=FullDiscovery)
	Initiates discovery of the service's included services, characteristics, and their associated descriptors.

ServiceError	error () const
	Returns the last occurred error or \l NoError.

bool	contains (const QLowEnergyCharacteristic &characteristic) const
	Returns `true` if characteristic belongs to this service; otherwise `false`.

void	readCharacteristic (const QLowEnergyCharacteristic &characteristic)
	Reads the value of characteristic.

void	writeCharacteristic (const QLowEnergyCharacteristic &characteristic, const QByteArray &newValue, WriteMode mode=WriteWithResponse)
	Writes newValue as value for the characteristic.

bool	contains (const QLowEnergyDescriptor &descriptor) const
	Returns `true` if descriptor belongs to this service; otherwise `false`.

void	readDescriptor (const QLowEnergyDescriptor &descriptor)
	Reads the value of descriptor.

void	writeDescriptor (const QLowEnergyDescriptor &descriptor, const QByteArray &newValue)
	Writes newValue as value for descriptor.

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`.

Friends
class	QLowEnergyController

class	QLowEnergyControllerPrivate

class	QLowEnergyControllerPrivateBluez

class	QLowEnergyControllerPrivateAndroid

class	QLowEnergyControllerPrivateDarwin

Additional Inherited Members
Public Slots inherited from QObject
void	deleteLater ()
	\threadsafe

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)

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
template< class T > T	qobject_cast (const QObject *object)
	Returns the given object cast to type T if the object is of type T (or of a subclass); otherwise returns \nullptr.

template< typename T > T	qFindChildqFindChildren (const QObject *obj, const QString &name)()

template< typename T > QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QString &name)()

	QObjectList
	\macro Q_CLASSINFO(Name, Value)

Detailed Description

\inmodule QtBluetooth

The QLowEnergyService class represents an individual service on a Bluetooth Low Energy Device.

Since: 5.4

QLowEnergyService provides access to the details of Bluetooth Low Energy services. The class facilitates the discovery and publification of service details, permits reading and writing of the contained data and notifies about data changes.

Definition at line 14 of file qlowenergyservice.h.

Member Enumeration Documentation

◆ DiscoveryMode

enum QLowEnergyService::DiscoveryMode

This enum lists service discovery modes.

All modes discover the characteristics of the service and the descriptors of the characteristics. The modes differ in whether characteristic values and descriptors are read.

\value FullDiscovery During a full discovery, all characteristics are discovered. All characteristic values and descriptors are read. \value SkipValueDiscovery During a minimal discovery, all characteristics are discovered. Characteristic values and descriptors are not read.

See also: discoverDetails()

Since: 6.2

Enumerator
FullDiscovery
SkipValueDiscovery

Definition at line 61 of file qlowenergyservice.h.

◆ ServiceError

enum QLowEnergyService::ServiceError

This enum describes all possible error conditions during the service's existence.

The \l error() function returns the last occurred error.

\value NoError No error has occurred. \value OperationError An operation was attempted while the service was not ready. An example might be the attempt to write to the service while it was not yet in the \l ServiceDiscovered \l state() or the service is invalid due to a loss of connection to the peripheral device. \value [since 5.5] CharacteristicReadError An attempt to read a characteristic value failed. For example, it might be triggered in response to a call to \l readCharacteristic(). \value CharacteristicWriteError An attempt to write a new value to a characteristic failed. For example, it might be triggered when attempting to write to a read-only characteristic. \value [since 5.5] DescriptorReadError An attempt to read a descriptor value failed. For example, it might be triggered in response to a call to \l readDescriptor(). \value DescriptorWriteError An attempt to write a new value to a descriptor failed. For example, it might be triggered when attempting to write to a read-only descriptor. \value [since 5.5] UnknownError An unknown error occurred when interacting with the service.

Enumerator
NoError
OperationError
CharacteristicWriteError
DescriptorWriteError
UnknownError
CharacteristicReadError
DescriptorReadError

Definition at line 25 of file qlowenergyservice.h.

◆ ServiceState

enum QLowEnergyService::ServiceState

This enum describes the \l state() of the service object.

\value InvalidService A service can become invalid when it looses the connection to the underlying device. Even though the connection may be lost it retains its last information. An invalid service cannot become valid anymore even if the connection to the device is re-established. \value RemoteService The service details are yet to be discovered by calling \l discoverDetails(). The only reliable pieces of information are its \l serviceUuid() and \l serviceName(). \value RemoteServiceDiscovering The service details are being discovered. \value RemoteServiceDiscovered The service details have been discovered. \value [since 5.7] LocalService The service is associated with a controller object in the \l{QLowEnergyController::PeripheralRole}{peripheral role}. Such service objects do not change their state. \value DiscoveryRequired Deprecated. Was renamed to RemoteService. \value DiscoveringService Deprecated. Was renamed to RemoteServiceDiscovering. \value ServiceDiscovered Deprecated. Was renamed to RemoteServiceDiscovered.

Enumerator
InvalidService
RemoteService
RemoteServiceDiscovering
RemoteServiceDiscovered
LocalService

Definition at line 36 of file qlowenergyservice.h.

◆ ServiceType

enum QLowEnergyService::ServiceType

This enum describes the type of the service.

\value PrimaryService The service is a top-level/primary service. If this type flag is not set, the service is considered to be a secondary service. Each service may be included by another service which is indicated by IncludedService. \value IncludedService The service is included by another service. On some platforms, this flag cannot be determined until the service that includes the current service was discovered.

Enumerator
PrimaryService
IncludedService

Definition at line 18 of file qlowenergyservice.h.

◆ WriteMode

enum QLowEnergyService::WriteMode

This enum describes the mode to be used when writing a characteristic value.

The characteristic advertises its supported write modes via its \l {QLowEnergyCharacteristic::properties()}{properties}.

\value WriteWithResponse If a characteristic is written using this mode, the peripheral shall send a write confirmation. If the operation is successful, the confirmation is emitted via the \l characteristicWritten() signal. Otherwise the \l CharacteristicWriteError is emitted. A characteristic must have set the \l QLowEnergyCharacteristic::Write property to support this write mode.

\value WriteWithoutResponse If a characteristic is written using this mode, the remote peripheral shall not send a write confirmation. The operation's success cannot be determined and the payload must not be longer than 20 bytes. A characteristic must have set the \l QLowEnergyCharacteristic::WriteNoResponse property to support this write mode. Its adavantage is a quicker write operation as it may happen in between other device interactions.

\value [since 5.7] WriteSigned If a characteristic is written using this mode, the remote peripheral shall not send a write confirmation. The operation's success cannot be determined and the payload must not be longer than 8 bytes. A bond must exist between the two devices and the link must not be encrypted. A characteristic must have set the \l QLowEnergyCharacteristic::WriteSigned property to support this write mode. This value is currently only supported on Android and on Linux with BlueZ 5 and a kernel version 3.7 or newer.

Enumerator
WriteWithResponse
WriteWithoutResponse
WriteSigned

Definition at line 67 of file qlowenergyservice.h.

Constructor & Destructor Documentation

◆ ~QLowEnergyService()

QLowEnergyService::~QLowEnergyService ( )

Destroys the \l QLowEnergyService instance.

Definition at line 399 of file qlowenergyservice.cpp.

Member Function Documentation

◆ characteristic()

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 \l discoverDetails() was not yet called or there are no characteristics with a matching uuid.

See also: characteristics()

Definition at line 480 of file qlowenergyservice.cpp.

References QLowEnergyServicePrivate::characteristicList, QHash< QLowEnergyHandle, QLowEnergyServicePrivate::CharData >::const_iterator, and QLowEnergyServicePrivate::CharData::value.

Referenced by characteristics(), contains(), readCharacteristic(), and writeCharacteristic().

Here is the caller graph for this function:

◆ characteristicChanged

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

signal

If the associated controller object is in the \l {QLowEnergyController::CentralRole}{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 \l {QBluetoothUuid::DescriptorType::ClientCharacteristicConfiguration}{ClientCharacteristicConfiguration} descriptor prior to the change event on the peripheral. More details on how this might be done can be found further \l{notifications}{above}.

If the controller is in the \l {QLowEnergyController::PeripheralRole}{peripheral} role, that is, the service object was created via \l 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.

◆ characteristicRead

void QLowEnergyService::characteristicRead	(	const QLowEnergyCharacteristic &	characteristic,
		const QByteArray &	value )

signal

This signal is emitted when the read request for characteristic successfully returned its value.

The signal might be triggered by calling \l characteristicRead(). If the read operation is not successful, the \l errorOccurred() signal is emitted using the \l CharacteristicReadError flag.

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

See also: readCharacteristic()

Since: 5.5

◆ characteristics()

QList< QLowEnergyCharacteristic > QLowEnergyService::characteristics ( ) const

Returns all characteristics associated with this QLowEnergyService instance.

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

See also: characteristic(), state(), discoverDetails()

Definition at line 503 of file qlowenergyservice.cpp.

References QList< T >::append(), characteristic(), QLowEnergyServicePrivate::characteristicList, and results.

Here is the call graph for this function:

◆ characteristicWritten

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

signal

This signal is emitted when the value of characteristic is successfully changed to newValue.

The change must have been triggered by calling \l writeCharacteristic(). If the write operation is not successful, the \l errorOccurred() signal is emitted using the \l 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 \l writeCharacteristic() is called using the \l WriteWithoutResponse mode, this signal and the \l errorOccurred() are never emitted.; This signal is only emitted for Central Role related use cases.

See also: writeCharacteristic()

◆ contains() [1/2]

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

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

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

Definition at line 608 of file qlowenergyservice.cpp.

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

Referenced by readCharacteristic(), readDescriptor(), writeCharacteristic(), and writeDescriptor().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ contains() [2/2]

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

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

Definition at line 738 of file qlowenergyservice.cpp.

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

Here is the call graph for this function:

◆ descriptorRead

void QLowEnergyService::descriptorRead	(	const QLowEnergyDescriptor &	descriptor,
		const QByteArray &	value )

signal

This signal is emitted when the read request for descriptor successfully returned its value.

The signal might be triggered by calling \l descriptorRead(). If the read operation is not successful, the \l errorOccurred() signal is emitted using the \l DescriptorReadError flag.

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

See also: readDescriptor()

Since: 5.5

◆ descriptorWritten

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

signal

This signal is emitted when the value of descriptor is successfully changed to newValue.

If the associated controller object is in the \l {QLowEnergyController::CentralRole}{central} role, the change must have been caused by calling \l writeDescriptor(). Otherwise, the signal is the result of a write request or command from a GATT client to the respective descriptor.

See also: writeDescriptor()

◆ discoverDetails()

void QLowEnergyService::discoverDetails ( DiscoveryMode mode = FullDiscovery )

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

The discovery process is indicated via the \l stateChanged() signal. After creation, the service is in \l DiscoveryRequired state. When calling discoverDetails() it transitions to \l DiscoveringService. After completion of detail discovery, it transitions to \l ServiceDiscovered state. On each transition, the \l stateChanged() signal is emitted. Depending on the argument mode, a \l FullDiscovery or a \l SkipValueDiscovery is performed. In any case, all services and characteristics are discovered. A \l FullDiscovery proceeds and reads all characteristic values and descriptors. A \l SkipValueDiscovery does not read characteristic values and descriptors. A \l 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 \l SkipValueDiscovery, it is necessary to call \l readCharacteristic() / \l 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()

Definition at line 576 of file qlowenergyservice.cpp.

References d, InvalidService, OperationError, RemoteService, and RemoteServiceDiscovering.

◆ error()

QLowEnergyService::ServiceError QLowEnergyService::error ( ) const

Returns the last occurred error or \l NoError.

Definition at line 596 of file qlowenergyservice.cpp.

References QLowEnergyServicePrivate::lastError.

◆ errorOccurred

void QLowEnergyService::errorOccurred ( QLowEnergyService::ServiceError newError )

signal

This signal is emitted when an error occurrs.

The newError parameter describes the error that occurred.

Since: 6.2

◆ includedServices()

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 \l 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.

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

See also: {QLowEnergyController::}{createServiceObject()}

Definition at line 420 of file qlowenergyservice.cpp.

References QLowEnergyServicePrivate::includedServices.

◆ readCharacteristic()

void QLowEnergyService::readCharacteristic ( const QLowEnergyCharacteristic & characteristic )

Reads the value of characteristic.

If the operation is successful, the \l characteristicRead() signal is emitted; otherwise the \l CharacteristicReadError is set. In general, a characteristic is readable, if its \l 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 \l ServiceDiscovered state and belongs to the service. If one of these conditions is not true the \l QLowEnergyService::OperationError is set.

Note: Calling this function despite \l 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 \l CharacteristicReadError is set.

See also: characteristicRead(), writeCharacteristic()

Since: 5.5

Definition at line 644 of file qlowenergyservice.cpp.

References characteristic(), contains(), d, OperationError, RemoteServiceDiscovered, and state.

Here is the call graph for this function:

◆ readDescriptor()

void QLowEnergyService::readDescriptor ( const QLowEnergyDescriptor & descriptor )

Reads the value of descriptor.

If the operation is successful, the \l descriptorRead() signal is emitted; otherwise the \l 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 \l ServiceDiscovered state and the descriptor belongs to the service. If one of these conditions is not true the \l QLowEnergyService::OperationError is set.

See also: descriptorRead(), writeDescriptor()

Since: 5.5

Definition at line 774 of file qlowenergyservice.cpp.

References contains(), d, OperationError, RemoteServiceDiscovered, and state.

Here is the call graph for this function:

◆ serviceName()

QString QLowEnergyService::serviceName ( ) const

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

The returned name can only be retrieved if \l serviceUuid() is a \l {https://developer.bluetooth.org/gatt/services/Pages/ServicesHome.aspx}{well-known UUID}.

Definition at line 532 of file qlowenergyservice.cpp.

References ok, qApp, QStringLiteral, QBluetoothUuid::serviceClassToString(), QBluetoothUuid::toUInt16(), and QLowEnergyServicePrivate::uuid.

Here is the call graph for this function:

◆ serviceUuid()

QBluetoothUuid QLowEnergyService::serviceUuid ( ) const

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

Definition at line 520 of file qlowenergyservice.cpp.

References QLowEnergyServicePrivate::uuid.

◆ state()

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 \l 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 \l 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()

Definition at line 449 of file qlowenergyservice.cpp.

References QLowEnergyServicePrivate::state.

Referenced by MyClass::btleSharedData().

Here is the caller graph for this function:

◆ stateChanged

void QLowEnergyService::stateChanged ( QLowEnergyService::ServiceState newState )

signal

This signal is emitted when the service's state changes.

The newState can also be retrieved via \l state().

See also: state()

◆ type()

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 \l ServiceDiscovered state. This field is initialised with \l PrimaryService.; On Android, it is not possible to determine whether a service is a primary or secondary service. Therefore all services have the \l PrimaryService flag set.

Definition at line 466 of file qlowenergyservice.cpp.

References QLowEnergyServicePrivate::type.

◆ writeCharacteristic()

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 \l characteristicWritten() signal is emitted; otherwise the \l CharacteristicWriteError is set. Calling this function does not trigger the a \l 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 \l QLowEnergyCharacteristic::Write and \l 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 \l ServiceDiscovered state and belongs to the service. If one of these conditions is not true the \l QLowEnergyService::OperationError is set.

Note: Calling this function despite \l QLowEnergyCharacteristic::properties() reporting a non-writable property always attempts to write to the hardware. Similarly, a \l WriteWithoutResponse is sent to the hardware too although the characteristic may only support \l WriteWithResponse. If the hardware returns with an error the \l 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(), QLowEnergyService::readCharacteristic()

Definition at line 713 of file qlowenergyservice.cpp.

References QLowEnergyController::CentralRole, characteristic(), contains(), d, OperationError, RemoteServiceDiscovered, and state.

Here is the call graph for this function:

◆ writeDescriptor()

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 \l descriptorWritten() signal is emitted; otherwise the \l 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 \l ServiceDiscovered state, belongs to the service. If one of these conditions is not true the \l 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(), readDescriptor()

Definition at line 816 of file qlowenergyservice.cpp.

References QLowEnergyController::CentralRole, QBluetoothUuid::ClientCharacteristicConfiguration, contains(), d, OperationError, RemoteServiceDiscovered, state, and QLowEnergyDescriptor::uuid().

Here is the call graph for this function:

Friends And Related Symbol Documentation

◆ QLowEnergyController

friend class QLowEnergyController

friend

Definition at line 120 of file qlowenergyservice.h.

◆ QLowEnergyControllerPrivate

friend class QLowEnergyControllerPrivate

friend

Definition at line 121 of file qlowenergyservice.h.

◆ QLowEnergyControllerPrivateAndroid

friend class QLowEnergyControllerPrivateAndroid

friend

Definition at line 123 of file qlowenergyservice.h.

◆ QLowEnergyControllerPrivateBluez

friend class QLowEnergyControllerPrivateBluez

friend

Definition at line 122 of file qlowenergyservice.h.

◆ QLowEnergyControllerPrivateDarwin

friend class QLowEnergyControllerPrivateDarwin

friend

Definition at line 124 of file qlowenergyservice.h.

The documentation for this class was generated from the following files:

qtconnectivity/src/bluetooth/qlowenergyservice.h (664d2a1cf019f76adf433d41b1418e515ffce86c)
qtconnectivity/src/bluetooth/qlowenergyservice.cpp (4814ec0069a11a0e21cd3ac8c956c5a8ec7a0c5b)

Public Types

Signals

Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ DiscoveryMode

◆ ServiceError

◆ ServiceState

◆ ServiceType

◆ WriteMode

Constructor & Destructor Documentation

◆ ~QLowEnergyService()

Member Function Documentation

◆ characteristic()

◆ characteristicChanged

◆ characteristicRead

◆ characteristics()

◆ characteristicWritten

◆ contains() [1/2]

◆ contains() [2/2]

◆ descriptorRead

◆ descriptorWritten

◆ discoverDetails()

◆ error()

◆ errorOccurred

◆ includedServices()

◆ readCharacteristic()

◆ readDescriptor()

◆ serviceName()

◆ serviceUuid()

◆ state()

◆ stateChanged

◆ type()

◆ writeCharacteristic()

◆ writeDescriptor()

Friends And Related Symbol Documentation

◆ QLowEnergyController

◆ QLowEnergyControllerPrivate

◆ QLowEnergyControllerPrivateAndroid

◆ QLowEnergyControllerPrivateBluez

◆ QLowEnergyControllerPrivateDarwin