From a1a31f0b59b9896a04973846bfad2aa0bc9e8d1f Mon Sep 17 00:00:00 2001
From: Sven Gothel <sgothel@jausoft.com>
Date: Thu, 25 Jun 2020 00:30:09 +0200
Subject: GATTHandler/DBTDevice (incl Java): Add ping[GATT](), testing device
 availability via retrieval of GATT info

Issues a ping to the device, validating whether it is still reachable.

This method could be periodically utilized to shorten the underlying OS disconnect period
after turning the device off, which lies within 7-13s.

In case the device is no more reachable, disconnect will be initiated due to the occurring IO error.

+++

Implementation attempts to read the mandatory APPEARANCE CharacteristicValue
of the mandatory GENERIC_ACCESS service.
---
 api/direct_bt/DBTDevice.hpp   | 17 +++++++++++++++++
 api/direct_bt/GATTHandler.hpp | 13 +++++++++++++
 2 files changed, 30 insertions(+)

(limited to 'api')

diff --git a/api/direct_bt/DBTDevice.hpp b/api/direct_bt/DBTDevice.hpp
index 6c8097d1..e01ecaab 100644
--- a/api/direct_bt/DBTDevice.hpp
+++ b/api/direct_bt/DBTDevice.hpp
@@ -325,6 +325,23 @@ namespace direct_bt {
             /** Returns the shared GenericAccess instance, retrieved by {@link #getGATTServices()} or nullptr if not available. */
             std::shared_ptr<GenericAccess> getGATTGenericAccess();
 
+            /**
+             * Issues a GATT ping to the device, validating whether it is still reachable.
+             * <p>
+             * This method could be periodically utilized to shorten the underlying OS disconnect period
+             * after turning the device off, which lies within 7-13s.
+             * </p>
+             * <p>
+             * In case the device is no more reachable, the GATTHandler will initiate disconnect due to the occurring IO error.
+             * will issue a disconnect.
+             * </p>
+             * <p>
+             * See {@link #getGATTServices()} regarding GATT initialization.
+             * </p>
+             * @return {@code true} if successful, otherwise false in case no GATT services exists etc.
+             */
+            bool pingGATT();
+
             /**
              * Explicit disconnecting an open GATTHandler, which is usually performed via disconnect()
              * <p>
diff --git a/api/direct_bt/GATTHandler.hpp b/api/direct_bt/GATTHandler.hpp
index 253077d0..92a79c38 100644
--- a/api/direct_bt/GATTHandler.hpp
+++ b/api/direct_bt/GATTHandler.hpp
@@ -374,6 +374,19 @@ namespace direct_bt {
 
             std::shared_ptr<DeviceInformation> getDeviceInformation(std::vector<GATTServiceRef> & primServices);
             std::shared_ptr<DeviceInformation> getDeviceInformation(std::vector<GATTCharacteristicRef> & deviceInfoCharDeclList);
+
+            /**
+             * Issues a ping to the device, validating whether it is still reachable.
+             * <p>
+             * This method could be periodically utilized to shorten the underlying OS disconnect period
+             * after turning the device off, which lies within 7-13s.
+             * </p>
+             * <p>
+             * In case the device is no more reachable, disconnect will be initiated due to the occurring IO error.
+             * </p>
+             * @return {@code true} if successful, otherwise false in case no GATT services exists etc.
+             */
+            bool ping();
     };
 
 } // namespace direct_bt
-- 
cgit v1.2.3