adtf::filter::cSubstreamHandling Class Reference

#include <substream_handling.h>

Inherited by adtf::filter::substream_filter< FilterBase > [protected].

Public Types
using	tSampleCallback = std::function<void(const adtf::ucom::iobject_ptr<const adtf::streaming::ISample>&)>
	a function that processes samples
using	tGeneratorCallback = std::function<tSampleCallback(const adtf::ucom::iobject_ptr<const adtf::streaming::IStreamType>&)>
	a function that generates a function that processes samples for a given stream type.
using	tNamedGeneratorCallback = std::function<tSampleCallback(const std::string&, const adtf::ucom::iobject_ptr<const adtf::streaming::IStreamType>&)>
	a function that generates a function that processes samples for a given substream name and stream type.
using	tElementValue = std::variant<bool, int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t, uint64_t, float, double>

Public Member Functions
	cSubstreamHandling ()
	cSubstreamHandling (adtf::filter::cGraphObject *pFilter, const std::string &strInputPinName, bool bForwardTriggerViaOutputPins=true)
	cSubstreamHandling (cSubstreamHandling &&oOther)
cSubstreamHandling &	operator= (cSubstreamHandling &&oOther)
	cSubstreamHandling (const cSubstreamHandling &)=delete
cSubstreamHandling &	operator= (const cSubstreamHandling &)=delete
void	AddSubstreamHandler (const std::string &strName, tGeneratorCallback fnGeneratorCallback)
void	AddSubstreamHandler (const std::regex &strNameExpression, tNamedGeneratorCallback fnGeneratorCallback)
void	AddSubstreamHandler (const std::string &strName, tSampleCallback fnCallback)
void	AddElementHandler (const std::string &strSubstreamName, const std::string &strElementName, std::function< void(adtf::base::flash::tNanoSeconds, tElementValue)> fnCallback, bool bNameHeuristic=false)
template<typename T>
void	AddElementHandler (const std::string &strSubstreamName, const std::string &strElementName, std::function< void(adtf::base::flash::tNanoSeconds, T)> fnCallback, bool bNameHeuristic=false)
void	RemoveAllHandlers ()

Detailed Description

Utility class to handle substream routing within a filter.

This class will perform all the substream request handling and routing for you. You can create multiple instances within one filter to seperate multiple inputs. if you only require a single input, you can also use cSubstreamFilter or substream_filter.

An example usage would look like this:

#include <adtffiltersdk/adtf_filtersdk.h>
 
class cMyFilter: public adtf::filter::cFilter
{
    public:
        ADTF_CLASS_ID_NAME(cMyFilter, "my_filter.filter.example.cid", "My Filter");
        
        cMyFilter()
        {
            m_oInput = adtf::filter::cSubstreamHandling(this, "input");
            m_oInput.AddSubstreamHandler("your.substream.name", [this](const adtf::ucom::iobject_ptr<const adtf::streaming::ISample>& pSample)
            {
                LOG_INFO("received a sample on substream 'your.substream.name'");
            });
        }
 
    private:
        adtf::filter::cSubstreamHandling m_oInput;
};

Member Typedef Documentation

tElementValue

using adtf::filter::cSubstreamHandling::tElementValue = std::variant<bool, int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t, uint64_t, float, double>

Element Variant value type that can contain any of the primitive types that are supported by the media description (i.e. int, float, bool, etc.)

Constructor & Destructor Documentation

cSubstreamHandling() [1/3]

adtf::filter::cSubstreamHandling::cSubstreamHandling

(

)

Constructs an empty object that cannot perform any operations other than being assigned another value.

cSubstreamHandling() [2/3]

adtf::filter::cSubstreamHandling::cSubstreamHandling	(	adtf::filter::cGraphObject *	pFilter,
		const std::string &	strInputPinName,
		bool	bForwardTriggerViaOutputPins = true )

Constructs a new object that will create an input pin at the given graph object (i.e. filter).

Example Usage

#include <adtffiltersdk/adtf_filtersdk.h>
 
class cMyFilter: public adtf::filter::cFilter
{
    public:
        ADTF_CLASS_ID_NAME(cMyFilter, "my_filter.filter.example.cid", "My Filter");
        
        cMyFilter()
        {
            m_oInput = adtf::filter::cSubstreamHandling(this, "input");
            m_oInput.AddSubstreamHandler("your.substream.name", [this](const adtf::ucom::iobject_ptr<const adtf::streaming::ISample>& pSample)
            {
                LOG_INFO("received a sample on substream 'your.substream.name'");
            });
        }
 
    private:
        adtf::filter::cSubstreamHandling m_oInput;
};

Parameters

[in]	pFilter	The filter instance where the input pin should be created at.
[in]	strInputPinName	The name of the input pin.
[in]	bForwardTriggerViaOutputPins	If true, triggers will be forwarded via all output pins after all handlers were called.

cSubstreamHandling() [3/3]

adtf::filter::cSubstreamHandling::cSubstreamHandling

(

cSubstreamHandling &&

oOther

)

Move constructor.

Parameters

[in]

oOther

The other instance to move from.

Member Function Documentation

AddElementHandler() [1/2]

template<typename T>

void adtf::filter::cSubstreamHandling::AddElementHandler ( const std::string & strSubstreamName, const std::string & strElementName, std::function< void(adtf::base::flash::tNanoSeconds, T)> fnCallback, bool bNameHeuristic = false )

inline

Installs a handler for the given element of the given substream.

Use this version when you need the element value in a specific type (i.e. double)

Example Usage

m_oInput.AddElementHandler<uint32_t>("your.substream.name", "the.name.of.the.structure.element", [this](adtf::base::tNanoSeconds tmTimeStamp, uint32_t nValue)
{
    LOG_INFO("received an element value of %" PRIu32, nValue);
});

Template Parameters

T	The type that the element value should be converted to.

Parameters

[in]	strSubstreamName	The name of the substream.
[in]	strElementName	The elements name i.e. "first.second.leaf"
[in]	fnCallback	This is called with the timestamp and the value of the element whenever a sample is recieved.
[in]	bNameHeuristic	If true, different variants of the element name will be tried as well (i.e. with ".phy" or ".raw" appended, etc.)

AddElementHandler() [2/2]

void adtf::filter::cSubstreamHandling::AddElementHandler	(	const std::string &	strSubstreamName,
		const std::string &	strElementName,
		std::function< void(adtf::base::flash::tNanoSeconds, tElementValue)>	fnCallback,
		bool	bNameHeuristic = false )

Installs a handler for the given element of the given substream.

The element value is handed over as a variant containing the original element value type. You can use std::visit to access the contained value in a type safe manner.

There is also a convenience template function AddElementHandler<> in case you want the value in a specific type. (i.e. double)

Example Usage

m_oInput.AddElementHandler("your.substream.name", "the.name.of.the.structure.element", [this](adtf::base::tNanoSeconds tmTimeStamp, adtf::filter::cSubstreamHandling::tElementValue xValue)
{
    LOG_INFO("received an element value of type: %zu", xValue.index());
 
    // you can use std::visit() to access the value in a type safe manner.                
});

Parameters

[in]	strSubstreamName	The name of the substream.
[in]	strElementName	The elements name i.e. "first.second.leaf"
[in]	fnCallback	This is called with the timestamp and the value of the element whenever a sample is recieved.
[in]	bNameHeuristic	If true, different variants of the element name will be tried as well (i.e. with ".phy" or ".raw" appended, etc., elements representing physical values will be preferred)

AddSubstreamHandler() [1/3]

void adtf::filter::cSubstreamHandling::AddSubstreamHandler	(	const std::regex &	strNameExpression,
		tNamedGeneratorCallback	fnGeneratorCallback )

Installs a handler generator that will be called for each available substream that matches the regular expression This allows you to assign handlers based on name and the stream type.

Example Usage

m_oInput.AddSubstreamHandler(std::regex("my_prefix_.*"), [this](const std::string& strSubstreamName, const adtf::ucom::iobject_ptr<const adtf::streaming::IStreamType>& pType)
{
    return [this, strSubstreamName](const adtf::ucom::iobject_ptr<const adtf::streaming::ISample>& pSample) // you can pass along/store required data via the lambda capture clause
    {
        LOG_INFO("received a sample on substream '%s'", strSubstreamName.c_str());    
    };
});

Parameters

[in]	strNameExpression	A regular expression to match the substream names against.
[in]	fnGeneratorCallback	This is called for each substream whenever the stream type changes. Return an empty std::function when you want to ignore a certain substream.

AddSubstreamHandler() [2/3]

void adtf::filter::cSubstreamHandling::AddSubstreamHandler	(	const std::string &	strName,
		tGeneratorCallback	fnGeneratorCallback )

Installs a handler generator for the given substream. This allows you to assign handlers based on the stream type.

Example Usage

m_oInput.AddSubstreamHandler("your.substream.name", [this](const adtf::ucom::iobject_ptr<const adtf::streaming::IStreamType>& pType)
{
    std::string strMetaType;
    pType->GetMetaTypeName(adtf_string_intf(strMetaType));
    LOG_INFO("Found substream 'your.substream.name' with type '%s'", strMetaType.c_str());
 
    return [this, strMetaType](const adtf::ucom::iobject_ptr<const adtf::streaming::ISample>& pSample) // you can pass along/store required data via the lambda capture clause
    {
        LOG_INFO("received a sample on substream 'your.substream.name' with type '%s'", strMetaType.c_str());    
    };
});

Parameters

[in]	strName	The name of the substream.
[in]	fnGeneratorCallback	This is called whenever a stream becomes available. Return an empty std::function when you want to ignore the substream.

AddSubstreamHandler() [3/3]

void adtf::filter::cSubstreamHandling::AddSubstreamHandler	(	const std::string &	strName,
		tSampleCallback	fnCallback )

Installs a handler for samples of the given substream.

Example Usage

m_oInput.AddSubstreamHandler("your.substream.name", [this](const adtf::ucom::iobject_ptr<const adtf::streaming::ISample>& pSample)
{
    LOG_INFO("received a sample on substream 'your.substream.name'");
});

Parameters

[in]	strName	The name of the substream.
[in]	fnCallback	Callback function for each received sample.

operator=()

cSubstreamHandling & adtf::filter::cSubstreamHandling::operator=

(

cSubstreamHandling &&

oOther

)

Move assignment operator.

Parameters

[in]

oOther

The other instance to move from.

Returns

cSubstreamHandling& Reference to this instance.

RemoveAllHandlers()

void adtf::filter::cSubstreamHandling::RemoveAllHandlers

(

)

Removes all installed handlers. Call this in the aquivalent shutdown stage to where you added them.

Example Usage

#include <adtffiltersdk/adtf_filtersdk.h>
 
class cMyFilter: public adtf::filter::cFilter
{
    public:
        ADTF_CLASS_ID_NAME(cMyFilter, "my_filter.filter.example.cid", "My Filter");
 
        cMyFilter()
        {
            m_oInput = adtf::filter::cSubstreamHandling(this, "input");
        }
        
        tResult Init(tInitStage eStage)
        {
            RETURN_IF_FAILED(cFilter::Init(eStage))
 
            if (eStage == StageNormal)
            {
                // this could be based on some confiugration file etc.
                m_oInput.AddSubstreamHandler("your.substream.name", [this](const adtf::ucom::iobject_ptr<const adtf::streaming::ISample>& pSample)
                {
                    LOG_INFO("received a sample on substream 'your.substream.name'");
                });
            }
 
            RETURN_NOERROR;
        }
 
        tResult Shutdown(tInitStage eStage)
        {
            if (eStage == StageNormal)
            {
                m_oInput.RemoveAllHandlers();
            }
 
            return cFilter::Shutdown(eStage);
        }
 
    private:
        adtf::filter::cSubstreamHandling m_oInput;
};

---

The documentation for this class was generated from the following file:

• src/libraries/filtersdk/include/adtffiltersdk/substream_handling.h