Document and test concurrent write requests

BTLE communication is serialised. However the Qt API provides the
ability to issue multiple write requests while the first is still
pending. The backend must enqueue the requests for later on.

This behavior was already indirectly tests by a unit test but this
patch adds an explicit test section for it and documents the behavior.

Change-Id: I089b52940820bf0ba9c3ec872a6f1d5d6bd78a0e
Reviewed-by: Timur Pocheptsov <Timur.Pocheptsov@digia.com>
Reviewed-by: Alex Blasche <alexander.blasche@theqtcompany.com>

1 files changed, 15 insertions, 1 deletions

diff --git a/src/bluetooth/qlowenergyservice.cpp b/src/bluetooth/qlowenergyservice.cpp
index 0c803144..0ae9ca67 100644
--- a/src/bluetooth/qlowenergyservice.cpp
+++ b/src/bluetooth/qlowenergyservice.cpp
@@ -98,7 +98,9 @@ QT_BEGIN_NAMESPACE
     \l writeCharacteristic() function attempts to write a new value to the given
     characteristic. If the write attempt is successful, the \l characteristicWritten()
     signal is emitted. A failure to write triggers the \l CharacteristicWriteError.
-    Writing a descriptor follows the same pattern.
+    Writing a descriptor follows the same pattern. Write requests are serialised.
+    Issuing a second write request before the previous request has finished
+    is delayed until the first write request has finished.
 
     \note Currently, it is not possible to send signed write or reliable write requests.
 
@@ -495,6 +497,12 @@ bool QLowEnergyService::contains(const QLowEnergyCharacteristic &characteristic)
     \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.
 
@@ -566,6 +574,12 @@ bool QLowEnergyService::contains(const QLowEnergyDescriptor &descriptor) const
     the \l descriptorWritten() signal is emitted; otherwise the \l DescriptorWriteError
     is emitted.
 
+    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 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 and is writable.
  */