From 944dbb9b558719b3ff9e2d129a328142c0ae6228 Mon Sep 17 00:00:00 2001
From: Alex Blasche <alexander.blasche@theqtcompany.com>
Date: Wed, 26 Nov 2014 11:22:35 +0100
Subject: [PATCH] Improve documentation for undiscovered QLEService
The class' behavior strongly deponds on its state. This can be
confusing. This patch reduces the behavior uncertainties.
Change-Id: Ib5cd8e821f2bb9aca5b579abf4ae98918f951f24
Reviewed-by: Timur Pocheptsov <Timur.Pocheptsov@digia.com>
Reviewed-by: Alex Blasche <alexander.blasche@theqtcompany.com>
---
src/bluetooth/qlowenergyservice.cpp | 15 ++++++++++++++-
1 file changed, 14 insertions(+), 1 deletion(-)
diff --git a/src/bluetooth/qlowenergyservice.cpp b/src/bluetooth/qlowenergyservice.cpp
index 0ec92d45..d3461a96 100644
--- a/src/bluetooth/qlowenergyservice.cpp
+++ b/src/bluetooth/qlowenergyservice.cpp
@@ -149,6 +149,9 @@ QT_BEGIN_NAMESPACE
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.
*/
/*!
@@ -306,6 +309,9 @@ QLowEnergyService::~QLowEnergyService()
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
@@ -331,7 +337,6 @@ QList<QBluetoothUuid> QLowEnergyService::includedServices() const
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
@@ -353,6 +358,11 @@ QLowEnergyService::ServiceState QLowEnergyService::state() 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.
+
*/
QLowEnergyService::ServiceTypes QLowEnergyService::type() const
{
@@ -363,6 +373,9 @@ QLowEnergyService::ServiceTypes QLowEnergyService::type() const
Returns the matching characteristic for \a 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 \a uuid.
+
\sa characteristics()
*/
QLowEnergyCharacteristic QLowEnergyService::characteristic(const QBluetoothUuid &uuid) const
--
GitLab