The filter plugin is responsible to perform intermediate processing of incoming data after it has been received by the I/O socket and prior to it it being delivered to the protocol. It is also responsible to perform intermediate processing of outgoing data generated by the protocol and prior to it being delivered to I/O socket for sending.

The filters can be used to implement additional transport layer, such as MQTT or MQTT-SN. They can also be used to implement enctyption / decryption of the outgoing / incoming data.

Filter Class

To implement the required functionality the plugin's code must define its filter class inheriting from cc_tools_qt::Filter.

class MyFilter : public cc_tools_qt::Filter
{
    ...
};

If filter implementation uses Qt signals/slots infrastructure, it can use multiple inheritance and extend QObject as well.

class MyFilter : public QObject, public cc_tools_qt::Filter
{
    Q_OBJECT
    ...
private slots:
    ...
};

The cc_tools_qt::Filter 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.

Start / Stop

The filter object is not allowed to generate any events prior to being explicity started. It is also not allowed to generate any events after it has been exlicitly stopped. The driving application will use explicit calls to cc_tools_qt::Filter::start() and cc_tools_qt::Filter::stop() to control the operation of the filter. In order to receive the notifications on the start / stop operations, the actual filter class needs to override virtual cc_tools_qt::Filter::startImpl() and cc_tools_qt::Filter::stopImpl().

class MyFilter : public cc_tools_qt::Filter
{
    ...
protected:
    virtual bool startImpl() override;
    virtual void stopImpl() override;
};

Socket Connection Status

The communication link is driven by the socket plugin. Quite often it can be necessary for the filter plugin to be aware about socket connection status. To do so override the virtual cc_tools_qt::Filter::socketConnectionReportImpl() function

class MyFilter : public cc_tools_qt::Filter
{
    ...
protected:
    virtual void socketConnectionReportImpl(bool connected) override;
};

Processing Data

The new incoming data will be reported to the filter using virtual cc_tools_qt::Filter::recvDataImpl(). The derived class must override and implement it.

class MyFilter : public cc_tools_qt::Filter
{
    ...
protected:
    virtual QList<cc_tools_qt::DataInfoPtr> recvDataImpl(cc_tools_qt::DataInfoPtr dataPtr) override;
};

NOTE, that the return value from the function is a list of smart pointers to cc_tools_qt::DataInfo. Every such "data chunk" will be forwarded separately to the protocol or other filter up the chain.

The filter is allowed to consume the provided data and not to report anything for further processing. In this case the returned list will be empty.

The outgoing data generated by the protocol and/or other filter will be reported using virtual cc_tools_qt::Filter::sendDataImpl(). The derived class must override and implement it.

class MyFilter : public cc_tools_qt::Filter
{
    ...
protected:
    virtual QList<cc_tools_qt::DataInfoPtr> sendDataImpl(cc_tools_qt::DataInfoPtr dataPtr) override;
};

It is very similar to recvDataImpl() mentioned above

Generating Data

The filter class is allowed to generate outgoing data independently. It could be required when implementing "additional transport layer" filtering. If such data needs to be set, the filter class should use inherited cc_tools_qt::Filter::reportDataToSend() protected member function.

Reporting Errors

If there is any error discovered, the filter object is expected to report them using inherited cc_tools_qt::Filter::reportError() member function.

Plugin Class

Please read the Defining a Plugin page first to understand the way the plugins are defined.

The filter plugin must provide a callback to allocate the Filter object (the one that is derived from cc_tools_qt::Filter).

class MyFilterPlugin : public cc_tools_qt::Plugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "MyUniqueFilterId" FILE "my_filter.json")
    Q_INTERFACES(cc_tools_qt::Plugin)
 
public:
    MyFilterPlugin()
    {
        pluginProperties()
            .setFiltersCreateFunc(
                [this]() -> cc_tools_qt::PluginProperties::ListOfFilters
                {
                    cc_tools_qt::PluginProperties::ListOfFilters filters;
                    filters.append(cc_tools_qt::FilterPtr(new MyFilter));
                    return filters;
                });
    }
            
    ...
};

If the filter requires configuration, please also provide a callback which creates the widget when invoked (see Configuration Widget).

Table of Contents