This project uses Qt Infrastructure to define and load plugins. The custom plugin definition shared object needs to contain its own Plugin class that inherits from cc_tools_qt::Plugin and uses various Qt macros to describe itself. As an example please take a look at EchoSocketPlugin.h from this project.

class EchoSocketPlugin : public cc_tools_qt::Plugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "cc.EchoSocketPlugin" FILE "echo_socket.json")
    Q_INTERFACES(cc_tools_qt::Plugin)
    ...
};

It must contain Q_PLUGIN_METADATA() macro with unique ID of the plugin and name of the file that contains a detailed plugin description. The file contents are expected to be a valid JSON object with three values:

name - Short, human readable name of the plugin
desc - Multi line description of the plugin. The value is expected to be JSON array of strings.
type - Type of the plugin, can be one of the following: socket, filter, or protocol.

Please take a look at echo_socket.json as an example.

{
    "name" : "CC Echo Socket",
    "desc" : [
        "This socket duplicates outgoing data and echoes it as an incoming one."
    ],
    "type" : "socket"
}

The plugin definition class must also contain explicit declaration of implementing cc_tools_qt::Plugin interface using Q_INTERFACES() macro.

Also, don't forget to use Q_OBJECT macro and run moc utility on the header when building the plugin's shared library.

Plugin Configuration

Some plugins may require an ability to be configured. For example, remote address and/or port for TCP/IP client socket.

The CommsChampion Tools implement an ability to save and load the list of plugins with their respective configurations. Such list as well as plugins' configurations are stored in single file as human readable json object. The Qt framework implements its own parsing and handling of such files. The parsed json object is returned as QVariantMap. When requested, every plugin must be able to provide its own configuration by filling the given QVariantMap object as well as retrieve and apply the new configuration from it.

The cc_tools_qt::Plugin class is implemented using
Non-Virtual Interface Idiom It's non-virtual public interface is used by the driving application. The inheriting class needs to implement virtual *Impl() functions to override the default behaviour.

The cc_tools_qt::Plugin class defines the following virtual functions that are used for getting / setting the plugin's configuration.

namespace cc_tools_qt
{
class Plugin : public QObject
{
    ...
protected:
    // Retrieve current configuration
    virtual void getCurrentConfigImpl(QVariantMap& config);
 
    // Apply new configuration
    virtual void reconfigureImpl(const QVariantMap& config);
};
} // namespace cc_tools_qt

If the custom plugin being implemented requires external configuration, the inheriting class is expected to override these functions. It is recommended that the plugin will bundle its full configuration as single QVariantMap object, which will be inserted as one value into the provided QVariantMap full configuration object. For example, let's take a look at TCP/IP Client Socket plugin configuration:

const QString MainConfigKey("cc_tcp_client_socket");
const QString HostSubKey("host");
const QString PortSubKey("port");
 
void TcpClientSocketPlugin::getCurrentConfigImpl(QVariantMap& config)
{
    ...
 
    // Create QVariantMap to contain plugin configuration
    QVariantMap subConfig; 
 
    // Store host address and port info
    subConfig.insert(HostSubKey, m_socket->getHost()); 
    subConfig.insert(PortSubKey, m_socket->getPort()); 
 
    // Insert the configuration map as single value into provided full configuration map
    config.insert(MainConfigKey, QVariant::fromValue(subConfig)); 
}
 
void TcpClientSocketPlugin::reconfigureImpl(const QVariantMap& config)
{
    // Retrieve the relevant configuration containing object
    auto subConfigVar = config.value(MainConfigKey);
    if ((!subConfigVar.isValid()) || (!subConfigVar.canConvert<QVariantMap>())) {
        return;
    }
    auto subConfig = subConfigVar.value<QVariantMap>();
 
    ...
 
    // Retrieve and configure the remote host address
    auto hostVar = subConfig.value(HostSubKey);
    if (hostVar.isValid() && hostVar.canConvert<QString>()) {
        auto host = hostVar.value<QString>();
        m_socket->setHost(host);
    }
 
    // Retrieve and configure the remote port number
    typedef Socket::PortType PortType;
    auto portVar = subConfig.value(PortSubKey);
    if (portVar.isValid() && portVar.canConvert<PortType>()) {
        auto port = portVar.value<PortType>();
        m_socket->setPort(port);
    }
}

Plugin Properties

In addition to explained above configuration, the plugin is expected to apply extra properties which will allow the running application to use it properly. The cc_tools_qt::Plugin class provides an access to cc_tools_qt::PluginProperties object, which is stored as its data member.

namespace cc_tools_qt
{
class Plugin : public QObject
{
    ...
protected:
    // Get access to properties object
    PluginProperties& pluginProperties();
 
private:
    PluginProperties m_props;
};
}  // namespace cc_tools_qt

The deriving Plugin class is expected to grab a hold on the properties object and apply its relevant properties.

class MyPlugin : public cc_tools_qt::Plugin
{
    ...
public:
    MyPlugin()
    {
        pluginProperties()
            .setSocketCreateFunc(
                [this]() -> cc_tools_qt::SocketPtr
                {
                    ...
                })
            .setConfigWidgetCreateFunc(
                [this]() -> QWidget*
                {
                    ...
                });
    }
    ...
};

Let's take a look at available properties one by one.

Socket Allocation Callback

The Socket plugin (see Developing Custom Socket Plugin) is expected to be able to create and return cc_tools_qt::Socket object when requested. However, it is up to the application to decide when. As the result, the actual plugin class needs to provide a callback to be called when new cc_tools_qt::Socket object is required. It is done using call to cc_tools_qt::PluginProperties::setSocketCreateFunc().

class MySocketPlugin : public cc_tools_qt::Plugin
{
    ...
public:
    MySocketPlugin()
    {
        pluginProperties()
            .setSocketCreateFunc(
                [this]() -> cc_tools_qt::SocketPtr
                {
                    ...
                });
    }
    ...
};

Protocol Allocation Callback

The Protocol plugin (see Developing Custom Protocol Plugin) is expected to be able to create and return cc_tools_qt::Protocol object when requested. However, it is up to the application to decide when. As the result, the actual plugin class needs to provide a callback to be called when new cc_tools_qt::Protocol object is required. It is done using call to cc_tools_qt::PluginProperties::setProtocolCreateFunc().

class MyProtocolPlugin : public cc_tools_qt::Plugin
{
    ...
public:
    MyProtocolPlugin()
    {
        pluginProperties()
            .setProtocolCreateFunc(
                [this]() -> cc_tools_qt::ProtocolPtr
                {
                    ...
                });
    }
    ...
};

Filter Allocation Callback

The Filter plugin (see Developing Custom Filter Plugin) is expected to be able to create and return cc_tools_qt::Filter object when requested. However, it is up to the application to decide when. As the result, the actual plugin class needs to provide a callback to be called when new cc_tools_qt::Filter object is required. It is done using call to cc_tools_qt::PluginProperties::setFiltersCreateFunc().

class MyFilterPlugin : public cc_tools_qt::Plugin
{
    ...
public:
    MyFilterPlugin()
    {
        pluginProperties()
            .setFiltersCreateFunc(...);
    }
    ...
};

Configuration Widget

As was mentioned earlier, the plugin may require some configuration. The command line application will receive required parameters via command line arguments. The GUI application, on the other hand, must provide a convenient way to allow user to perform such configuration.

The developed plugins are expected to be used "as-is" with any of the CommsChampion Tools applications, both GUI and command-line ones. As the result, the developed plugin is expected to be able to create and return a widget object, which will be displayed by the GUI application at some stage. If plugin requires configuration it should also provide a callback to allow creation of such widget. Use cc_tools_qt::PluginProperties::setConfigWidgetCreateFunc() function to set the callback.

class MyPlugin : public cc_tools_qt::Plugin
{
    ...
public:
    MyPlugin()
    {
        pluginProperties()
            .setConfigWidgetCreateFunc(
                [this]() -> QWidget*
                {
                    return new MyConfigWidget(...);
                });
    }
    ...
};

NOTE, that the callback returns dynamically allocated widget object, which will be owned by the running application. The plugin does NOT need to store the pointer and delete it later.

GUI Actions

For user's convenience, the plugin may also create multiple QAction objects. This objects will be inserted into main toolbar of the GUI application allowing users to perform quick updates / notifications to the running plugins. Use cc_tools_qt::PluginProperties::setGuiActionsCreateFunc() function to set the callback.

class MyPlugin : public cc_tools_qt::Plugin
{
    ...
public:
    MyPlugin()
    {
        pluginProperties()
            .setGuiActionsCreateFunc(...);
    }
    ...
};

Table of Contents