Improve documentation on how to enable characteristic notifications

Change-Id: I87575fb7b5115a536e12c0a00374cc0e67428706
Reviewed-by: Lars Knoll <lars.knoll@digia.com>

2 files changed, 70 insertions, 1 deletions

diff --git a/src/bluetooth/doc/snippets/doc_src_qtbluetooth.cpp b/src/bluetooth/doc/snippets/doc_src_qtbluetooth.cpp
index abcf9dbb..70e1f629 100644
--- a/src/bluetooth/doc/snippets/doc_src_qtbluetooth.cpp
+++ b/src/bluetooth/doc/snippets/doc_src_qtbluetooth.cpp
@@ -69,11 +69,13 @@ public:
     void startServiceDiscovery();
     void objectPush();
     void btleSharedData();
+    void enableCharNotifications();
 
 public slots:
     void deviceDiscovered(const QBluetoothDeviceInfo &device);
     void serviceDiscovered(const QBluetoothServiceInfo &service);
     void transferFinished(QBluetoothTransferReply* reply);
+    void characteristicChanged(const QLowEnergyCharacteristic& ,const QByteArray&);
 };
 
 void MyClass::localDevice() {
@@ -171,6 +173,10 @@ void MyClass::transferFinished(QBluetoothTransferReply* /*reply*/)
 {
 }
 
+void MyClass::characteristicChanged(const QLowEnergyCharacteristic &, const QByteArray &)
+{
+}
+
 void MyClass::btleSharedData()
 {
     QBluetoothAddress remoteDevice;
@@ -194,6 +200,51 @@ void MyClass::btleSharedData()
 //! [data_share_qlowenergyservice]
 }
 
+void MyClass::enableCharNotifications()
+{
+    QBluetoothAddress remoteDevice;
+    QLowEnergyService *service;
+    QLowEnergyController *control = new QLowEnergyController(remoteDevice, this);
+    control->connectToDevice();
+
+
+    service = control->createServiceObject(QBluetoothUuid::BatteryService, this);
+    if (!service)
+        return;
+
+    service->discoverDetails();
+
+    //... wait until discovered
+
+//! [enable_btle_notifications]
+    //PreCondition: service details already discovered
+    QLowEnergyCharacteristic batteryLevel = service->characteristic(
+                QBluetoothUuid::BatteryLevel);
+    if (!batteryLevel.isValid())
+        return;
+
+    QLowEnergyDescriptor notification = batteryLevel.descriptor(
+                QBluetoothUuid::ClientCharacteristicConfiguration);
+    if (!notification.isValid())
+        return;
+
+    // establish hook into notifications
+    connect(service, SIGNAL(characteristicChanged(QLowEnergyCharacteristic,QByteArray)),
+            this, SLOT(characteristicChanged(QLowEnergyCharacteristic,QByteArray)));
+
+    // enable notification
+    service->writeDescriptor(notification, QByteArray::fromHex("0100"));
+
+    // disable notification
+    //service->writeDescriptor(notification, QByteArray::fromHex("0000"));
+
+    // wait until descriptorWritten() signal is emitted
+    // to confirm successful write
+//! [enable_btle_notifications]
+}
+
+
+
 int main(int argc, char** argv)
 {
     QCoreApplication app(argc, argv);
diff --git a/src/bluetooth/qlowenergyservice.cpp b/src/bluetooth/qlowenergyservice.cpp
index 7295bb87..9136f83b 100644
--- a/src/bluetooth/qlowenergyservice.cpp
+++ b/src/bluetooth/qlowenergyservice.cpp
@@ -100,6 +100,23 @@ QT_BEGIN_NAMESPACE
     signal is emitted. A failure to write triggers the \l CharacteristicWriteError.
     Writing a descriptor follows the same pattern.
 
+    \target notifications
+
+    In some cases the peripheral generates value updates which
+    the central is interested in receiving. In order for a characteristic to support
+    such notifications it must have the \l QLowEnergyCharacteristic::Notify or
+    \l QLowEnergyCharacteristic::Indicate property and a descriptor of type
+    \l QBluetoothUuid::ClientCharacteristicConfiguration. Provided those conditions
+    are fulfilled notifications can be enabled as shown in the following code segment:
+
+    \snippet doc_src_qtbluetooth.cpp enable_btle_notifications
+
+    The example shows a battery level characteristic which updates the central
+    on every value change. The notifications are provided via
+    the \l characteristicChanged() signal. More details about this mechanism
+    are provided by the
+    \l {https://developer.bluetooth.org/gatt/descriptors/Pages/DescriptorViewer.aspx?u=org.bluetooth.descriptor.gatt.client_characteristic_configuration.xml}{Bluetooth Specification}.
+
     \section1 Service Data Sharing
 
     Each QLowEnergyService instance shares its internal states and information
@@ -232,7 +249,8 @@ QT_BEGIN_NAMESPACE
     The signal emission implies that change notifications must
     have been activated via the characteristic's
     \l {QBluetoothUuid::ClientCharacteristicConfiguration}{ClientCharacteristicConfiguration}
-    descriptor prior to the change event on the peripheral.
+    descriptor prior to the change event on the peripheral. More details on how this might be
+    done can be found further \l{notifications}{above}.
  */
 
 /*!