Add ability to read characteristics and descriptors

This patch introduces the new API elements without any implementation.

Change-Id: Ia2a4d4c588f2f2f219288967ed9cc69b13b682c6
Reviewed-by: Timur Pocheptsov <Timur.Pocheptsov@digia.com>

4 files changed, 110 insertions, 5 deletions

diff --git a/src/bluetooth/qlowenergycharacteristic.cpp b/src/bluetooth/qlowenergycharacteristic.cpp
index efd54cfb..f0b78243 100644
--- a/src/bluetooth/qlowenergycharacteristic.cpp
+++ b/src/bluetooth/qlowenergycharacteristic.cpp
@@ -192,8 +192,8 @@ QLowEnergyCharacteristic::PropertyTypes QLowEnergyCharacteristic::properties() c
 
     The cache is updated during the associated service's
     \l {QLowEnergyService::discoverDetails()} {detail discovery}, a successful
-    \l {QLowEnergyService::writeCharacteristic()}{write operation} or when an update
-    notification is received.
+    \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
diff --git a/src/bluetooth/qlowenergydescriptor.cpp b/src/bluetooth/qlowenergydescriptor.cpp
index df044573..16b5b02b 100644
--- a/src/bluetooth/qlowenergydescriptor.cpp
+++ b/src/bluetooth/qlowenergydescriptor.cpp
@@ -237,8 +237,8 @@ QLowEnergyHandle QLowEnergyDescriptor::handle() const
 /*!
     Returns the cached value of the descriptor.
 
-    A descriptor value may be updated using
-    \l QLowEnergyService::writeDescriptor().
+    The cached descriptor value may be updated using
+    \l QLowEnergyService::writeDescriptor() or \l QLowEnergyService::readDescriptor().
 */
 QByteArray QLowEnergyDescriptor::value() const
 {
diff --git a/src/bluetooth/qlowenergyservice.cpp b/src/bluetooth/qlowenergyservice.cpp
index 839d6690..470db8c6 100644
--- a/src/bluetooth/qlowenergyservice.cpp
+++ b/src/bluetooth/qlowenergyservice.cpp
@@ -168,9 +168,15 @@ QT_BEGIN_NAMESPACE
                                     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 CharacteristicReadError  An attempt to read a characteristic value failed. For example,
+                                    it might be triggered in response to a call to
+                                    \l readCharacteristic(). This value was introduced by Qt 5.5.
     \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 DescriptorReadError      An attempt to read a descriptor value failed. For example,
+                                    it might be triggered in response to a call to
+                                    \l readDescriptor(). This value was introduced by Qt 5.5.
     \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.
@@ -238,6 +244,18 @@ QT_BEGIN_NAMESPACE
  */
 
 /*!
+    \fn void QLowEnergyService::characteristicRead(const QLowEnergyCharacteristic &characteristic, const QByteArray &value)
+
+    This signal is emitted when the read request for \a characteristic successfully returned
+    its \a value. The signal might be triggered by calling \l characteristicRead(). If
+    the read operation is not successful, the \l error() signal is emitted using the
+    \l CharacteristicReadError flag.
+
+    \sa readCharacteristic()
+    \since 5.5
+ */
+
+/*!
     \fn void QLowEnergyService::characteristicWritten(const QLowEnergyCharacteristic &characteristic, const QByteArray &newValue);
 
     This signal is emitted when the value of \a characteristic
@@ -275,6 +293,18 @@ QT_BEGIN_NAMESPACE
  */
 
 /*!
+    \fn void QLowEnergyService::descriptorRead(const QLowEnergyDescriptor &descriptor, const QByteArray &value)
+
+    This signal is emitted when the read request for \a descriptor successfully returned
+    its \a value. The signal might be triggered by calling \l descriptorRead(). If
+    the read operation is not successful, the \l error() signal is emitted using the
+    \l DescriptorReadError flag.
+
+    \sa readDescriptor()
+    \since 5.5
+ */
+
+/*!
     \fn void QLowEnergyService::descriptorWritten(const QLowEnergyDescriptor &descriptor, const QByteArray &newValue)
 
     This signal is emitted when the value of \a descriptor
@@ -512,6 +542,41 @@ bool QLowEnergyService::contains(const QLowEnergyCharacteristic &characteristic)
     return false;
 }
 
+
+/*!
+    Reads the value of \a characteristic. If the operation is successful, the
+    \l characteristicRead() signal is emitted; otherwise the \l CharacteristicReadError
+    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,
+    belongs to the service and is readable. If \a characteristic is readable its
+    \l QLowEnergyCharacteristic::Read property is set.
+
+    \sa characteristicRead()
+
+    \since 5.5
+ */
+void QLowEnergyService::readCharacteristic(
+        const QLowEnergyCharacteristic &characteristic)
+{
+    Q_D(QLowEnergyService);
+
+    // not a characteristic of this service
+    if (!contains(characteristic))
+        return;
+
+    if (state() != ServiceDiscovered || !d->controller) {
+        d->setError(QLowEnergyService::OperationError);
+        return;
+    }
+
+    //TODO
+}
+
 /*!
     Writes \a newValue as value for the \a characteristic. If the operation is successful,
     the \l characteristicWritten() signal is emitted; otherwise the \l CharacteristicWriteError
@@ -596,11 +661,43 @@ bool QLowEnergyService::contains(const QLowEnergyDescriptor &descriptor) const
 }
 
 /*!
+    Reads the value of \a 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 written if the service is in the \l ServiceDiscovered state,
+    belongs to the service and is readable.
+
+    \sa descriptorRead()
+
+    \since 5.5
+ */
+void QLowEnergyService::readDescriptor(
+        const QLowEnergyDescriptor &descriptor)
+{
+    Q_D(QLowEnergyService);
+
+    if (!contains(descriptor))
+        return;
+
+    if (state() != ServiceDiscovered || !d->controller) {
+        d->setError(QLowEnergyService::OperationError);
+        return;
+    }
+
+    //TODO implement QLowEnergyService::readDescriptor()
+}
+
+/*!
     Writes \a newValue as value for \a descriptor. If the operation is successful,
     the \l descriptorWritten() signal is emitted; otherwise the \l DescriptorWriteError
     is emitted.
 
-    All descriptor and characteristic write requests towards the same remote device are
+    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
diff --git a/src/bluetooth/qlowenergyservice.h b/src/bluetooth/qlowenergyservice.h
index 3d9247a6..78183c05 100644
--- a/src/bluetooth/qlowenergyservice.h
+++ b/src/bluetooth/qlowenergyservice.h
@@ -55,7 +55,9 @@ public:
     enum ServiceError {
         NoError = 0,
         OperationError,
+        CharacteristicReadError,
         CharacteristicWriteError,
+        DescriptorReadError,
         DescriptorWriteError,
         UnknownError
     };
@@ -90,11 +92,13 @@ public:
     ServiceError error() const;
 
     bool contains(const QLowEnergyCharacteristic &characteristic) const;
+    void readCharacteristic(const QLowEnergyCharacteristic &characteristic);
     void writeCharacteristic(const QLowEnergyCharacteristic &characteristic,
                              const QByteArray &newValue,
                              WriteMode mode = WriteWithResponse);
 
     bool contains(const QLowEnergyDescriptor &descriptor) const;
+    void readDescriptor(const QLowEnergyDescriptor &descriptor);
     void writeDescriptor(const QLowEnergyDescriptor &descriptor,
                          const QByteArray &newValue);
 
@@ -102,8 +106,12 @@ Q_SIGNALS:
     void stateChanged(QLowEnergyService::ServiceState newState);
     void characteristicChanged(const QLowEnergyCharacteristic &info,
                                const QByteArray &value);
+    void characteristicRead(const QLowEnergyCharacteristic &info,
+                            const QByteArray &value);
     void characteristicWritten(const QLowEnergyCharacteristic &info,
                                const QByteArray &value);
+    void descriptorRead(const QLowEnergyDescriptor &info,
+                        const QByteArray &value);
     void descriptorWritten(const QLowEnergyDescriptor &info,
                            const QByteArray &value);
     void error(QLowEnergyService::ServiceError error);