From 1a79ab468d8cc23cfdf28ddfa85d3e03ffddf44c Mon Sep 17 00:00:00 2001
From: Thomas Vanbesien <tvanbesi@proton.me>
Date: Wed, 18 Feb 2026 00:18:33 +0100
Subject: Refactor and document: fix cert filenames, add Doxygen, improve demo

Refactoring (issues 1,3,4,5,7,8,9,10 from review):
- Replace hardcoded cert filenames with certFile/keyFile properties
- Add 30s timeout to certificate trust QEventLoop
- Cache servers() QVariantList instead of rebuilding per call
- Validate URLs before passing to QtOpcUa
- Use ComboBox valueRole for robust enum mapping
- Add certificate trust dialog to demo
- Remove unnecessary RowLayout wrapper
- Remove debug output from BuildDeps.cmake

Documentation:
- Add Doxygen file blocks to all C++ files
- Document AuthMode enum, toAuthenticationInformation(), key
  Q_INVOKABLE methods, certificateTrustRequested signal contract
- Convert section banners to standard format
- Add file/target comments to CMake and QML files
---
 src/BobinkClient.h | 45 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 44 insertions(+), 1 deletion(-)

(limited to 'src/BobinkClient.h')

diff --git a/src/BobinkClient.h b/src/BobinkClient.h
index b8e5624..f95ab02 100644
--- a/src/BobinkClient.h
+++ b/src/BobinkClient.h
@@ -1,3 +1,11 @@
+/**
+ * @file   BobinkClient.h
+ * @brief  QML singleton managing the OPC UA connection lifecycle.
+ *
+ * Wraps QOpcUaClient into a declarative interface: LDS discovery,
+ * endpoint selection, PKI, and certificate trust flow.
+ * Single connection at a time (app-wide singleton).
+ */
 #ifndef BOBINKCLIENT_H
 #define BOBINKCLIENT_H
 
@@ -33,12 +41,21 @@ class BobinkClient : public QObject
   Q_PROPERTY (QVariantList servers READ servers NOTIFY serversChanged)
 
   Q_PROPERTY (QString pkiDir READ pkiDir WRITE setPkiDir NOTIFY pkiDirChanged)
+  Q_PROPERTY (
+      QString certFile READ certFile WRITE setCertFile NOTIFY certFileChanged)
+  Q_PROPERTY (
+      QString keyFile READ keyFile WRITE setKeyFile NOTIFY keyFileChanged)
 
 public:
   explicit BobinkClient (QObject *parent = nullptr);
   ~BobinkClient () override;
 
   static BobinkClient *instance ();
+
+  /**
+   * @brief  QML singleton factory.
+   * @note   CppOwnership — lives for the process lifetime.
+   */
   static BobinkClient *create (QQmlEngine *qmlEngine, QJSEngine *jsEngine);
 
   bool connected () const;
@@ -65,19 +82,38 @@ public:
   QString pkiDir () const;
   void setPkiDir (const QString &path);
 
+  QString certFile () const;
+  void setCertFile (const QString &path);
+
+  QString keyFile () const;
+  void setKeyFile (const QString &path);
+
+  /** @brief Discover endpoints, pick the most secure, connect. */
   Q_INVOKABLE void connectToServer ();
   Q_INVOKABLE void disconnectFromServer ();
+
+  /** @brief Accept the pending server certificate. */
   Q_INVOKABLE void acceptCertificate ();
+  /** @brief Reject the pending server certificate. */
   Q_INVOKABLE void rejectCertificate ();
 
   Q_INVOKABLE void startDiscovery ();
   Q_INVOKABLE void stopDiscovery ();
+
+  /** @brief Apply PKI dirs and cert/key. Call before connecting. */
   Q_INVOKABLE void applyPki ();
 
 signals:
   void connectedChanged ();
   void serverUrlChanged ();
   void authChanged ();
+
+  /**
+   * @brief Emitted when the server presents an untrusted cert.
+   *
+   * The connection blocks until acceptCertificate() or
+   * rejectCertificate() is called (30 s timeout, auto-rejects).
+   */
   void certificateTrustRequested (const QString &certInfo);
   void connectionError (const QString &message);
 
@@ -86,6 +122,8 @@ signals:
   void discoveringChanged ();
   void serversChanged ();
   void pkiDirChanged ();
+  void certFileChanged ();
+  void keyFileChanged ();
 
 private slots:
   void handleStateChanged (QOpcUaClient::ClientState state);
@@ -108,16 +146,21 @@ private:
   BobinkAuth *m_auth = nullptr;
   QString m_serverUrl;
   bool m_connected = false;
+
+  // Certificate trust event loop — see handleConnectError().
   QEventLoop *m_certLoop = nullptr;
   bool m_certAccepted = false;
 
   QString m_discoveryUrl;
-  int m_discoveryInterval = 10000;
+  int m_discoveryInterval = 10000; // ms
   QTimer m_discoveryTimer;
   bool m_discovering = false;
   QList<QOpcUaApplicationDescription> m_discoveredServers;
 
   QString m_pkiDir;
+  QString m_certFile;
+  QString m_keyFile;
+  QVariantList m_serversCache;
 };
 
 #endif // BOBINKCLIENT_H
-- 
cgit v1.2.3