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. They can also be used to implement encryption / 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::ToolsFilter.

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

The cc_tools_qt::ToolsFilter class is implemented using Non-Virtual Interface Idiom. Its 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 explicitly started. It is also not allowed to generate any events after it has been explicitly stopped. The driving application will use explicit calls to cc_tools_qt::ToolsFilter::start() and cc_tools_qt::ToolsFilter::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 startImpl() and stopImpl() member functions.

class MyFilter : public cc_tools_qt::ToolsFilter
{
    ...
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 socketConnectionReportImpl() member function

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

Processing Data

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

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

NOTE, that the return value from the function is a list of smart pointers to the cc_tools_qt::ToolsDataInfo. 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 sendDataImpl() member function. The derived class must override and implement it.

class MyFilter : public cc_tools_qt::ToolsFilter
{
    ...
protected:
    virtual QList<cc_tools_qt::ToolsDataInfoPtr> sendDataImpl(cc_tools_qt::ToolsDataInfoPtr 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 reportDataToSend() protected member function.

Reporting Errors

If there is any error discovered, the filter object is expected to report them using inherited 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 specify its type as Type_Filter and override createFilterImpl() virtual member function.

class MyFilterPlugin : public cc_tools_qt::ToolsPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "MyUniqueFilterId" FILE "my_filter.json")
    Q_INTERFACES(cc_tools_qt::ToolsPlugin)
 
    using Base = cc_tools_qt::ToolsPlugin;
 
public:
    MyFilterPlugin() : Base(Type_Filter) {}
            
protected:
    virtual cc_tools_qt::ToolsFilterPtr createFilterImpl() override {...}
    ...
};

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

Table of Contents