#include "comms/protocol/ProtocolLayerBase.h"

Detailed Description

template<typename TField, typename TNextLayer, typename TDerived, typename... TOptions>
class comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >

Base class for all the middle (non MsgDataLayer) protocol transport layers.

Provides all the default and/or common functionality for the middle transport layer. The inheriting actual layer class may use and/or override the provided functionality by redefining member function with the same signature. The NextLayer is stored as a private data meber.

Template Parameters

TField	Every middle layer will have a field containing extra information for this layer. This template parameter is a type of such field.
TNextLayer	Next layer this one wraps and forwards the calls to.
TDerived	Actual protocol layer class that extends this one.
TOptions	Extra options. Supported ones are: comms::option::def::ProtocolLayerForceReadUntilDataSplit comms::option::def::ProtocolLayerDisallowReadUntilDataSplit

Inheritance diagram for comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >:

Public Types
using	AllFields = typename std::decay< decltype(std::tuple_cat(std::declval< std::tuple< Field > >(), std::declval< typename TNextLayer::AllFields >())) >::type
	Type of all the fields of all the transport layers wrapped in std::tuple. More...

using	AllMessages = typename NextLayer::AllMessages
	All supported messages. More...

using	Field = TField
	Type of the field used for this layer.

using	MsgFactory = typename NextLayer::MsgFactory
	Type of message factory. More...

using	MsgPtr = typename details::ProtocolLayerMsgPtr< NextLayer >::Type
	Type of pointer to the message. More...

using	NextLayer = TNextLayer
	Type of the next transport layer.

using	ParsedOptions = details::ProtocolLayerBaseOptionsParser< TOptions... >
	Parsed options structure.

using	ThisLayer = TDerived
	Actual derived class.

Public Member Functions
	ProtocolLayerBase (const ProtocolLayerBase &)=default
	Copy constructor.

	ProtocolLayerBase (ProtocolLayerBase &&)=default
	Move constructor.

template<typename... TArgs>
	ProtocolLayerBase (TArgs &&... args)
	Constructor. More...

	~ProtocolLayerBase () noexcept=default
	Desctructor.

template<typename TId >
MsgPtr	createMsg (TId &&id, unsigned idx=0)
	Create message object given the ID. More...

template<typename TMsg , typename TIter , typename TNextLayerUpdater >
comms::ErrorStatus	doUpdate (const TMsg &msg, Field &field, TIter &iter, std::size_t size, TNextLayerUpdater &&nextLayerUpdater) const
	Default implementation of the "update" functaionality. More...

template<typename TIter , typename TNextLayerUpdater >
comms::ErrorStatus	doUpdate (Field &field, TIter &iter, std::size_t size, TNextLayerUpdater &&nextLayerUpdater) const
	Default implementation of the "update" functaionality. More...

constexpr std::size_t	length () const
	Get remaining length of wrapping transport information. More...

template<typename TMsg >
constexpr std::size_t	length (const TMsg &msg) const
	Get remaining length of wrapping transport information + length of the provided message. More...

NextLayer &	nextLayer ()
	Get access to the next layer object.

const NextLayer &	nextLayer () const
	Get "const" access to the next layer object.

ProtocolLayerBase &	operator= (const ProtocolLayerBase &)=default
	Copy assignment.

template<typename TMsg , typename TIter , typename... TExtraValues>
comms::ErrorStatus	read (TMsg &msg, TIter &iter, std::size_t size, TExtraValues... extraValues)
	Deserialise message from the input data sequence. More...

template<typename TAllFields , typename TMsg , typename TIter , typename... TExtraValues>
comms::ErrorStatus	readFieldsCached (TAllFields &allFields, TMsg &msg, TIter &iter, std::size_t size, TExtraValues... extraValues)
	Deserialise message from the input data sequence while caching the read transport information fields. More...

template<typename TMsg , typename TIter , typename... TExtraValues>
comms::ErrorStatus	readFromData (TMsg &msg, TIter &iter, std::size_t size, TExtraValues... extraValues)
	Finalise the read operation by reading the message payload. More...

template<typename TAllFields , typename TMsg , typename TIter , typename... TExtraValues>
comms::ErrorStatus	readFromDataFieldsCached (TAllFields &allFields, TMsg &msg, TIter &iter, std::size_t size, TExtraValues... extraValues)
	Finalise the read operation by reading the message payload while caching the read transport information fields. More...

template<typename TMsg , typename TIter , typename... TExtraValues>
comms::ErrorStatus	readUntilData (TMsg &msg, TIter &iter, std::size_t size, TExtraValues... extraValues)
	Perform read of data fields until data layer (message payload). More...

template<typename TAllFields , typename TMsg , typename TIter , typename... TExtraValues>
comms::ErrorStatus	readUntilDataFieldsCached (TAllFields &allFields, TMsg &msg, TIter &iter, std::size_t size, TExtraValues... extraValues)
	Perform read of data fields until data layer (message payload) while caching the read transport information fields. More...

ThisLayer &	thisLayer ()
	Get access to this layer object.

const ThisLayer &	thisLayer () const
	Get "const" access to this layer object.

template<typename TMsg , typename TIter >
comms::ErrorStatus	update (const TMsg &msg, TIter &iter, std::size_t size) const
	Update recently written (using write()) message contents data. More...

template<typename TIter >
comms::ErrorStatus	update (TIter &iter, std::size_t size) const
	Update recently written (using write()) message contents data. More...

template<typename TAllFields , typename TMsg , typename TIter >
ErrorStatus	updateFieldsCached (TAllFields &allFields, const TMsg &msg, TIter &iter, std::size_t size) const
	Update recently written (using writeFieldsCached()) message data as well as cached transport information fields. More...

template<typename TAllFields , typename TIter >
ErrorStatus	updateFieldsCached (TAllFields &allFields, TIter &iter, std::size_t size) const
	Update recently written (using writeFieldsCached()) message data as well as cached transport information fields. More...

template<typename TMsg , typename TIter >
comms::ErrorStatus	write (const TMsg &msg, TIter &iter, std::size_t size) const
	Serialise message into output data sequence. More...

template<typename TAllFields , typename TMsg , typename TIter >
comms::ErrorStatus	writeFieldsCached (TAllFields &allFields, const TMsg &msg, TIter &iter, std::size_t size) const
	Serialise message into output data sequence while caching the written transport information fields. More...

Static Public Member Functions
template<typename TAllFields >
static auto	accessCachedField (TAllFields &allFields) -> decltype(std::get< std::tuple_size< typename std::decay< TAllFields >::type >::value - std::tuple_size< AllFields >::value >(allFields))
	Access appropriate field from "cached" bundle of all the protocol stack fields. More...

static constexpr bool	canSplitRead ()
	Compile time check whether split read "until" and "from" data layer is allowed.

static constexpr std::size_t	doFieldLength ()
	Default implementation of field length retrieval. More...

template<typename TMsg >
static constexpr std::size_t	doFieldLength (const TMsg &)
	Default implementation of field length retrieval when message is known. More...

Static Public Attributes
static const std::size_t	NumOfLayers = 1 + NextLayer::NumOfLayers
	Static constant indicating amount of transport layers used.

Protected Member Functions
template<typename... TExtraValues>
void	setMissingSize (std::size_t val, TExtraValues... extraValues) const
	Set the missing size information if such is requested. More...

template<typename TId , typename... TExtraValues>
void	setMsgId (TId val, TExtraValues... extraValues) const
	Set the message ID information if such is requested. More...

template<typename... TExtraValues>
void	setMsgIndex (std::size_t val, TExtraValues... extraValues) const
	Set the message index information if such is requested. More...

template<typename... TExtraValues>
void	updateMissingSize (const Field &field, std::size_t size, TExtraValues... extraValues) const
	Update the missing size information if such is requested. More...

template<typename... TExtraValues>
void	updateMissingSize (std::size_t size, TExtraValues... extraValues) const
	Update the missing size information if such is requested. More...

Static Protected Member Functions
template<typename TMsg , typename TIter >
static comms::ErrorStatus	doReadField (const TMsg *msgPtr, Field &field, TIter &iter, std::size_t len)
	Read the layer field. More...

template<typename TMsg , typename TIter >
static comms::ErrorStatus	doWriteField (const TMsg *msgPtr, const Field &field, TIter &iter, std::size_t len)
	Write the layer field. More...

template<std::size_t TIdx, typename TAllFields >
static Field &	getField (TAllFields &allFields)
	Retrieve reference to a layer specific field out of all fields. More...

template<typename T >
static constexpr bool	isMessageObjRef ()
	Detect whether type is actual message object. More...

template<typename TMsg >
static void	resetMsg (TMsg &msg)
	Reset msg in case it is a smart pointer (MsgPtr). More...

template<typename TMsg >
static auto	toMsgPtr (TMsg &msg) -> decltype(toMsgPtrInternal(msg, MsgTypeTag< typename std::decay< decltype(msg)>::type >()))
	Get a pointer to the message object. More...

Related Functions
(Note that these are not member functions.)
#define	COMMS_PROTOCOL_LAYERS_ACCESS(...) COMMS_DO_ACCESS_LAYER_ACC_FUNC(__VA_ARGS__)
	Provide convenience access functions to protocol layers. More...

#define	COMMS_PROTOCOL_LAYERS_ACCESS_INNER(...) COMMS_PROTOCOL_LAYERS_ACCESS(__VA_ARGS__)
	Same as COMMS_PROTOCOL_LAYERS_ACCESS()

#define	COMMS_PROTOCOL_LAYERS_ACCESS_OUTER(...) COMMS_PROTOCOL_LAYERS_ACCESS(COMMS_EXPAND(COMMS_REVERSE_MACRO_ARGS(__VA_ARGS__)))
	Provide convenience access functions to protocol layers. More...

#define	COMMS_PROTOCOL_LAYERS_NAMES(...)
	Provide names and convenience access functions to protocol layers. More...

#define	COMMS_PROTOCOL_LAYERS_NAMES_INNER(...) COMMS_PROTOCOL_LAYERS_NAMES(__VA_ARGS__)
	Same as COMMS_PROTOCOL_LAYERS_NAMES()

#define	COMMS_PROTOCOL_LAYERS_NAMES_OUTER(...) COMMS_PROTOCOL_LAYERS_NAMES(COMMS_EXPAND(COMMS_REVERSE_MACRO_ARGS(__VA_ARGS__)))
	Provide names and convenience access functions to protocol layers. More...

Member Typedef Documentation

◆ AllFields

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

using comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::AllFields = typename std::decay< decltype( std::tuple_cat( std::declval<std::tuple<Field> >(), std::declval<typename TNextLayer::AllFields>()) ) >::type

Type of all the fields of all the transport layers wrapped in std::tuple.

The Field type is prepended to the AllFields type of the NextLayer and reported as AllFields of this one.

◆ AllMessages

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

using comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::AllMessages = typename NextLayer::AllMessages

All supported messages.

Same as NextLayer::AllMessages or void if such doesn't exist. Expected to be overrided by comms::protocol::MsgIdLayer

◆ MsgFactory

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

using comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::MsgFactory = typename NextLayer::MsgFactory

Type of message factory.

Same as NextLayer::AllMessages or void if such doesn't exist. Expected to be overrided by comms::protocol::MsgIdLayer

◆ MsgPtr

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

using comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::MsgPtr = typename details::ProtocolLayerMsgPtr<NextLayer>::Type

Type of pointer to the message.

Same as NextLayer::MsgPtr or void if such doesn't exist.

Constructor & Destructor Documentation

◆ ProtocolLayerBase()

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename... TArgs>

comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::ProtocolLayerBase ( TArgs &&... args )

explicit

Constructor.

Forwards all the parameters to the constructor of the embedded NextLayer object.

Parameters

args	Arguments to be passed to the constructor of the next layer

Member Function Documentation

◆ accessCachedField()

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TAllFields >

static auto comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::accessCachedField ( TAllFields & allFields ) -> decltype(std::get<std::tuple_size<typename std::decay<TAllFields>::type>::value - std::tuple_size<AllFields>::value>(allFields))

static

Access appropriate field from "cached" bundle of all the protocol stack fields.

Parameters

allFields All fields of the protocol stack

Returns: Reference to requested field.

◆ createMsg()

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TId >

MsgPtr comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::createMsg	(	TId &&	id,
		unsigned	idx = `0`
	)

Create message object given the ID.

The default implementation is to forwards this call to the next layer. One of the layers (usually comms::protocol::MsgIdLayer) hides and overrides this implementation.

Template Parameters

TMsg	Type of message ID.

Parameters

id	ID of the message.
idx	Relative index of the message with the same ID.

Returns: Smart pointer (variant of std::unique_ptr) to allocated message object

◆ doFieldLength() [1/2]

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

static constexpr std::size_t comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::doFieldLength ( )

staticconstexpr

Default implementation of field length retrieval.

Default implementation returns

Field::minLength();

Note: Can be overriden by the extending class.

◆ doFieldLength() [2/2]

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TMsg >

static constexpr std::size_t comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::doFieldLength ( const TMsg & )

staticconstexpr

Default implementation of field length retrieval when message is known.

Default implementation returns

Field::minLength();

Note: Can be overriden by the extending class.

◆ doReadField()

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TMsg , typename TIter >

static comms::ErrorStatus comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::doReadField	(	const TMsg *	msgPtr,
		Field &	field,
		TIter &	iter,
		std::size_t	len
	)

staticprotected

Read the layer field.

The default implementation invokes read() operation of the passed field object. The function can be overriden by the extending class.

Parameters

[in]	msgPtr	Pointer to message object (if available), can be nullptr.
[out]	field	Field object value of which needs to be populated
[in,out]	iter	Iterator used for reading, expected to be advanced
[in]	len	Length of the input buffer

Note: May be non-static in the extending class

◆ doUpdate() [1/2]

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TMsg , typename TIter , typename TNextLayerUpdater >

comms::ErrorStatus comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::doUpdate	(	const TMsg &	msg,
		Field &	field,
		TIter &	iter,
		std::size_t	size,
		TNextLayerUpdater &&	nextLayerUpdater
	)		const

Default implementation of the "update" functaionality.

Similar to other doUpdate() but also receiving recently written message object.

Template Parameters

TMsg	Type of message object.
TIter	Type of iterator used for updating.
TNextLayerWriter	next layer updater object type.

Parameters

[in]	msg	Reference to message object.
[out]	field	Field that needs to be updated.
[in,out]	iter	Any random access iterator.
[in]	size	Number of bytes that have been written using write().
[in]	nextLayerUpdater	Next layer updater object.

◆ doUpdate() [2/2]

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TIter , typename TNextLayerUpdater >

comms::ErrorStatus comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::doUpdate	(	Field &	field,
		TIter &	iter,
		std::size_t	size,
		TNextLayerUpdater &&	nextLayerUpdater
	)		const

Default implementation of the "update" functaionality.

It will be invoked by update() or updateFieldsCached() member function, unless the derived class provides its own doUpdate() member function to override the default behavior.
This function in this layer does nothing, just advances the iterator by the length of the Field.

Template Parameters

TIter	Type of iterator used for updating.
TNextLayerWriter	next layer updater object type.

Parameters

[out]	field	Field that needs to be updated.
[in,out]	iter	Any random access iterator.
[in]	size	Number of bytes that have been written using write().
[in]	nextLayerUpdater	Next layer updater object.

◆ doWriteField()

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TMsg , typename TIter >

static comms::ErrorStatus comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::doWriteField	(	const TMsg *	msgPtr,
		const Field &	field,
		TIter &	iter,
		std::size_t	len
	)

staticprotected

Write the layer field.

The default implementation invokes write() operation of the passed field object. The function can be overriden by the extending class.

Parameters

[in]	msgPtr	Pointer to message object (if available), can be nullptr.
[out]	field	Field object value of which needs to be written
[in,out]	iter	Iterator used for writing, expected to be advanced
[in]	len	Length of the output buffer

Note: May be non-static in the extending class, but needs to be const.

◆ getField()

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<std::size_t TIdx, typename TAllFields >

static Field& comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::getField ( TAllFields & allFields )

staticprotected

Retrieve reference to a layer specific field out of all fields.

Template Parameters

TIdx	Index of the field in tuple

◆ isMessageObjRef()

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename T >

static constexpr bool comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::isMessageObjRef ( )

staticconstexprprotected

Detect whether type is actual message object.

Template Parameters

T	Type of the object

Returns: true if T type is extending comms::MessageBase, false otherwise.

◆ length() [1/2]

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

constexpr std::size_t comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::length ( ) const

constexpr

Get remaining length of wrapping transport information.

The message data always get wrapped with transport information to be successfully delivered to and unpacked on the other side. This function return remaining length of the transport information. It performs a call to doFieldLength() member function to get info about current field length. To update the default behaviour just override the function in the derived class.

Returns: length of the field + length reported by the next layer.

◆ length() [2/2]

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TMsg >

constexpr std::size_t comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::length ( const TMsg & msg ) const

constexpr

Get remaining length of wrapping transport information + length of the provided message.

This function usually gets called when there is a need to identify the size of the buffer required to write provided message wrapped in the transport information. This function is very similar to length(), but adds also length of the message. It performs a call to doFieldLength() member function with message parameter to get info about current field length. To update the default behaviour just override the function in the derived class.

Template Parameters

TMsg	Type of message object.

Parameters

[in] msg Message object

Returns: length of the field + length reported by the next layer.

◆ read()

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TMsg , typename TIter , typename... TExtraValues>

comms::ErrorStatus comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::read	(	TMsg &	msg,
		TIter &	iter,
		std::size_t	size,
		TExtraValues...	extraValues
	)

Deserialise message from the input data sequence.

The function will invoke doRead() member function provided by the derived class, which must have the following signature and logic:

template<typename TMsg, typename TIter, typename TNextLayerReader, typename... TExtraValues>
comms::ErrorStatus doRead(
    Field& field, // field object used to read required data
    TMsg& msg, // Ref to smart pointer to message object, or message object itself
    TIter& iter, // iterator used for reading
    std::size_t size, // size of the remaining data
    TNextLayerReader&& nextLayerReader, // next layer reader object
    TExtraValues... extraValues)
{
    // internal logic prior next layer read, such as reading the field value
    auto es = field.read(iter, size);
    ...
    // request next layer to perform read operation
    es = nextLayerReader.read(msg, iter, size - field.length(), extraValues...);
    ... // internal logic after next layer read if applicable
    return es;
};

The signature of the nextLayerReader.read() function is the same as the signature of this read() member function. The implemented doRead() member function also may use the following inherited protected member to set values of variadic parameters in case they are provided.

updateMissingSize() - to calculate update missing size if such is requested.
setMissingSize() - to set specific value as missing size if suce information is requested.
setMsgId() - to set the value of message id

setMsgIndex() - to set the value of message index.

Template Parameters

TMsg	Type of msg parameter
TIter	Type of iterator used for reading.

Parameters

[in,out]	msg	Reference to smart pointer, that already holds or will hold allocated message object, or reference to actual message object (which extends comms::MessageBase).
[in,out]	iter	Input iterator used for reading.
[in]	size	Size of the data in the sequence
[out]	extraValues	Extra output parameters provided using one of the following functions: comms::protocol::missingSize(), comms::protocol::msgId(), comms::protocol::msgIndex(), comms::protocol::msgPayload().

Returns: Status of the operation.

Precondition: Iterator must be valid and can be dereferenced and incremented at least "size" times;

Postcondition: The iterator will be advanced by the number of bytes was actually read. In case of an error, distance between original position and advanced will pinpoint the location of the error.; Returns comms::ErrorStatus::Success if and only if msg points to a valid object.

◆ readFieldsCached()

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TAllFields , typename TMsg , typename TIter , typename... TExtraValues>

comms::ErrorStatus comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::readFieldsCached	(	TAllFields &	allFields,
		TMsg &	msg,
		TIter &	iter,
		std::size_t	size,
		TExtraValues...	extraValues
	)

Deserialise message from the input data sequence while caching the read transport information fields.

Very similar to read() member function, but adds "allFields" parameter to store read transport information fields. The function will also invoke the same doRead() member function provided by the derived class, as described with read().

Template Parameters

TAllFields	std::tuple of all the transport fields, must be AllFields type defined in the last layer class that defines protocol stack.
TMsg	Type of msg parameter.
TIter	Type of iterator used for reading.

Parameters

[out]	allFields	Reference to the std::tuple object that wraps all transport fields (AllFields type of the last protocol layer class).
[in,out]	msg	Reference to smart pointer, that already holds or will hold allocated message object, or reference to actual message object (which extends comms::MessageBase).
[in,out]	iter	Iterator used for reading.
[in]	size	Number of bytes available for reading.
[out]	extraValues	Extra output parameters provided using one of the following functions comms::protocol::missingSize() comms::protocol::msgId() comms::protocol::msgIndex() comms::protocol::msgPayload()

Returns: Status of the operation.

◆ readFromData()

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TMsg , typename TIter , typename... TExtraValues>

comms::ErrorStatus comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::readFromData	(	TMsg &	msg,
		TIter &	iter,
		std::size_t	size,
		TExtraValues...	extraValues
	)

Finalise the read operation by reading the message payload.

Should be called to finalise the read operation started by readUntilData().

Template Parameters

TMsg	Type of msg parameter
TIter	Type of iterator used for reading.

Parameters

[in,out]	msg	Reference to smart pointer, that already holds or will hold allocated message object, or reference to actual message object (which extends comms::MessageBase).
[in,out]	iter	Input iterator used for reading.
[in]	size	Size of the data in the sequence
[out]	extraValues	Extra output parameters provided using one of the following functions comms::protocol::missingSize() comms::protocol::msgId() comms::protocol::msgIndex() comms::protocol::msgPayload()

Returns: Status of the operation.

Precondition: Iterator must be valid and can be dereferenced and incremented at least "size" times;

Postcondition: The iterator will be advanced by the number of bytes was actually read. In case of an error, distance between original position and advanced will pinpoint the location of the error.

◆ readFromDataFieldsCached()

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TAllFields , typename TMsg , typename TIter , typename... TExtraValues>

comms::ErrorStatus comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::readFromDataFieldsCached	(	TAllFields &	allFields,
		TMsg &	msg,
		TIter &	iter,
		std::size_t	size,
		TExtraValues...	extraValues
	)

Finalise the read operation by reading the message payload while caching the read transport information fields.

Should be called to finalise the read operation started by readUntilDataFieldsCached().

Template Parameters

TAllFields	std::tuple of all the transport fields, must be AllFields type defined in the last layer class that defines protocol stack.
TMsg	Type of msg parameter
TIter	Type of iterator used for reading.

Parameters

[out]	allFields	Reference to the std::tuple object that wraps all transport fields (AllFields type of the last protocol layer class).
[in,out]	msg	Reference to smart pointer, that already holds or will hold allocated message object, or reference to actual message object (which extends comms::MessageBase).
[in,out]	iter	Iterator used for reading.
[in]	size	Number of bytes available for reading.
[out]	extraValues	Extra output parameters provided using one of the following functions comms::protocol::missingSize() comms::protocol::msgId() comms::protocol::msgIndex() comms::protocol::msgPayload()

Returns: Status of the operation.

◆ readUntilData()

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TMsg , typename TIter , typename... TExtraValues>

comms::ErrorStatus comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::readUntilData	(	TMsg &	msg,
		TIter &	iter,
		std::size_t	size,
		TExtraValues...	extraValues
	)

Perform read of data fields until data layer (message payload).

Same as read by stops read operation when data layer is reached. Expected to be followed by a call to readFromData().

Template Parameters

TMsg	Type of msg parameter.
TIter	Type of iterator used for reading.

Parameters

[in,out]	msg	Reference to smart pointer, that already holds or will hold allocated message object, or reference to actual message object (which extends comms::MessageBase).
[in,out]	iter	Input iterator used for reading.
[in]	size	Size of the data in the sequence
[out]	extraValues	Extra output parameters provided using one of the following functions comms::protocol::missingSize() comms::protocol::msgId() comms::protocol::msgIndex() comms::protocol::msgPayload()

Returns: Status of the operation.

Precondition: Iterator must be valid and can be dereferenced and incremented at least "size" times;

Postcondition: The iterator will be advanced by the number of bytes was actually read. In case of an error, distance between original position and advanced will pinpoint the location of the error.; missingSize output value is updated if and only if function returns comms::ErrorStatus::NotEnoughData.

◆ readUntilDataFieldsCached()

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TAllFields , typename TMsg , typename TIter , typename... TExtraValues>

comms::ErrorStatus comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::readUntilDataFieldsCached	(	TAllFields &	allFields,
		TMsg &	msg,
		TIter &	iter,
		std::size_t	size,
		TExtraValues...	extraValues
	)

Perform read of data fields until data layer (message payload) while caching the read transport information fields.

Very similar to readUntilData() member function, but adds "allFields" parameter to store read transport information fields. The function will also invoke the same doRead() member function provided by the derived class, as described with read().

Template Parameters

TAllFields	std::tuple of all the transport fields, must be AllFields type defined in the last layer class that defines protocol stack.
TMsg	Type of msg parameter
TIter	Type of iterator used for reading.

Parameters

[out]	allFields	Reference to the std::tuple object that wraps all transport fields (AllFields type of the last protocol layer class).
[in,out]	msg	Reference to smart pointer, that already holds or will hold allocated message object, or reference to actual message object (which extends comms::MessageBase).
[in,out]	iter	Iterator used for reading.
[in]	size	Number of bytes available for reading.
[out]	extraValues	Extra output parameters provided using one of the following functions comms::protocol::missingSize() comms::protocol::msgId() comms::protocol::msgIndex() comms::protocol::msgPayload()

Returns: Status of the operation.

◆ resetMsg()

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TMsg >

static void comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::resetMsg ( TMsg & msg )

staticprotected

Reset msg in case it is a smart pointer (MsgPtr).

Does nothing if passed parameter is actual message object.

See also: isMessageObjRef().

◆ setMissingSize()

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename... TExtraValues>

void comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::setMissingSize	(	std::size_t	val,
		TExtraValues...	extraValues
	)		const

protected

Set the missing size information if such is requested.

Updates the value reference to which was passed to the "read" operation using comms::protocol::missingSize().

Parameters

[in]	val	Value to assign.
[out]	extraValues	Variadic parameters passed to the "read" function such as read() or readFieldsCached()

◆ setMsgId()

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TId , typename... TExtraValues>

void comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::setMsgId	(	TId	val,
		TExtraValues...	extraValues
	)		const

protected

Set the message ID information if such is requested.

Updates the value reference to which was passed to the "read" operation using comms::protocol::msgId().

Parameters

[in]	val	Value to assign.
[out]	extraValues	Variadic parameters passed to the "read" function such as read() or readFieldsCached()

◆ setMsgIndex()

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename... TExtraValues>

void comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::setMsgIndex	(	std::size_t	val,
		TExtraValues...	extraValues
	)		const

protected

Set the message index information if such is requested.

Updates the value reference to which was passed to the "read" operation using comms::protocol::msgIndex().

Parameters

[in]	val	Value to assign.
[out]	extraValues	Variadic parameters passed to the "read" function such as read() or readFieldsCached()

◆ toMsgPtr()

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TMsg >

static auto comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::toMsgPtr ( TMsg & msg ) -> decltype(toMsgPtrInternal(msg, MsgTypeTag<typename std::decay<decltype(msg)>::type>()))

staticprotected

Get a pointer to the message object.

The function works seamlessly for both smart pointer and reference to the real object

See also: isMessageObjRef().

◆ update() [1/2]

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TMsg , typename TIter >

comms::ErrorStatus comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::update	(	const TMsg &	msg,
		TIter &	iter,
		std::size_t	size
	)		const

Update recently written (using write()) message contents data.

Similar to other update() but also receiving recently written message object.

Parameters

[in]	msg	Reference to message object.
[in,out]	iter	Any random access iterator.
[in]	size	Number of bytes that have been written using write().

Returns: Status of the update operation.

◆ update() [2/2]

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TIter >

comms::ErrorStatus comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::update	(	TIter &	iter,
		std::size_t	size
	)		const

Update recently written (using write()) message contents data.

Sometimes, when NON random access iterator is used for writing (for example std::back_insert_iterator), some transport data cannot be properly written. In this case, write() function will return comms::ErrorStatus::UpdateRequired. When such status is returned it is necessary to call update() with random access iterator on the written buffer to update written dummy information with proper values.
The function will invoke doUpdate() member function provided (or inherited) by the derived class, which must have the following signature and logic:

template<typename TIter, typename TNextLayerUpdater>
comms::ErrorStatus doUpdate(
    Field& field, // field object to update and re-write if necessary
    TIter& iter, // iterator used for updateing
    std::size_t size, // Number of remaning bytes in the output buffer.
    TNextLayerUpdater&& nextLayerUpdater // next layer updater object
    )
{
    // internal logic prior next layer update, such as
    // updating field's value and re-writing it.
    field.value() = ...;
    auto es = field.write(iter, size);
    ...
    // request next layer to perform update operation
    es = nextLayerUpdater.update(iter, size - field.length());
    ... // internal logic after next layer write if applicable
    return es;
};

The signature of the nextLayerUpdater.update() function is the same as the signature of this update() member function.

Parameters

[in,out]	iter	Any random access iterator.
[in]	size	Number of bytes that have been written using write().

Returns: Status of the update operation.

◆ updateFieldsCached() [1/2]

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TAllFields , typename TMsg , typename TIter >

ErrorStatus comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::updateFieldsCached	(	TAllFields &	allFields,
		const TMsg &	msg,
		TIter &	iter,
		std::size_t	size
	)		const

Update recently written (using writeFieldsCached()) message data as well as cached transport information fields.

Very similar to other updateFieldsCached() member function, but adds "msg" parameter to access message object if needed.
The function will also invoke the same doUpdate() member function provided by the derived class, as described with write().

Template Parameters

TAllFields	std::tuple of all the transport fields, must be AllFields type defined in the last layer class that defines protocol stack.
TMsg	Type of msg parameter.
TIter	Type of the random access iterator.

Parameters

[out]	allFields	Reference to the std::tuple object that wraps all transport fields (AllFields type of the last protocol layer class).
[in]	msg	Reference to recently written message object.
[in,out]	iter	Random access iterator to the written data.
[in]	size	Number of bytes that have been written using writeFieldsCached().

Returns: Status of the update operation.

◆ updateFieldsCached() [2/2]

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TAllFields , typename TIter >

ErrorStatus comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::updateFieldsCached	(	TAllFields &	allFields,
		TIter &	iter,
		std::size_t	size
	)		const

Update recently written (using writeFieldsCached()) message data as well as cached transport information fields.

Very similar to update() member function, but adds "allFields" parameter to store raw data of the message.
The function will also invoke the same doUpdate() member function provided by the derived class, as described with write().

Template Parameters

TAllFields	std::tuple of all the transport fields, must be AllFields type defined in the last layer class that defines protocol stack.
TIter	Type of the random access iterator.

Parameters

[out]	allFields	Reference to the std::tuple object that wraps all transport fields (AllFields type of the last protocol layer class).
[in,out]	iter	Random access iterator to the written data.
[in]	size	Number of bytes that have been written using writeFieldsCached().

Returns: Status of the update operation.

◆ updateMissingSize() [1/2]

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename... TExtraValues>

void comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::updateMissingSize	(	const Field &	field,
		std::size_t	size,
		TExtraValues...	extraValues
	)		const

protected

Update the missing size information if such is requested.

Calculates the minimal required length to be yet read. Updates the value reference to which was passed to the "read" operation using comms::protocol::missingSize().

Parameters

[in]	field	Field read operation of which has failed.
[in]	size	Remaining number of bytes in the input buffer.
[out]	extraValues	Variadic parameters passed to the "read" function such as read() or readFieldsCached()

◆ updateMissingSize() [2/2]

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename... TExtraValues>

void comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::updateMissingSize	(	std::size_t	size,
		TExtraValues...	extraValues
	)		const

protected

Update the missing size information if such is requested.

Calculates the minimal required length to be yet read. Updates the value reference to which was passed to the "read" operation using comms::protocol::missingSize().

Parameters

[in]	size	Remaining number of bytes in the input buffer.
[out]	extraValues	Variadic parameters passed to the "read" function such as read() or readFieldsCached()

◆ write()

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TMsg , typename TIter >

comms::ErrorStatus comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::write	(	const TMsg &	msg,
		TIter &	iter,
		std::size_t	size
	)		const

Serialise message into output data sequence.

The function will invoke doWrite() member function provided by the derived class, which must have the following signature and logic:

template<typename TMsg, typename TIter, typename TNextLayerWriter>
comms::ErrorStatus doWrite(
    Field& field, // field object used to update and write required data
    const TMsg& msg, // reference to ready to be sent message object
    TIter& iter, // iterator used for writing
    std::size_t size, // Max number of bytes that can be written.
    TNextLayerWriter&& nextLayerWriter // next layer writer object
    )
{
    // internal logic prior next layer write, such as
    // updating field's value and writing it.
    field.value() = ...;
    auto es = field.write(iter, size);
    ...
    // request next layer to perform write operation
    es = nextLayerWriter.write(msg, iter, size - field.length());
    ... // internal logic after next layer write if applicable
    return es;
};

The signature of the nextLayerWriter.write() function is the same as the signature of this write() member function.

Template Parameters

TMsg	Type of the message being written.
TIter	Type of iterator used for writing.

Parameters

[in]	msg	Reference to message object
[in,out]	iter	Output iterator used for writing.
[in]	size	Max number of bytes that can be written.

Returns: Status of the write operation.

Precondition: Iterator must be valid and can be dereferenced and incremented at least "size" times;

Postcondition: The iterator will be advanced by the number of bytes was actually written. In case of an error, distance between original position and advanced will pinpoint the location of the error.

Returns: Status of the write operation.

◆ writeFieldsCached()

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

template<typename TAllFields , typename TMsg , typename TIter >

comms::ErrorStatus comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >::writeFieldsCached	(	TAllFields &	allFields,
		const TMsg &	msg,
		TIter &	iter,
		std::size_t	size
	)		const

Serialise message into output data sequence while caching the written transport information fields.

Very similar to write() member function, but adds "allFields" parameter to store raw data of the message. The function will also invoke the same doWrite() member function provided by the derived class, as described with write().

Template Parameters

TAllFields	std::tuple of all the transport fields, must be AllFields type defined in the last layer class that defines protocol stack.
TMsg	Type of the message being written.
TIter	Type of iterator used for writing.

Parameters

[out]	allFields	Reference to the std::tuple object that wraps all transport fields (AllFields type of the last protocol layer class).
[in]	msg	Reference to the message object that is being written,
[in,out]	iter	Iterator used for writing.
[in]	size	Max number of bytes that can be written.

Returns: Status of the write operation.

Friends And Related Function Documentation

◆ COMMS_PROTOCOL_LAYERS_ACCESS

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

#define COMMS_PROTOCOL_LAYERS_ACCESS ( ... ) COMMS_DO_ACCESS_LAYER_ACC_FUNC(__VA_ARGS__)

The first argument is a name for innermost layer (comms::protocol::MsgDataLayer), while the last one is the name for the outermost one.

◆ COMMS_PROTOCOL_LAYERS_ACCESS_OUTER

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

#define COMMS_PROTOCOL_LAYERS_ACCESS_OUTER ( ... ) COMMS_PROTOCOL_LAYERS_ACCESS(COMMS_EXPAND(COMMS_REVERSE_MACRO_ARGS(__VA_ARGS__)))

Similar to COMMS_PROTOCOL_LAYERS_ACCESS(), but the arguments are expected to be in reverse order, i.e. the first argument is the name of the outermost layer, while the last one is the name for the innermost one (comms::protocol::MsgDataLayer)

◆ COMMS_PROTOCOL_LAYERS_NAMES

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

#define COMMS_PROTOCOL_LAYERS_NAMES ( ... )

COMMS_DO_LAYER_TYPE_ALIAS(Base, __VA_ARGS__) \

COMMS_DO_ACCESS_LAYER_ACC_FUNC(__VA_ARGS__)

Provide names and convenience access functions to protocol layers.

Similar to COMMS_PROTOCOL_LAYERS_ACCESS() but defines "Layer_<name>" type names.

Precondition: Requires definition of inner "Base" type aliasing the base class.

◆ COMMS_PROTOCOL_LAYERS_NAMES_OUTER

template<typename TField , typename TNextLayer , typename TDerived , typename... TOptions>

#define COMMS_PROTOCOL_LAYERS_NAMES_OUTER ( ... ) COMMS_PROTOCOL_LAYERS_NAMES(COMMS_EXPAND(COMMS_REVERSE_MACRO_ARGS(__VA_ARGS__)))

Similar to COMMS_PROTOCOL_LAYERS_ACCESS_OUTER() but defines "Layer_<name>" type names.

Precondition: Requires definition of inner "Base" type aliasing the base class.

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

include/comms/protocol/ProtocolLayerBase.h

Detailed Description

template<typename TField, typename TNextLayer, typename TDerived, typename... TOptions> class comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Related Functions

Member Typedef Documentation

◆ AllFields

◆ AllMessages

◆ MsgFactory

◆ MsgPtr

Constructor & Destructor Documentation

◆ ProtocolLayerBase()

Member Function Documentation

◆ accessCachedField()

◆ createMsg()

◆ doFieldLength() [1/2]

◆ doFieldLength() [2/2]

◆ doReadField()

◆ doUpdate() [1/2]

◆ doUpdate() [2/2]

◆ doWriteField()

◆ getField()

◆ isMessageObjRef()

◆ length() [1/2]

◆ length() [2/2]

◆ read()

◆ readFieldsCached()

◆ readFromData()

◆ readFromDataFieldsCached()

◆ readUntilData()

◆ readUntilDataFieldsCached()

◆ resetMsg()

◆ setMissingSize()

◆ setMsgId()

◆ setMsgIndex()

◆ toMsgPtr()

◆ update() [1/2]

◆ update() [2/2]

◆ updateFieldsCached() [1/2]

◆ updateFieldsCached() [2/2]

◆ updateMissingSize() [1/2]

◆ updateMissingSize() [2/2]

◆ write()

◆ writeFieldsCached()

Friends And Related Function Documentation

◆ COMMS_PROTOCOL_LAYERS_ACCESS

◆ COMMS_PROTOCOL_LAYERS_ACCESS_OUTER

◆ COMMS_PROTOCOL_LAYERS_NAMES

◆ COMMS_PROTOCOL_LAYERS_NAMES_OUTER

template<typename TField, typename TNextLayer, typename TDerived, typename... TOptions>
class comms::protocol::ProtocolLayerBase< TField, TNextLayer, TDerived, TOptions >