DBTDevice: Clarify setConn* Security parameter API: Provide more versatile overloaded variant and simplified API entries.

setConnSecurityLevel(..) no more sets SMPIOCapability, only advise in API doc to avoid complexity.

2 files changed, 129 insertions, 33 deletions

diff --git a/api/direct_bt/DBTAdapter.hpp b/api/direct_bt/DBTAdapter.hpp
index 868c8485..ec042cee 100644
--- a/api/direct_bt/DBTAdapter.hpp
+++ b/api/direct_bt/DBTAdapter.hpp
@@ -249,9 +249,9 @@ namespace direct_bt {
                                                       uint16_t min_interval, uint16_t max_interval,
                                                       uint16_t latency, uint16_t supervision_timeout);
             friend HCIStatusCode DBTDevice::connectBREDR(const uint16_t pkt_type, const uint16_t clock_offset, const uint8_t role_switch);
-            friend bool DBTDevice::setConnSecurityLevel(const BTSecurityLevel sec_level, const bool blocking) noexcept;
-            friend bool DBTDevice::setConnIOCapability(const SMPIOCapability io_cap, const bool blocking) noexcept;
-            friend bool DBTDevice::setConnSecurity(const BTSecurityLevel sec_level, const SMPIOCapability io_cap, const bool blocking) noexcept;
+            friend bool DBTDevice::setConnSecurityLevel(const BTSecurityLevel sec_level) noexcept;
+            friend bool DBTDevice::setConnIOCapability(const SMPIOCapability io_cap, bool& blocking, SMPIOCapability& pre_io_cap) noexcept;
+            friend bool DBTDevice::setConnSecurity(const BTSecurityLevel sec_level, const SMPIOCapability io_cap, bool& blocking, SMPIOCapability& pre_io_cap) noexcept;
             friend void DBTDevice::processL2CAPSetup(std::shared_ptr<DBTDevice> sthis);
             friend bool DBTDevice::updatePairingState(std::shared_ptr<DBTDevice> sthis, SMPPairingState state, std::shared_ptr<MgmtEvent> evt) noexcept;
             friend void DBTDevice::hciSMPMsgCallback(std::shared_ptr<DBTDevice> sthis, std::shared_ptr<const SMPPDUMsg> msg, const HCIACLData::l2cap_frame& source) noexcept;
@@ -261,14 +261,19 @@ namespace direct_bt {
             /**
              * Sets the given SMPIOCapability for the next DBTDevice::connectLE() or DBTDevice::connectBREDR().
              * <p>
-             * The SMPIOCapability value will be reset to its previous value when connection is completed or failed.
+             * The ::SMPIOCapability value will be reset to its previous value when connection is completed or failed.
              * </p>
-             * @param io_cap SMPIOCapability to be applied
-             * @param blocking if true, blocks until previous setting is completed,
+             * <p>
+             * A value of ::SMPIOCapability::UNSET will be ignored and method returns immediately.
+             * </p>
+             * @param[in] io_cap ::SMPIOCapability to be applied
+             * @param[in,out] blocking if true, blocks until previous setting is completed,
              *        i.e. until connection has been completed or failed.
              *        Otherwise returns immediately with false if previous connection result is still pending.
+             *        On return, this parameter will be set to true if failure was caused by blocking or timeout, otherwise set to false.
+             * @param[out] pre_io_cap return the previous set ::SMPIOCapability value if successful
              */
-            bool setConnIOCapability(const DBTDevice & device, const SMPIOCapability io_cap, const bool blocking) noexcept;
+            bool setConnIOCapability(const DBTDevice & device, const SMPIOCapability io_cap, bool& blocking, SMPIOCapability& pre_io_cap) noexcept;
             bool resetConnIOCapability(const DBTDevice & device) noexcept;
             bool resetConnIOCapability(const DBTDevice & device, SMPIOCapability& pre_io_cap) noexcept;
             bool isConnIOCapabilitySet() const noexcept { return nullptr != io_capability_device_ptr; }
diff --git a/api/direct_bt/DBTDevice.hpp b/api/direct_bt/DBTDevice.hpp
index 2ceaf62c..83aed534 100644
--- a/api/direct_bt/DBTDevice.hpp
+++ b/api/direct_bt/DBTDevice.hpp
@@ -430,64 +430,155 @@ namespace direct_bt {
             HCIStatusCode disconnect(const HCIStatusCode reason=HCIStatusCode::REMOTE_USER_TERMINATED_CONNECTION ) noexcept;
 
             /**
-             * Set the ::BTSecurityLevel used to connect to this device.
+             * Set the ::BTSecurityLevel used to connect to this device on the upcoming connection.
              * <p>
-             * Method returns false if this device has already being connected,
+             * Method returns false if ::BTSecurityLevel::UNSET has been given,
+             * operation fails, this device has already being connected,
              * or DBTDevice::connectLE() or DBTDevice::connectBREDR() has been issued already.
              * </p>
              * <p>
-             * To ensure consistent no authentication setup,<br>
-             * implementation will set ::SMPIOCapability::NO_INPUT_NO_OUTPUT if sec_level <= ::BTSecurityLevel::ENC_ONLY<br>
-             * and DBTDevice::setConnIOCapability() has not been used.
+             * To ensure a consistent authentication setup,
+             * it is advised to set ::SMPIOCapability::NO_INPUT_NO_OUTPUT for sec_level <= ::BTSecurityLevel::ENC_ONLY
+             * using setConnSecurity() as well as an IO capable ::SMPIOCapability value
+             * for ::BTSecurityLevel::ENC_AUTH or ::BTSecurityLevel::ENC_AUTH_FIPS.
              * </p>
-             * @param sec_level ::BTSecurityLevel to be applied
-             * @param blocking if true, blocks until previous ::SMPIOCapability setting is completed,
-             *        i.e. until connection has been completed or failed.
-             *        Otherwise returns immediately with false if previous connection result is still pending.
-             * @return
+             * @param sec_level ::BTSecurityLevel to be applied, ::BTSecurityLevel::UNSET will be ignored and method fails.
+             * @see ::BTSecurityLevel
+             * @see ::SMPIOCapability
+             * @see getConnSecurityLevel()
+             * @see setConnIOCapability()
+             * @see getConnIOCapability()
+             * @see setConnSecurity()
              */
-            bool setConnSecurityLevel(const BTSecurityLevel sec_level, const bool blocking) noexcept;
+            bool setConnSecurityLevel(const BTSecurityLevel sec_level) noexcept;
 
             /**
-             * Return the ::BTSecurityLevel, determined when connection is established.
+             * Return the ::BTSecurityLevel, determined when the connection is established.
+             * @see ::BTSecurityLevel
+             * @see ::SMPIOCapability
+             * @see setConnSecurityLevel()
+             * @see setConnIOCapability()
+             * @see getConnIOCapability()
+             * @see setConnSecurity()
              */
             BTSecurityLevel getConnSecurityLevel() const noexcept { return pairing_data.sec_level_conn; }
 
             /**
-             * Sets the given ::SMPIOCapability used to connect to this device.
+             * Sets the given ::SMPIOCapability used to connect to this device temporarily for the adapter.
              * <p>
-             * Method returns false if operation fails, this device has already being connected,
+             * Method returns false if ::SMPIOCapability::UNSET has been given,
+             * operation fails, this device has already being connected,
              * or DBTDevice::connectLE() or DBTDevice::connectBREDR() has been issued already.
              * </p>
              * <p>
              * The ::SMPIOCapability value will be reset for the adapter to its previous value when connection is completed or failed.
              * </p>
-             * @param io_cap ::SMPIOCapability to be applied
-             * @param blocking if true, blocks until previous ::SMPIOCapability setting is completed,
+             * @param[in] io_cap ::SMPIOCapability to be applied, ::SMPIOCapability::UNSET will be ignored and method fails.
+             * @param[in,out] blocking if true, blocks until previous ::SMPIOCapability setting is completed,
              *        i.e. until connection has been completed or failed.
-             *        Otherwise returns immediately with false if previous connection result is still pending.
+             *        Otherwise returns immediately with false if previous connection result is still pending on the adapter.<br>
+             *        On return, this parameter will be set to true if failure was caused by blocking or timeout, otherwise set to false.
+             * @param[out] pre_io_cap return the previous set ::SMPIOCapability value if successful
+             * @see ::BTSecurityLevel
+             * @see ::SMPIOCapability
+             * @see setConnSecurityLevel()
+             * @see getConnSecurityLevel()
+             * @see getConnIOCapability()
+             * @see setConnSecurity()
              */
-            bool setConnIOCapability(const SMPIOCapability io_cap, const bool blocking=true) noexcept;
+            bool setConnIOCapability(const SMPIOCapability io_cap, bool& blocking, SMPIOCapability& pre_io_cap) noexcept;
+
+            /**
+             * Sets the given ::SMPIOCapability used to connect to this device temporarily for the adapter.
+             * <p>
+             * Method returns false if ::SMPIOCapability::UNSET has been given,
+             * operation fails, this device has already being connected,
+             * or DBTDevice::connectLE() or DBTDevice::connectBREDR() has been issued already.
+             * </p>
+             * <p>
+             * The ::SMPIOCapability value will be reset for the adapter to its previous value when connection is completed or failed.
+             * </p>
+             * @param[in] io_cap ::SMPIOCapability to be applied, ::SMPIOCapability::UNSET will be ignored and method fails.
+             * @param[in] blocking if true, blocks until previous ::SMPIOCapability setting is completed,
+             *        i.e. until connection has been completed or failed.
+             *        Otherwise returns immediately with false if previous connection result is still pending on the adapter.
+             * @see ::BTSecurityLevel
+             * @see ::SMPIOCapability
+             * @see setConnSecurityLevel()
+             * @see getConnSecurityLevel()
+             * @see getConnIOCapability()
+             * @see setConnSecurity()
+             */
+            bool setConnIOCapability(const SMPIOCapability io_cap, const bool blocking) noexcept {
+                SMPIOCapability pre_io_cap { SMPIOCapability::UNSET };
+                bool blocking_in_out = blocking;
+                return setConnIOCapability(io_cap, blocking_in_out, pre_io_cap);
+            }
 
             /**
-             * Sets the given ::BTSecurityLevel and ::SMPIOCapability used to connect to this device.
+             * Sets the given ::BTSecurityLevel (on the upcoming connection) and ::SMPIOCapability (temporarily for the adapter)
+             * used to connect to this device if successful, otherwise method doesn't change either value.
              * <p>
-             * Method returns false if operation fails, this device has already being connected,
+             * Method returns false if ::BTSecurityLevel::UNSET or ::SMPIOCapability::UNSET has been given,
+             * operation fails, this device has already being connected,
              * or DBTDevice::connectLE() or DBTDevice::connectBREDR() has been issued already.
              * </p>
              * <p>
              * The ::SMPIOCapability value will be reset for the adapter to its previous value when connection is completed or failed.
              * </p>
-             * @param sec_level ::BTSecurityLevel to be applied
-             * @param io_cap ::SMPIOCapability to be applied
-             * @param blocking if true, blocks until previous ::SMPIOCapability setting is completed,
+             * @param[in] sec_level ::BTSecurityLevel to be applied, ::BTSecurityLevel::UNSET will be ignored and method fails.
+             * @param[in] io_cap ::SMPIOCapability to be applied, ::SMPIOCapability::UNSET will be ignored and method fails.
+             * @param[in,out] blocking if true, blocks until previous ::SMPIOCapability setting is completed,
              *        i.e. until connection has been completed or failed.
-             *        Otherwise returns immediately with false if previous connection result is still pending.
+             *        Otherwise returns immediately with false if previous connection result is still pending on the adapter.<br>
+             *        On return, this parameter will be set to true if failure was caused by blocking or timeout, otherwise set to false.
+             * @param[out] pre_io_cap return the previous set ::SMPIOCapability value if successful
+             * @see ::BTSecurityLevel
+             * @see ::SMPIOCapability
+             * @see setConnSecurityLevel()
+             * @see getConnSecurityLevel()
+             * @see setConnIOCapability()
+             * @see getConnIOCapability()
              */
-            bool setConnSecurity(const BTSecurityLevel sec_level, const SMPIOCapability io_cap, const bool blocking=true) noexcept;
+            bool setConnSecurity(const BTSecurityLevel sec_level, const SMPIOCapability io_cap, bool& blocking, SMPIOCapability& pre_io_cap) noexcept;
+
+            /**
+             * Sets the given ::BTSecurityLevel (on the upcoming connection) and ::SMPIOCapability (temporarily for the adapter)
+             * used to connect to this device if successful, otherwise method doesn't change either value.
+             * <p>
+             * Method returns false if ::BTSecurityLevel::UNSET or ::SMPIOCapability::UNSET has been given,
+             * operation fails, this device has already being connected,
+             * or DBTDevice::connectLE() or DBTDevice::connectBREDR() has been issued already.
+             * </p>
+             * <p>
+             * The ::SMPIOCapability value will be reset for the adapter to its previous value when connection is completed or failed.
+             * </p>
+             * @param[in] sec_level ::BTSecurityLevel to be applied, ::BTSecurityLevel::UNSET will be ignored and method fails.
+             * @param[in] io_cap ::SMPIOCapability to be applied, ::SMPIOCapability::UNSET will be ignored and method fails.
+             * @param[in] blocking if true, blocks until previous ::SMPIOCapability setting is completed,
+             *        i.e. until connection has been completed or failed.
+             *        Otherwise returns immediately with false if previous connection result is still pending on the adapter.
+             * @see ::BTSecurityLevel
+             * @see ::SMPIOCapability
+             * @see setConnSecurityLevel()
+             * @see getConnSecurityLevel()
+             * @see setConnIOCapability()
+             * @see getConnIOCapability()
+             */
+            bool setConnSecurity(const BTSecurityLevel sec_level, const SMPIOCapability io_cap, const bool blocking) noexcept {
+                SMPIOCapability pre_io_cap { SMPIOCapability::UNSET };
+                bool blocking_in_out = blocking;
+                return setConnSecurity(sec_level, io_cap, blocking_in_out, pre_io_cap);
+            }
 
             /**
-             * Return the set ::SMPIOCapability value, determined when connection is established.
+             * Return the set ::SMPIOCapability value, determined when the connection is established.
+             * @see ::BTSecurityLevel
+             * @see ::SMPIOCapability
+             * @see setConnSecurityLevel()
+             * @see getConnSecurityLevel()
+             * @see setConnIOCapability()
+             * @see setConnSecurity()
              */
             SMPIOCapability getConnIOCapability() const noexcept { return pairing_data.ioCap_conn; }