Integration interface refactoring

zehnm · zehnm · commit 828a3dc9cb6b · 2020-01-17T17:56:01.000+01:00
- Using the base integration interfaces instead of generic QObject. - Preparing to use the skeleton integration classes. - Clean up. Part of YIO-Remote/remote-software#348
diff --git a/src/yio-interface/configinterface.h b/src/yio-interface/configinterface.h
@@ -23,7 +23,9 @@
 
 #include <QVariant>
 
-/// This interface is implemented by the Entities object and used by integration DLLs to access the entities
+/**
+ * @brief This interface is implemented by the Entities object and used by integration DLLs to access the entities.
+ */
 class ConfigInterface {
  public:
     virtual ~ConfigInterface();
diff --git a/src/yio-interface/integrationinterface.h b/src/yio-interface/integrationinterface.h
@@ -24,20 +24,61 @@
 
 #include <QVariant>
 
+// FIXME provide complete API documentation with all QML requirements of the implementation!
+/**
+ * @brief The IntegrationInterface must be implemented by the integration plugins.
+ */
 class IntegrationInterface {
  public:
     enum States { CONNECTED = 0, CONNECTING = 1, DISCONNECTED = 2 };
 
     virtual ~IntegrationInterface();
 
-    virtual void connect() = 0;       // Must be implemented by integration
-    virtual void disconnect() = 0;    // Must be implemented by integration
-    virtual void enterStandby() = 0;  // Can be overriden by integration
-    virtual void leaveStandby() = 0;  // Can be overriden by integration
+    /**
+     * @brief connect Must be implemented by integration as Q_INVOKABLE
+     */
+    virtual void connect() = 0;
+
+    /**
+     * @brief disconnect Must be implemented by integration as Q_INVOKABLE
+     */
+    virtual void disconnect() = 0;
+
+    /**
+     * @brief enterStandby Can be implemented by integration as Q_INVOKABLE
+     */
+    virtual void enterStandby() = 0;
+
+    /**
+     * @brief enterStandby Can be implemented by integration as Q_INVOKABLE
+     */
+    virtual void leaveStandby() = 0;
+
+    /**
+     * @brief sendCommand Must be implemented as Q_INVOKABLE
+     * @param type
+     * @param entity_id
+     * @param command
+     * @param param
+     */
     virtual void sendCommand(const QString& type, const QString& entity_id, int command, const QVariant& param) = 0;
 
+    /**
+     * @brief state Returns the current state. See States enum definition.
+     * @details A Q_PROPERTY must be implemented with this method as READ accessor.
+     */
     virtual int     state() = 0;
+
+    /**
+     * @brief state Returns the integration identifier.
+     * @details A Q_PROPERTY must be implemented with this method as READ accessor.
+     */
     virtual QString integrationId() = 0;
+
+    /**
+     * @brief state Returns the friendly human readable name of the integration.
+     * @details A Q_PROPERTY must be implemented with this method as READ accessor.
+     */
     virtual QString friendlyName() = 0;
 };
 
diff --git a/src/yio-interface/notificationsinterface.h b/src/yio-interface/notificationsinterface.h
@@ -24,7 +24,9 @@
 
 #include <QVariant>
 
-/// This interface is implemented by the Entities object and used by integration DLLs to access the entities
+/**
+ * @brief This interface is implemented by the Entities object and used by integration DLLs to access the entities.
+ */
 class NotificationsInterface {
  public:
     virtual ~NotificationsInterface();
diff --git a/src/yio-interface/plugininterface.h b/src/yio-interface/plugininterface.h
@@ -26,17 +26,24 @@
 #include <QTranslator>
 #include <QVariantMap>
 
-// This interface is implemented by the integration .so files, it is used by the entities to operate the integration
+#include "configinterface.h"
+#include "entities/entitiesinterface.h"
+#include "notificationsinterface.h"
+#include "yioapiinterface.h"
+
+// FIXME provide complete API documentation with all QML requirements of the implementation!
+/**
+ * @brief The PluginInterface must be implemented by the integration plugins, it is used by the entities to operate the integration.
+ */
 class PluginInterface : public QObject {
     Q_OBJECT
 
  public:
     virtual ~PluginInterface() {}
 
     // create an integration and return the object
-    virtual void create(const QVariantMap &configurations, QObject *entities, QObject *notifications, QObject *api,
-                        QObject *configObj) = 0;
-
+    virtual void create(const QVariantMap &config, EntitiesInterface *entities, NotificationsInterface *notifications,
+                        YioAPIInterface *api, ConfigInterface *configObj) = 0;
     // enable log category
     virtual void setLogEnabled(QtMsgType msgType, bool enable) = 0;
 
diff --git a/src/yio-interface/yioapiinterface.h b/src/yio-interface/yioapiinterface.h
@@ -25,7 +25,9 @@
 #include <QObject>
 #include <QVariant>
 
-/// This interface is implemented by the Entities object and used by integration DLLs to access the entities
+/**
+ * @brief This interface is implemented by the Entities object and used by integration DLLs to access the entities.
+ */
 class YioAPIInterface : public QObject {
     Q_OBJECT
 
diff --git a/src/yio-plugin/integration.cpp b/src/yio-plugin/integration.cpp
@@ -20,7 +20,7 @@
  * SPDX-License-Identifier: GPL-3.0-or-later
  *****************************************************************************/
 
-#include "yio-plugin/integration.h"
+#include "integration.h"
 
 // FIXME redo Integration implementation once the project is cleary separated from remote-software
 // and the common headers are working!
@@ -42,7 +42,7 @@ Integration::Integration(const QVariantMap& config, QObject *entities, QObject *
     m_config = qobject_cast<ConfigInterface *>(configObj);
 }
 
-// Used for proxy
+// Used for integration threading adapter
 Integration::Integration (Plugin* parent) :
     QObject(parent),
     m_state(DISCONNECTED),
@@ -52,4 +52,5 @@ Integration::Integration (Plugin* parent) :
     m_config(nullptr),
     m_log(parent->m_logCategory)
 {}
+
 */
diff --git a/src/yio-plugin/integration.h b/src/yio-plugin/integration.h
@@ -24,32 +24,37 @@
 
 #include <QObject>
 
+#include "plugin.h"
 #include "yio-interface/entities/entitiesinterface.h"
 #include "yio-interface/integrationinterface.h"
 
-// Integration base class
-class Integration : public QObject, IntegrationInterface {
+/**
+ * @brief The Integration class is the base class of an integration plugin defining all required QML accessors.
+ */
+class Integration : public QObject, public IntegrationInterface {
     Q_OBJECT
     Q_INTERFACES(IntegrationInterface)
 
  public:
+    // TODO(mze) default implementation
+    // Integration(const QVariantMap& config, EntitiesInterface *entities, NotificationsInterface *notifications,
+    //             YioAPIInterface* api, ConfigInterface *configObj, Plugin* plugin);
+    // Integration(Plugin* plugin);
     Integration() {}
 
-    enum states { CONNECTED = 0, CONNECTING = 1, DISCONNECTED = 2 };
-
-    Q_ENUM(states)
-
+    // FIXME do we really need all Q_PROPERTY & Q_INVOKABLE function? E.g. why should QML be able to change the
+    // integrationId?
     Q_PROPERTY(int state READ state WRITE setState NOTIFY stateChanged)
     Q_PROPERTY(QString integrationId READ integrationId WRITE setIntegrationId NOTIFY integrationIdChanged)
     Q_PROPERTY(QString friendlyName READ friendlyName WRITE setFriendlyName)
 
-    Q_INVOKABLE void connect()    = 0;  // Must be implemented by integration
+    Q_INVOKABLE void connect() = 0;     // Must be implemented by integration
     Q_INVOKABLE void disconnect() = 0;  // Must be implemented by integration
     Q_INVOKABLE void enterStandby() {}  // Can be overriden by integration
     Q_INVOKABLE void leaveStandby() {}  // Can be overriden by integration
     Q_INVOKABLE void sendCommand(const QString& type, const QString& entity_id, int command, const QVariant& param) = 0;
 
-    void setup(const QVariantMap& config, QObject* entities) {
+    void setup(const QVariantMap& config, EntitiesInterface* entities) {
         // FIXME remove QVariantMap indirection for friendlyName and integrationId:
         //       plugins MUST set them themself. Otherwise it's just very confusing without any benefits.
         for (QVariantMap::const_iterator iter = config.begin(); iter != config.end(); ++iter) {
@@ -58,12 +63,12 @@ class Integration : public QObject, IntegrationInterface {
             else if (iter.key() == "id")
                 m_integrationId = iter.value().toString();
         }
-        m_entities = qobject_cast<EntitiesInterface*>(entities);
+        m_entities = entities;
     }
 
     ~Integration() {}
 
-    // get the if the state
+    // get the state
     int state() { return m_state; }
 
     // set the state
@@ -103,16 +108,23 @@ class Integration : public QObject, IntegrationInterface {
     // set the friendly name of the integration
     void setFriendlyName(QString value) { m_friendlyName = value; }
 
- protected:
-    int                m_state = DISCONNECTED;
-    QString            m_integrationId;
-    QString            m_friendlyName;
-    EntitiesInterface* m_entities;
-
  signals:
     void integrationIdChanged();
     void connected();
     void connecting();
     void disconnected();
     void stateChanged();
+
+ protected:
+    int                m_state = DISCONNECTED;
+    QString            m_integrationId;
+    QString            m_friendlyName;
+    EntitiesInterface* m_entities;
+    /*
+    bool                    m_workerThread;
+    NotificationsInterface* m_notifications;
+    YioAPIInterface*        m_yioapi;
+    ConfigInterface*        m_config;
+    QLoggingCategory&       m_log;
+    */
 };
diff --git a/src/yio-plugin/integration_threadadapter.cpp b/src/yio-plugin/integration_threadadapter.cpp
@@ -20,12 +20,12 @@
  * SPDX-License-Identifier: GPL-3.0-or-later
  *****************************************************************************/
 
-#include "integrationproxy.h"
+#include "integration_threadadapter.h"
 
 // FIXME quick and dirty workaround until logging integration is fixed
 static Q_LOGGING_CATEGORY(CLASS_LC, "integration.threadAdapter");
 
-IntegrationProxy::IntegrationProxy(Integration& integration, Plugin* plugin)
+IntegrationThreadAdapter::IntegrationThreadAdapter(Integration& integration, Plugin* plugin)
     :  //    Integration(plugin),
       m_integration(integration) {
     setFriendlyName(integration.friendlyName());
@@ -36,53 +36,53 @@ IntegrationProxy::IntegrationProxy(Integration& integration, Plugin* plugin)
     // connect signals and slots
     QObject::connect(&m_thread, &QThread::finished, &integration, &QObject::deleteLater);
 
-    QObject::connect(this, &IntegrationProxy::connectSignal, &integration, &Integration::connect);
-    QObject::connect(this, &IntegrationProxy::disconnectSignal, &integration, &Integration::disconnect);
-    QObject::connect(this, &IntegrationProxy::enterStandbySignal, &integration, &Integration::enterStandby);
-    QObject::connect(this, &IntegrationProxy::leaveStandbySignal, &integration, &Integration::leaveStandby);
-    QObject::connect(this, &IntegrationProxy::sendCommandSignal, &integration, &Integration::sendCommand);
+    QObject::connect(this, &IntegrationThreadAdapter::connectSignal, &integration, &Integration::connect);
+    QObject::connect(this, &IntegrationThreadAdapter::disconnectSignal, &integration, &Integration::disconnect);
+    QObject::connect(this, &IntegrationThreadAdapter::enterStandbySignal, &integration, &Integration::enterStandby);
+    QObject::connect(this, &IntegrationThreadAdapter::leaveStandbySignal, &integration, &Integration::leaveStandby);
+    QObject::connect(this, &IntegrationThreadAdapter::sendCommandSignal, &integration, &Integration::sendCommand);
 
-    QObject::connect(&integration, &Integration::stateChanged, this, &IntegrationProxy::onStateChanged);
+    QObject::connect(&integration, &Integration::stateChanged, this, &IntegrationThreadAdapter::onStateChanged);
 
     m_thread.start();
 }
 
-IntegrationProxy::~IntegrationProxy() {
+IntegrationThreadAdapter::~IntegrationThreadAdapter() {
     if (m_thread.isRunning()) {
         m_thread.exit();
         m_thread.wait(5000);
     }
 }
 
-void IntegrationProxy::connect() {
-    qCDebug(CLASS_LC) << "Proxy connect";
+void IntegrationThreadAdapter::connect() {
+    qCDebug(CLASS_LC) << "ThreadAdapter connect";
     emit connectSignal();
 }
 
-void IntegrationProxy::disconnect() {
-    qCDebug(CLASS_LC) << "Proxy disconnect";
+void IntegrationThreadAdapter::disconnect() {
+    qCDebug(CLASS_LC) << "ThreadAdapter disconnect";
     emit disconnectSignal();
 }
 
-void IntegrationProxy::enterStandby() {
-    qCDebug(CLASS_LC) << "Proxy enterStandby";
+void IntegrationThreadAdapter::enterStandby() {
+    qCDebug(CLASS_LC) << "ThreadAdapter entering standby";
     emit enterStandbySignal();
 }
 
-void IntegrationProxy::leaveStandby() {
-    qCDebug(CLASS_LC) << "Proxy leaveStandby";
+void IntegrationThreadAdapter::leaveStandby() {
+    qCDebug(CLASS_LC) << "ThreadAdapter leaving standby";
     emit leaveStandbySignal();
 }
 
-void IntegrationProxy::sendCommand(const QString& type, const QString& entity_id, int command, const QVariant& param) {
-    qCDebug(CLASS_LC) << "Proxy sendCommand" << type << entity_id << command << param;
+void IntegrationThreadAdapter::sendCommand(const QString& type, const QString& entity_id, int command,
+                                           const QVariant& param) {
+    qCDebug(CLASS_LC) << "ThreadAdapter sendCommand" << type << entity_id << command << param;
     emit sendCommandSignal(type, entity_id, command, param);
 }
 
-// set the state
-void IntegrationProxy::onStateChanged() {
+void IntegrationThreadAdapter::onStateChanged() {
     m_state = m_integration.state();
-    // qCDebug(CLASS_LC) << "Proxy state changed" << static_cast<States>(m_state);
+    qCDebug(CLASS_LC) << "ThreadAdapter state changed" << static_cast<States>(m_state);
     emit stateChanged();
     switch (m_state) {
         case CONNECTING:
diff --git a/src/yio-plugin/integration_threadadapter.h b/src/yio-plugin/integration_threadadapter.h
@@ -29,12 +29,17 @@
 #include "yio-interface/integrationinterface.h"
 #include "yio-plugin/integration.h"
 
-class IntegrationProxy : public Integration {
+/**
+ * @brief The IntegrationThreadAdapter class is a convenient adapter to run an integration plugin within it's own
+ * thread. It takes care of proxying all signals between the integration interface and the plugin implementation.
+ */
+class IntegrationThreadAdapter : public Integration {
     Q_OBJECT
 
  public:
-    explicit IntegrationProxy(Integration& integration, Plugin* parent);  // NOLINT we need a non-const reference
-    ~IntegrationProxy() override;
+    explicit IntegrationThreadAdapter(Integration& integration,  // NOLINT we need a non-const reference
+                                      Plugin*      parent);
+    ~IntegrationThreadAdapter() override;
 
  public slots:  // NOLINT open issue: https://github.com/cpplint/cpplint/pull/99
     // set the state
diff --git a/src/yio-plugin/plugin.cpp b/src/yio-plugin/plugin.cpp
diff --git a/src/yio-plugin/plugin.h b/src/yio-plugin/plugin.h
diff --git a/yio-plugin-lib.pri b/yio-plugin-lib.pri
