fix: Enrich android channel with nfc HW states

- Don't attempt to enable NFC if the app or HW is not ready
- Notify clients whenever the HW adapter state changes

Author: alexjba

CMakeLists.txt

@@ -16,6 +16,12 @@ if(IOS OR ANDROID)
     find_package(Qt6 REQUIRED COMPONENTS Nfc)
 endif()
 
+# Android: this library may be built standalone (e.g. as a vendored dependency) and still needs
+# QtGui headers for QGuiApplication-based lifecycle gating in the NFC backend.
+if(ANDROID)
+    find_package(Qt6 REQUIRED COMPONENTS Gui)
+endif()
+
 # OpenSSL for secp256k1 ECDH
 # For Android and iOS, we use manually provided paths instead of find_package
 if((ANDROID OR IOS) AND OPENSSL_CRYPTO_LIBRARY AND OPENSSL_BUILD_INCLUDE_DIR AND OPENSSL_SOURCE_INCLUDE_DIR)
@@ -140,6 +146,10 @@ if(IOS OR ANDROID)
     target_link_libraries(keycard-qt PUBLIC Qt6::Nfc)
 endif()
 
+if(ANDROID)
+    target_link_libraries(keycard-qt PRIVATE Qt6::Gui)
+endif()
+
 # Link OpenSSL (if found)
 if(OpenSSL_FOUND)
     # For Android and iOS with manually provided paths, link directly to the library file

include/keycard-qt/backends/keycard_channel_unified_qt_nfc.h

@@ -6,6 +6,7 @@
 #include "keycard_channel_backend.h"
 #include <QNearFieldManager>
 #include <QNearFieldTarget>
+#include <QMetaObject>
 #include <QMutex>
 
 namespace Keycard {
@@ -38,6 +39,9 @@ class KeycardChannelUnifiedQtNfc : public KeycardChannelBackend
 private slots:
     void onTargetDetected(QNearFieldTarget* target);
     void onTargetLost(QNearFieldTarget* target);
+#ifdef Q_OS_ANDROID
+    void onAdapterStateChanged(QNearFieldManager::AdapterState state);
+#endif
 
 private:
     QString describe(QNearFieldTarget::Error error);
@@ -50,6 +54,13 @@ private slots:
     // State management
     ChannelState m_state = ChannelState::Idle;
     bool m_detectionActive = false;
+
+#ifdef Q_OS_ANDROID
+    // Qt NFC on Android can fail if discovery is started before the Activity/app is fully active.
+    // We defer startTargetDetection() until the app reaches Qt::ApplicationActive.
+    bool m_waitingForAppActive = false;
+    QMetaObject::Connection m_appStateConn;
+#endif
 
     // Helper to update and emit channel state
     void emitChannelState(ChannelOperationalState newState);

src/channel/backends/keycard_channel_unified_qt_nfc.cpp

@@ -5,12 +5,13 @@
 #include <QDebug>
 #include <QThread>
 #include <QCoreApplication>
+#ifdef Q_OS_ANDROID
+#include <QGuiApplication>
+#include <QTimer>
+#endif
 
 namespace Keycard {
 
-// Android NFC timeout extension is now handled via platform/android_nfc_utils.h
-// and called from CommandSet before long operations like GlobalPlatform factory reset
-
 KeycardChannelUnifiedQtNfc::KeycardChannelUnifiedQtNfc(QObject* parent)
     : KeycardChannelBackend(parent)
     , m_manager(nullptr)
@@ -22,6 +23,15 @@ KeycardChannelUnifiedQtNfc::KeycardChannelUnifiedQtNfc(QObject* parent)
             this, &KeycardChannelUnifiedQtNfc::onTargetDetected, Qt::DirectConnection);
     connect(m_manager, &QNearFieldManager::targetLost,
             this, &KeycardChannelUnifiedQtNfc::onTargetLost, Qt::DirectConnection);
+    connect(this, &KeycardChannelUnifiedQtNfc::channelStateChanged, this, [this](ChannelOperationalState state) {
+        if (state == ChannelOperationalState::WaitingForKeycard) {
+            m_manager->setUserInformation("Waiting for keycard. Please hold the keycard near the device.");
+        } else if (state == ChannelOperationalState::Reading) {
+            m_manager->setUserInformation("Reading keycard. Please hold the keycard near the device.");
+        } else if (state == ChannelOperationalState::Error) {
+            m_manager->setUserInformation("Error reading keycard. Please try again.");
+        }
+    });
 }
 
 KeycardChannelUnifiedQtNfc::~KeycardChannelUnifiedQtNfc()
@@ -34,6 +44,48 @@ void KeycardChannelUnifiedQtNfc::startDetection()
 {
     qDebug() << "KeycardChannelUnifiedQtNfc::startDetection()";
 
+#ifdef Q_OS_ANDROID
+    // Android-only: emitted when the OS NFC adapter is toggled on/off (or transitioning).
+    QObject::connect(m_manager, &QNearFieldManager::adapterStateChanged,
+            this, &KeycardChannelUnifiedQtNfc::onAdapterStateChanged, Qt::UniqueConnection);
+    // Qt 6.9 Android NFC uses foreground dispatch and may fail if started before the Activity
+    // is fully active/resumed. If we call too early, Qt may consider discovery enabled while
+    // the platform never actually starts delivering tag intents until a background→foreground cycle.
+    //
+    // Mitigation: defer startTargetDetection() until the Qt app is ApplicationActive.
+    auto *app = QCoreApplication::instance();
+    auto *guiApp = qobject_cast<QGuiApplication *>(app);
+    qDebug() << "KeycardChannelUnifiedQtNfc:Verifying app state=" << static_cast<int>(guiApp->applicationState());
+
+    if (guiApp && guiApp->applicationState() != Qt::ApplicationActive) {
+        qDebug() << "KeycardChannelUnifiedQtNfc: App not active yet, deferring NFC start. state="
+                 << static_cast<int>(guiApp->applicationState());
+
+        if (!m_waitingForAppActive) {
+            m_waitingForAppActive = true;
+            m_appStateConn = connect(guiApp, &QGuiApplication::applicationStateChanged,
+                                     this, [this](Qt::ApplicationState state) {
+                if (state != Qt::ApplicationActive) {
+                    return;
+                }
+
+                // One-shot: once active, drop the guard and retry immediately on the event loop.
+                m_waitingForAppActive = false;
+                QObject::disconnect(m_appStateConn);
+                m_appStateConn = {};
+
+                QTimer::singleShot(0, this, [this]() {
+                    this->startDetection();
+                });
+            });
+        }
+
+        // Keep UX consistent: we are logically waiting for a keycard, just not starting NFC yet.
+        emitChannelState(ChannelOperationalState::WaitingForKeycard);
+        return;
+    }
+#endif
+
     if (!m_manager->isSupported(QNearFieldTarget::TagTypeSpecificAccess)) {
         emitChannelState(ChannelOperationalState::NotSupported);
         emit readerAvailabilityChanged(false);
@@ -49,7 +101,7 @@ void KeycardChannelUnifiedQtNfc::startDetection()
         m_detectionActive = false;
         return;
     }
-    // Desktop: Start continuous detection immediately
+
     m_manager->startTargetDetection(QNearFieldTarget::TagTypeSpecificAccess);
     m_detectionActive = true;
     emit readerAvailabilityChanged(true);
@@ -58,6 +110,11 @@ void KeycardChannelUnifiedQtNfc::startDetection()
 
 void KeycardChannelUnifiedQtNfc::stopDetection()
 {
+#ifdef Q_OS_ANDROID
+    QObject::disconnect(m_manager, &QNearFieldManager::adapterStateChanged,
+        this, &KeycardChannelUnifiedQtNfc::onAdapterStateChanged);
+#endif
+    // iOS NFC session management can be sensitive to threading; serialize with transmit.
 #ifdef Q_OS_IOS
     QMutexLocker locker(&m_transmitMutex);
     qDebug() << "KeycardChannelUnifiedQtNfc::stopDetection()";
@@ -160,6 +217,44 @@ void KeycardChannelUnifiedQtNfc::onTargetLost(QNearFieldTarget* target)
     emit cardRemoved();
 }
 
+#ifdef Q_OS_ANDROID
+void KeycardChannelUnifiedQtNfc::onAdapterStateChanged(QNearFieldManager::AdapterState state)
+{
+    qDebug() << "KeycardChannelUnifiedQtNfc::onAdapterStateChanged() state=" << static_cast<int>(state);
+
+    switch (state) {
+        case QNearFieldManager::AdapterState::Offline:
+        case QNearFieldManager::AdapterState::TurningOff: {
+            m_manager->stopTargetDetection();
+            m_detectionActive = false;
+            disconnect();
+            // NFC is going away: stop scanning and drop any current target.
+            // Do NOT emit Idle in-between (avoid flicker); go straight to NotAvailable.
+            emit readerAvailabilityChanged(false);
+            emitChannelState(ChannelOperationalState::NotAvailable);
+            break;
+        }
+
+        case QNearFieldManager::AdapterState::Online: {
+            emit readerAvailabilityChanged(true);
+
+            // If higher-level logic expects us to be scanning, (re)start now.
+            // Use event-loop deferral to avoid re-entrancy if this signal fires during Qt NFC internals.
+            QTimer::singleShot(0, this, [this]() { this->setState(ChannelState::WaitingForCard); });
+            break;
+        }
+
+        case QNearFieldManager::AdapterState::TurningOn: {
+            // Transitional state: avoid emitting errors; keep UX in "waiting" if applicable.
+            if (m_state == ChannelState::WaitingForCard) {
+                emitChannelState(ChannelOperationalState::WaitingForKeycard);
+            }
+            break;
+        }
+    }
+}
+#endif
+
 QString KeycardChannelUnifiedQtNfc::describe(QNearFieldTarget::Error error)
 {
     switch(error) {

src/command_set.cpp

@@ -4,7 +4,6 @@
 #include "keycard-qt/pairing_storage.h"
 #include "keycard-qt/globalplatform/gp_command_set.h"
 #include "keycard-qt/globalplatform/gp_constants.h"
-#include "keycard-qt/platform/android_nfc_utils.h"
 #include <QDebug>
 #include <QCryptographicHash>
 #include <QMessageAuthenticationCode>