#include "comms/MessageBase.h"
Detailed Description
class comms::MessageBase< TMessage, TOptions >
Base class for all the custom protocol messages.
The main purpose of this class is to provide default implementation for some pure virtual functions defined in Message class. Just like with Message class, the provided methods implementation depends on the options passed as TOption template parameter.
- Template Parameters
-
TMessage The main interface class of the custom protocol messages. It may be either Message class itself or any other class that extends Message. The MessageBase inherits from class provided as TMessage template parameter. As the result the real inheritance diagram will look like: comms::Message <– TMessage <– comms::MessageBase. TOptions Variadic template parameter that can include zero or more options that specify behaviour. The options may be comma separated as well as bundled into std::tuple. Supported options are: - comms::option::def::StaticNumIdImpl - In case message have numeric IDs (comms::Message::MsgIdType is of integral or enum type), usage of this option will cause this class to implement getIdImpl() virtual function that returns provided numeric value.
- comms::option::def::NoIdImpl - Some message may not have valid IDs and their getId() function is never going to be called. Usage of this option will create dummy implementation of getIdImpl() virtual function that contains always failing assertion. In DEBUG mode compilation the application will crash while in release mode the default constructed value of comms::Message::MsgIdType will be returned.
- comms::option::def::MsgType - Provide type of actual message that inherits from this comms::MessageBase class.
- comms::option::def::FieldsImpl - Usually implementation of read, write, validity check, and length calculation is pretty straight forward. For example the message is considered valid if all the field values are considered to be valid, or read operation is to perform read for all the fields in the message. If the comms::option::def::FieldsImpl option with all the message field classes bundled into the std::tuple is provided, then MessageBase class can implement readImpl(), writeImpl(), validImpl(), lengthImpl() virtual functions declared as pure in comms::Message interface. The option also provides an accessor functions to the all the field objects: fields().
- comms::option::def::ZeroFieldsImpl - This option is an alias to comms::option::def::FieldsImpl<std::tuple<> >, which provides implementation readImpl(), writeImpl(), validImpl(), lengthImpl() virtual functions when message contains no fields, i.e. readImpl() and writeImple() will always report success doing nothing, validImpl() will always return true, and lengthImpl() will always return 0.
- comms::option::def::HasCustomRefresh - Notify comms::MessageBase that there is custom doRefresh() member function in the message definition class.
- comms::option::def::HasDoGetId - Enable implementation of getIdImpl() even if comms::option::def::StaticNumIdImpl option wasn't used. Must be paired with comms::option::def::MsgType.
- comms::option::def::HasName - Notify comms::MessageBase that there is custom doName() member function in the message definition class.
- comms::option::def::FailOnInvalid - Fail the read operation if the contents are invalid.
- comms::option::app::NoReadImpl - Inhibit the implementation of readImpl().
- comms::option::app::NoWriteImpl - Inhibit the implementation of writeImpl().
- comms::option::app::NoLengthImpl - Inhibit the implementation of lengthImpl().
- comms::option::app::NoValidImpl - Inhibit the implementation of validImpl().
- comms::option::app::NoDispatchImpl - Inhibit the implementation of dispatchImpl().
Public Types | |
| using | AllFields = FieldsProvidedWithOption |
| All field classes provided with comms::option::def::FieldsImpl option. | |
| using | DispatchRetType = typename Handler::RetType |
| Return type of the dispatch() member function. | |
| using | Endian = typename BaseImpl::Endian |
| Serialisation endian type. | |
| using | Field = BaseImpl::Field |
| Type of default base class for all the fields. | |
| using | Handler = TypeProvidedWithOption |
| Type of the message handler object. | |
| using | ImplOptions = details::MessageImplOptionsParser< TOptions... > |
| All the options provided to this class bundled into struct. | |
| using | InterfaceOptions = details::MessageInterfaceOptionsParser< TOptions... > |
| All the options bundled into struct. | |
| using | MsgIdParamType = typename BaseImpl::MsgIdParamType |
| Type used for message ID passed as parameter or returned from function. | |
| using | MsgIdType = typename BaseImpl::MsgIdType |
| Type used for message ID. | |
| using | MsgType = typename ImplOptions::MsgType |
| Type of the actual message provided via comms::option::def::MsgType. | |
| using | ReadIterator = TypeProvidedWithOption |
| Type of the iterator used for reading message contents from sequence of bytes stored somewhere. | |
| using | TransportFields = FieldsProvidedWithOption |
| std::tuple of extra fields from transport layers that may affect the way the message fields get serialized / deserialized. | |
| using | VersionType = typename BaseImpl::VersionType |
| Type used for version info. | |
| using | WriteIterator = TypeProvidedWithOption |
| Type of the iterator used for writing message contents into sequence of bytes stored somewhere. | |
Public Member Functions | |
| DispatchRetType | dispatch (Handler &handler) |
| Dispatch message to the handler for processing. | |
| bool | doFieldsVersionUpdate () |
| Update version information of all the fields. | |
| std::size_t | doLength () const |
| Default implementation of length calculation functionality. | |
| template<std::size_t TFromIdx> | |
| std::size_t | doLengthFrom () const |
| Default implementation of partial length calculation functionality. | |
| template<std::size_t TFromIdx, std::size_t TUntilIdx> | |
| std::size_t | doLengthFromUntil () const |
| Default implementation of partial length calculation functionality. | |
| template<std::size_t TUntilIdx> | |
| std::size_t | doLengthUntil () const |
| Default implementation of partial length calculation functionality. | |
| template<std::size_t TFromIdx, std::size_t TUntilIdx> | |
| std::size_t | doMaxLengthFromUntil () const |
| Compile time constant of maximal partial serialisation length. | |
| template<std::size_t TFromIdx, std::size_t TUntilIdx> | |
| std::size_t | doMinLengthFromUntil () const |
| Compile time constant of minimal partial serialisation length. | |
| template<typename TIter > | |
| ErrorStatus | doRead (TIter &iter, std::size_t size) |
| Default implementation of read functionality. | |
| bool | doRefresh () const |
| Default implementation of refreshing functionality. | |
| bool | doValid () const |
| Default implementation of validity check functionality. | |
| template<typename TIter > | |
| ErrorStatus | doWrite (TIter &iter, std::size_t size) const |
| Default implementation of write functionality. | |
| AllFields & | fields () |
| Get an access to the fields of the message. | |
| const AllFields & | fields () const |
| Get an access to the fields of the message. | |
| MsgIdParamType | getId () const |
| Retrieve ID of the message. | |
| std::size_t | length () const |
| Get number of bytes required to serialise this message. | |
| const char * | name () const |
| Get name of the message. | |
| ErrorStatus | read (ReadIterator &iter, std::size_t size) |
| Read message contents using provided iterator. | |
| bool | refresh () |
| Refresh to contents of the message. | |
| TransportFields & | transportFields () |
| Get access to extra transport fields. | |
| const TransportFields & | transportFields () const |
| Const version of transportFields. | |
| bool | valid () const |
| Check validity of message contents. | |
| VersionType & | version () |
| Access to version information. | |
| const VersionType & | version () const |
| Const access to version information. | |
| ErrorStatus | write (WriteIterator &iter, std::size_t size) const |
| Write message contents using provided iterator. | |
Static Public Member Functions | |
| static constexpr bool | areFieldsVersionDependent () |
| Compile time check of whether the message fields are version dependent. | |
| static constexpr MsgIdParamType | doGetId () |
| Default implementation of ID retrieval functionality. | |
| static constexpr std::size_t | doMaxLength () |
| Compile time constant of maximal serialisation length. | |
| template<std::size_t TFromIdx> | |
| static constexpr std::size_t | doMaxLengthFrom () |
| Compile time constant of maximal partial serialisation length. | |
| template<std::size_t TUntilIdx> | |
| static constexpr std::size_t | doMaxLengthUntil () |
| Compile time constant of maximal partial serialisation length. | |
| static constexpr std::size_t | doMinLength () |
| Compile time constant of minimal serialisation length. | |
| template<std::size_t TFromIdx> | |
| static constexpr std::size_t | doMinLengthFrom () |
| Compile time constant of minimal partial serialisation length. | |
| template<std::size_t TUntilIdx> | |
| static constexpr std::size_t | doMinLengthUntil () |
| Compile time constant of minimal partial serialisation length. | |
| static constexpr bool | hasCustomName () |
| Compile time inquiry of whether comms::MessageBase has notified about custom name retrieval function in the derived class via comms::option::def::HasName. | |
| static constexpr bool | hasCustomRefresh () |
| Compile time inquiry of whether comms::MessageBase has notified about custom refresh functionality in the derived class via comms::option::def::HasCustomRefresh. | |
| static constexpr bool | hasDispatch () |
| Compile type inquiry whether message interface class defines dispatch() and dispatchImpl() member functions as well as Handler and DispatchRetType types. | |
| static constexpr bool | hasEndian () |
| Compile type inquiry whether message interface class defines Endian and Field types. | |
| static constexpr bool | hasFailOnInvalid () |
| Compile time inquiry of whether fail on invalid has been requested comms::option::def::FailOnInvalid option. | |
| static constexpr bool | hasFields () |
| Compile type inquiry whether fields have been provided via comms::option::def::FieldsImpl. | |
| static constexpr bool | hasGetId () |
| Compile type inquiry whether message interface class defines getId() and getIdImpl() member functions. | |
| static constexpr bool | hasLength () |
| Compile type inquiry whether message interface class defines length() and lengthImpl() member functions. | |
| static constexpr bool | hasMsgIdType () |
| Compile type inquiry whether message interface class defines MsgIdType and MsgIdParamType types. | |
| static constexpr bool | hasMsgType () |
| Compile time inquiry of whether the actual message type has been provided via comms::option::def::MsgType. | |
| static constexpr bool | hasName () |
| Compile type inquiry whether message interface class defines name() and nameImpl() member functions. | |
| static constexpr bool | hasPolymorphicDispatch () |
| Compile time inquiry of whether polymoriphic dispatch has been requested via interface options and hasn't been inhibited by the comms::option::app::NoDispatchImpl. | |
| static constexpr bool | hasPolymorphicLength () |
| Compile time inquiry of whether polymoriphic length has been requested via interface options and hasn't been inhibited by the comms::option::app::NoLengthImpl. | |
| static constexpr bool | hasPolymorphicRead () |
| Compile time inquiry of whether polymoriphic read has been requested via interface options and hasn't been inhibited by the comms::option::app::NoReadImpl. | |
| static constexpr bool | hasPolymorphicValid () |
| Compile time inquiry of whether polymoriphic validity check has been requested via interface options and hasn't been inhibited by the comms::option::app::NoValidImpl. | |
| static constexpr bool | hasPolymorphicWrite () |
| Compile time inquiry of whether polymoriphic write has been requested via interface options and hasn't been inhibited by the comms::option::app::NoWriteImpl. | |
| static constexpr bool | hasRead () |
| Compile type inquiry whether message interface class defines read() and readImpl() member functions as well as ReadIterator type. | |
| static constexpr bool | hasRefresh () |
| Compile type inquiry whether message interface class defines refresh() and refreshImpl() member functions. | |
| static constexpr bool | hasStaticMsgId () |
| Compile type inquiry whether static numeric id has been provided via comms::option::def::StaticNumIdImpl. | |
| static constexpr bool | hasTransportFields () |
| Compile type inquiry whether message interface class defines transportFields() member functions as well as TransportFields type. | |
| static constexpr bool | hasValid () |
| Compile type inquiry whether message interface class defines valid() and validImpl() member functions. | |
| static constexpr bool | hasVersionInTransportFields () |
| Compile type inquiry whether there is version information inside transport fields. | |
| static constexpr bool | hasWrite () |
| Compile type inquiry whether message interface class defines write() and writeImpl() member functions as well as WriteIterator type. | |
| static constexpr std::intmax_t | staticMsgId () |
| Compile time retrieval of the message id provided via comms::option::def::StaticNumIdImpl. | |
| static constexpr std::size_t | versionIdxInTransportFields () |
| Compile type inquiry of version field index in transport field. | |
Protected Member Functions | |
| virtual DispatchRetType | dispatchImpl (Handler &handler) override |
| Implementation of dispatch functionality. | |
| template<std::size_t TIdx, typename TIter > | |
| ErrorStatus | doReadFrom (TIter &iter, std::size_t len) |
| Helper function that allows to read only limited number of fields. | |
| template<std::size_t TIdx, typename TIter > | |
| ErrorStatus | doReadFromAndUpdateLen (TIter &iter, std::size_t &len) |
| Same as doReadFrom(), but modifies length parameter. | |
| template<std::size_t TFromIdx, std::size_t TUntilIdx, typename TIter > | |
| ErrorStatus | doReadFromUntil (TIter &iter, std::size_t len) |
| Helper function that allows to read only limited number of fields. | |
| template<std::size_t TFromIdx, std::size_t TUntilIdx, typename TIter > | |
| ErrorStatus | doReadFromUntilAndUpdateLen (TIter &iter, std::size_t &len) |
| Same as doReadFromUntil(), but modifies length parameter. | |
| template<std::size_t TIdx, typename TIter > | |
| void | doReadNoStatusFrom (TIter &iter) |
| Helper function that allows to read only limited number of fields. | |
| template<std::size_t TFromIdx, std::size_t TUntilIdx, typename TIter > | |
| void | doReadNoStatusFromUntil (TIter &iter) |
| Helper function that allows to read only limited number of fields. | |
| template<std::size_t TIdx, typename TIter > | |
| void | doReadNoStatusUntil (TIter &iter) |
| Helper function that allows to read only limited number of fields. | |
| template<std::size_t TIdx, typename TIter > | |
| ErrorStatus | doReadUntil (TIter &iter, std::size_t &len) |
| Helper function that allows to read only limited number of fields. | |
| template<std::size_t TIdx, typename TIter > | |
| ErrorStatus | doReadUntilAndUpdateLen (TIter &iter, std::size_t &len) |
| Same as doReadUntil(), but updating length parameter. | |
| template<std::size_t TIdx, typename TIter > | |
| ErrorStatus | doWriteFrom (TIter &iter, std::size_t len) const |
| Helper function that allows to write only limited number of fields. | |
| template<std::size_t TIdx, typename TIter > | |
| ErrorStatus | doWriteFromAndUpdateLen (TIter &iter, std::size_t &len) const |
| Same as doWriteFrom(), but modifies length parameter. | |
| template<std::size_t TFromIdx, std::size_t TUntilIdx, typename TIter > | |
| ErrorStatus | doWriteFromUntil (TIter &iter, std::size_t len) const |
| Helper function that allows to write only limited number of fields. | |
| template<std::size_t TFromIdx, std::size_t TUntilIdx, typename TIter > | |
| ErrorStatus | doWriteFromUntilAndUpdateLen (TIter &iter, std::size_t &len) const |
| Same as doWriteNoStatusFrom(), but updates length information. | |
| template<std::size_t TIdx, typename TIter > | |
| void | doWriteNoStatusFrom (TIter &iter) const |
| Helper function that allows to write only limited number of fields. | |
| template<std::size_t TFromIdx, std::size_t TUntilIdx, typename TIter > | |
| void | doWriteNoStatusFromUntil (TIter &iter) const |
| Helper function that allows to write only limited number of fields. | |
| template<std::size_t TIdx, typename TIter > | |
| void | doWriteNoStatusUntil (TIter &iter) const |
| Helper function that allows to write only limited number of fields. | |
| template<std::size_t TIdx, typename TIter > | |
| ErrorStatus | doWriteUntil (TIter &iter, std::size_t len) const |
| Helper function that allows to write only limited number of fields. | |
| template<std::size_t TIdx, typename TIter > | |
| ErrorStatus | doWriteUntilAndUpdateLen (TIter &iter, std::size_t &len) const |
| Same as doWriteUntil(), but modifies length parameter. | |
| virtual MsgIdParamType | getIdImpl () const override |
| Implementation of ID retrieval functionality. | |
| virtual std::size_t | lengthImpl () const override |
| Implementation of polymorphic length calculation functionality. | |
| virtual const char * | nameImpl () const override |
| Implementation of polymorphic name retrieval functionality. | |
| virtual ErrorStatus | readImpl (ReadIterator &iter, std::size_t size) override |
| Implementation of polymorphic read functionality. | |
| virtual bool | refreshImpl () override |
| Implementation of polymorphic refresh functionality. | |
| virtual bool | validImpl () const override |
| Implementation of polymorphic validity check functionality. | |
| virtual ErrorStatus | writeImpl (WriteIterator &iter, std::size_t size) const override |
| Implementation of polymorphic write functionality. | |
Static Protected Member Functions | |
| template<typename T , typename TIter > | |
| static T | readData (TIter &iter) |
| Read data from input area. | |
| template<typename T , std::size_t TSize, typename TIter > | |
| static T | readData (TIter &iter) |
| Read partial data from input area. | |
| template<typename T , typename TIter > | |
| static void | writeData (T value, TIter &iter) |
| Write data into the output area. | |
| template<std::size_t TSize, typename T , typename TIter > | |
| static void | writeData (T value, TIter &iter) |
| Write partial data into the output area. | |
Related Symbols | |
(Note that these are not member symbols.) | |
| #define | COMMS_MSG_FIELD_ALIAS(f_, ...) |
| Generate convinience alias types and access member functions for other member fields. | |
| #define | COMMS_MSG_FIELD_ALIAS_ACCESS(f_, ...) COMMS_DO_ALIAS(field_, f_, __VA_ARGS__) |
| Generate convinience alias access member functions for other member fields. | |
| #define | COMMS_MSG_FIELDS_ACCESS(...) |
| Add convenience access enum and functions to message fields. | |
| #define | COMMS_MSG_FIELDS_NAMES(...) |
| Provide names for message fields. | |
| #define | COMMS_MSG_TRANSPORT_FIELD_ALIAS(f_, ...) |
| Generate convinience alias access member functions for extra member transport fields. | |
| #define | COMMS_MSG_TRANSPORT_FIELD_ALIAS_ACCESS(f_, ...) COMMS_EXPAND(COMMS_DO_ALIAS(transportField_, f_, __VA_ARGS__)) |
| Generate convinience alias access member functions for extra member transport fields. | |
| #define | COMMS_MSG_TRANSPORT_FIELDS_ACCESS(...) |
| Add convenience access enum and functions to extra transport fields. | |
| #define | COMMS_MSG_TRANSPORT_FIELDS_NAMES(...) |
| Provide names for extra transport fields. | |
| template<typename TMessage1 , typename TMessage2 , typename... TOptions> | |
| bool | operator!= (const MessageBase< TMessage1, TOptions... > &msg1, const MessageBase< TMessage2, TOptions... > &msg2) noexcept |
| Message object inequality comparison operator. | |
| template<typename TMessage1 , typename TMessage2 , typename... TOptions> | |
| bool | operator== (const MessageBase< TMessage1, TOptions... > &msg1, const MessageBase< TMessage2, TOptions... > &msg2) noexcept |
| Message object equality comparison operator. | |
Member Typedef Documentation
◆ AllFields
| using comms::MessageBase< TMessage, TOptions >::AllFields = FieldsProvidedWithOption |
All field classes provided with comms::option::def::FieldsImpl option.
The type is not defined if comms::option::def::FieldsImpl option wasn't provided to comms::MessageBase.
◆ DispatchRetType
|
inherited |
Return type of the dispatch() member function.
Equal to Handler::RetType if such exists, void otherwise.
◆ Endian
|
inherited |
Serialisation endian type.
The type exists only if comms::option::def::BigEndian or comms::option::def::LittleEndian options were used to specify it.
- See also
- hasEndian()
◆ Field
|
inherited |
Type of default base class for all the fields.
Requires definition of the Endian type, i.e. the type exist only if comms::option::def::BigEndian or comms::option::def::LittleEndian options were used.
◆ Handler
|
inherited |
Type of the message handler object.
The type exists only if comms::option::app::Handler option was provided to comms::Message to specify one.
◆ ImplOptions
| using comms::MessageBase< TMessage, TOptions >::ImplOptions = details::MessageImplOptionsParser<TOptions...> |
All the options provided to this class bundled into struct.
For internal use only
◆ InterfaceOptions
|
inherited |
All the options bundled into struct.
For internal use only.
◆ MsgIdParamType
|
inherited |
Type used for message ID passed as parameter or returned from function.
It is equal to MsgIdType for numeric types and becomes "const-reference-to" MsgIdType for more complex types. The type exists only if MsgIdType exists, i.e. the comms::option::def::MsgIdType option was used.
◆ MsgIdType
|
inherited |
Type used for message ID.
The type exists only if comms::option::def::MsgIdType option was provided to comms::Message to specify it.
- See also
- hasMsgIdType()
◆ MsgType
| using comms::MessageBase< TMessage, TOptions >::MsgType = typename ImplOptions::MsgType |
Type of the actual message provided via comms::option::def::MsgType.
If comms::option::def::MsgType hasn't been used equals to void.
◆ ReadIterator
|
inherited |
Type of the iterator used for reading message contents from sequence of bytes stored somewhere.
The type exists only if comms::option::app::ReadIterator option was provided to comms::Message to specify one.
- See also
- hasRead()
◆ TransportFields
|
inherited |
std::tuple of extra fields from transport layers that may affect the way the message fields get serialized / deserialized.
The type exists only if comms::option::def::ExtraTransportFields option has been provided to comms::Message class to specify them.
- See also
- hasTransportFields()
◆ VersionType
|
inherited |
Type used for version info.
The type exists only if comms::option::def::VersionInExtraTransportFields option has been provided.
◆ WriteIterator
|
inherited |
Type of the iterator used for writing message contents into sequence of bytes stored somewhere.
The type exists only if comms::option::app::WriteIterator option was provided to comms::Message to specify one.
- See also
- hasWrite()
Member Function Documentation
◆ areFieldsVersionDependent()
|
staticconstexpr |
Compile time check of whether the message fields are version dependent.
The function doesn't exist if comms::option::def::FieldsImpl option wasn't provided to comms::MessageBase.
- Returns
- true if at least one of the fields is version dependent.
◆ dispatch()
|
inherited |
Dispatch message to the handler for processing.
The function exists only if comms::option::app::Handler option was provided to comms::Message to specify type of the handler. The function invokes virtual dispatchImpl() function.
- Parameters
-
handler Handler object to dispatch message to.
◆ dispatchImpl()
|
overrideprotectedvirtual |
Implementation of dispatch functionality.
This function exists only if the following conditions are true:
- comms::option::app::Handler option option was provided to comms::Message.
- comms::option::def::MsgType option was used to specify actual type of the inheriting message class.
- comms::option::app::NoDispatchImpl option was NOT used.
In order to properly implement the dispatch functionality this class imposes several requirements. First of all, the custom message class must provide its own type as an argument to comms::option::def::MsgType option:
Second, The Handler type (inherited from comms::Message) must implement "handle()" member function for every message type (specified as Message1, Message2, ...) it is supposed to handle:
The "handle()" functions may be virtual. If the handler is capable of handling only limited number of messages, there is a need to provide additional "handle()" member function to implement default handling functionality (usually ignore the message by doing nothing) for all other messages that weren't handled explicitly.
Where "MessageBase" is a common base class for all the possible messages.
Once the requirements above are properly implemented, the implementation of this message is very simple:
The code above forces a compiler to choose appropriate handle() function in the Handler class, based on the actual type of the message. If such function is not found, the compiler will choose to call the one that covers all possible messages "void handle(MessageBase& msg)".
- Parameters
-
handler Reference to handler object.
Reimplemented from comms::Message< TOptions >.
◆ doFieldsVersionUpdate()
| bool comms::MessageBase< TMessage, TOptions >::doFieldsVersionUpdate | ( | ) |
Update version information of all the fields.
This function exists only if comms::option::def::FieldsImpl or comms::option::def::ZeroFieldsImpl option was provided to comms::MessageBase and comms::option::def::VersionInExtraTransportFields was provided to the message interface class (comms::Message).
This function will invoke such setVersion() member function for every field object listed with comms::option::def::FieldsImpl option and will return true if at least one of the invoked functions returned true (similar to doRefresh()).
- Returns
- true when at least one of the fields has been updated.
◆ doGetId()
|
staticconstexpr |
Default implementation of ID retrieval functionality.
This function exists only if comms::option::def::StaticNumIdImpl option was provided to comms::MessageBase.
- Returns
- Numeric ID of the message.
◆ doLength()
| std::size_t comms::MessageBase< TMessage, TOptions >::doLength | ( | ) | const |
Default implementation of length calculation functionality.
This function exists only if comms::option::def::FieldsImpl or comms::option::def::ZeroFieldsImpl option was provided to comms::MessageBase. To make this function works, every field class must provide "length()" function with following signature:
This function will invoke such "length()" member function for every field object listed with comms::option::def::FieldsImpl option. The final result is a summary of the "length" values of all the fields.
- Returns
- Serialisation length of the message.
◆ doLengthFrom()
| std::size_t comms::MessageBase< TMessage, TOptions >::doLengthFrom | ( | ) | const |
Default implementation of partial length calculation functionality.
Similar to length() member function but starts the calculation at the the field specified using TFromIdx template parameter.
- Template Parameters
-
TFromIdx Index of the field, from which length calculation will start
- Returns
- Calculated serialisation length
- Precondition
- TFromIdx < std::tuple_size<AllFields>::value
◆ doLengthFromUntil()
| std::size_t comms::MessageBase< TMessage, TOptions >::doLengthFromUntil | ( | ) | const |
Default implementation of partial length calculation functionality.
Similar to length() member function but starts the calculation at the the field specified using TFromIdx template parameter, and stops the calculation at the the field specified using TUntilIdx template parameter.
- Template Parameters
-
TFromIdx Index of the field, from which length calculation will start TUntilIdx Index of the field, at which the calculation will stop. The length of the filed with index TUntilIdx will NOT be taken into account.
- Returns
- Calculated serialisation length
- Precondition
- TFromIdx < std::tuple_size<AllFields>::value
- TUntilIdx <= std::tuple_size<AllFields>::value
- TFromIdx < TUntilIdx
◆ doLengthUntil()
| std::size_t comms::MessageBase< TMessage, TOptions >::doLengthUntil | ( | ) | const |
Default implementation of partial length calculation functionality.
Similar to length() member function but stops the calculation at the the field specified using TUntilIdx template parameter.
- Template Parameters
-
TUntilIdx Index of the field, at which the calculation will stop. The length of the filed with index TUntilIdx will NOT be taken into account.
- Returns
- Calculated serialisation length
- Precondition
- TUntilIdx <= std::tuple_size<AllFields>::value
◆ doMaxLength()
|
staticconstexpr |
Compile time constant of maximal serialisation length.
This function exists only if comms::option::def::FieldsImpl or comms::option::def::ZeroFieldsImpl option was provided to comms::MessageBase. To make this function works, every field class must provide "maxLength()" function with following signature:
- Returns
- Minimal serialisation length of the message.
◆ doMaxLengthFrom()
|
staticconstexpr |
Compile time constant of maximal partial serialisation length.
Similar to doMaxLength() member function but starts the calculation at the the field specified using TFromIdx template parameter.
- Template Parameters
-
TFromIdx Index of the field, from which length calculation will start
- Returns
- Calculated minimal serialisation length
- Precondition
- TFromIdx < std::tuple_size<AllFields>::value
◆ doMaxLengthFromUntil()
| std::size_t comms::MessageBase< TMessage, TOptions >::doMaxLengthFromUntil | ( | ) | const |
Compile time constant of maximal partial serialisation length.
Similar to doMaxLength() member function but starts the calculation at the the field specified using TFromIdx template parameter, and stops the calculation at the the field specified using TUntilIdx template parameter.
- Template Parameters
-
TFromIdx Index of the field, from which length calculation will start TUntilIdx Index of the field, at which the calculation will stop. The length of the filed with index TUntilIdx will NOT be taken into account.
- Returns
- Calculated minimal serialisation length
- Precondition
- TFromIdx < std::tuple_size<AllFields>::value
- TUntilIdx <= std::tuple_size<AllFields>::value
- TFromIdx < TUntilIdx
◆ doMaxLengthUntil()
|
staticconstexpr |
Compile time constant of maximal partial serialisation length.
Similar to doMaxLength() member function but stops the calculation at the the field specified using TUntilIdx template parameter.
- Template Parameters
-
TUntilIdx Index of the field, at which the calculation will stop. The length of the filed with index TUntilIdx will NOT be taken into account.
- Returns
- Calculated minimal serialisation length
- Precondition
- TUntilIdx <= std::tuple_size<AllFields>::value
◆ doMinLength()
|
staticconstexpr |
Compile time constant of minimal serialisation length.
This function exists only if comms::option::def::FieldsImpl or comms::option::def::ZeroFieldsImpl option was provided to comms::MessageBase. To make this function works, every field class must provide "minLength()" function with following signature:
- Returns
- Minimal serialisation length of the message.
◆ doMinLengthFrom()
|
staticconstexpr |
Compile time constant of minimal partial serialisation length.
Similar to doMinLength() member function but starts the calculation at the the field specified using TFromIdx template parameter.
- Template Parameters
-
TFromIdx Index of the field, from which length calculation will start
- Returns
- Calculated minimal serialisation length
- Precondition
- TFromIdx < std::tuple_size<AllFields>::value
◆ doMinLengthFromUntil()
| std::size_t comms::MessageBase< TMessage, TOptions >::doMinLengthFromUntil | ( | ) | const |
Compile time constant of minimal partial serialisation length.
Similar to doMinLength() member function but starts the calculation at the the field specified using TFromIdx template parameter, and stops the calculation at the the field specified using TUntilIdx template parameter.
- Template Parameters
-
TFromIdx Index of the field, from which length calculation will start TUntilIdx Index of the field, at which the calculation will stop. The length of the filed with index TUntilIdx will NOT be taken into account.
- Returns
- Calculated minimal serialisation length
- Precondition
- TFromIdx < std::tuple_size<AllFields>::value
- TUntilIdx <= std::tuple_size<AllFields>::value
- TFromIdx < TUntilIdx
◆ doMinLengthUntil()
|
staticconstexpr |
Compile time constant of minimal partial serialisation length.
Similar to doMinLength() member function but stops the calculation at the the field specified using TUntilIdx template parameter.
- Template Parameters
-
TUntilIdx Index of the field, at which the calculation will stop. The length of the filed with index TUntilIdx will NOT be taken into account.
- Returns
- Calculated minimal serialisation length
- Precondition
- TUntilIdx <= std::tuple_size<AllFields>::value
◆ doRead()
| ErrorStatus comms::MessageBase< TMessage, TOptions >::doRead | ( | TIter & | iter, |
| std::size_t | size | ||
| ) |
Default implementation of read functionality.
This function exists only if comms::option::def::FieldsImpl option was provided to comms::MessageBase.
To make this function works, every field class must provide "read" function with following signature:
This function will invoke such "read()" member function for every field object listed with comms::option::def::FieldsImpl option. If any field doesn't report ErrorStatus::Success, then read operation stops, i.e. the provided iterator is not advanced any more.
- Template Parameters
-
TIter Type of the iterator used for reading.
- Parameters
-
[in,out] iter Iterator used for reading the data. [in] size Maximum number of bytes that can be read.
- Returns
- Status of the operation.
◆ doReadFrom()
|
protected |
Helper function that allows to read only limited number of fields.
Sometimes the default implementation of doRead() is incorrect. For example, some bit in specific field specifies whether other field exists or must be skipped. In this case the derived class must implement different read functionality. To help in such task doReadUntil() function allows to read fields up to a specified one, while this function provides an ability to resume reading from some other field in the middle. The overriding doRead() function in the custom message definition class may use this function for such task. This function exists only if comms::option::def::FieldsImpl or comms::option::def::ZeroFieldsImpl option was provided to comms::MessageBase. The requirements from field classes is the same as explained in doRead() documentation.
- Template Parameters
-
TIdx Zero based index of the field to read from. The function reads all the fields between the one indexed TIdx (included) and the last one (also included). TIter Type of the iterator used for reading.
- Parameters
-
[in,out] iter Iterator used for reading the data. [in] len Maximum number of bytes that can be read.
- Returns
- Status of the operation.
- Precondition
- TIdx < std::tuple_size<AllFields>::value
◆ doReadFromAndUpdateLen()
|
protected |
Same as doReadFrom(), but modifies length parameter.
- Parameters
-
[in,out] iter Iterator used for reading the data. [in,out] len Maximum number of bytes that can be read.
◆ doReadFromUntil()
|
protected |
Helper function that allows to read only limited number of fields.
Sometimes the default implementation of doRead() is incorrect. For example, some bit in specific field specifies whether other fields exist or must be skipped. In this case the derived class must implement different read functionality. In similar way to doReadFrom() and doReadUntil() this function provides an ability to read any number of fields. This function exists only if comms::option::def::FieldsImpl or comms::option::def::ZeroFieldsImpl option was provided to comms::MessageBase. The requirements from field classes is the same as explained in doRead() documentation.
- Template Parameters
-
TFromIdx Zero based index of the field to read from. TUntilIdx Zero based index of the field to read until (not included). TIter Type of the iterator used for reading.
- Parameters
-
[in,out] iter Iterator used for reading the data. [in] len Maximum number of bytes that can be read.
- Returns
- Status of the operation.
- Precondition
- TFromIdx < std::tuple_size<AllFields>::value
- TUntilIdx <= std::tuple_size<AllFields>::value
- TFromIdx < TUntilIdx
◆ doReadFromUntilAndUpdateLen()
|
protected |
Same as doReadFromUntil(), but modifies length parameter.
- Parameters
-
[in,out] iter Iterator used for reading the data. [in,out] len Maximum number of bytes that can be read.
◆ doReadNoStatusFrom()
|
protected |
Helper function that allows to read only limited number of fields.
Similar to doReadFrom(), but doesn't check for errors and doesn't report status. This function can be used instead of doReadFrom() when correction of the read operation was ensured by other means prior to its invocation.
- Template Parameters
-
TIdx Zero based index of the field to read from. The function reads all the fields between the one indexed TIdx (included) and the last one (also included). TIter Type of the iterator used for reading.
- Parameters
-
[in,out] iter Iterator used for reading the data.
- Precondition
- TIdx < std::tuple_size<AllFields>::value
◆ doReadNoStatusFromUntil()
|
protected |
Helper function that allows to read only limited number of fields.
Similar to doReadFromUntil(), but doesn't check for errors and doesn't report status. This function can be used instead of doReadFromUntil() when correction of the read operation was ensured by other means prior to its invocation.
- Template Parameters
-
TFromIdx Zero based index of the field to read from. TUntilIdx Zero based index of the field to read until (not included). TIter Type of the iterator used for reading.
- Parameters
-
[in,out] iter Iterator used for reading the data.
- Precondition
- TFromIdx < std::tuple_size<AllFields>::value
- TUntilIdx <= std::tuple_size<AllFields>::value
- TFromIdx < TUntilIdx
◆ doReadNoStatusUntil()
|
protected |
Helper function that allows to read only limited number of fields.
Similar to doReadUntil(), but doesn't check for errors and doesn't report status. This function can be used instead of doReadUntil() when correction of the read operation was ensured by other means prior to its invocation.
- Template Parameters
-
TIdx Zero based index of the field to read until. The function returns when field with index "TIdx - 1" (if such exists) has been read, while field with index "TIdx" still hasn't. TIter Type of the iterator used for reading.
- Parameters
-
[in,out] iter Iterator used for reading the data.
- Precondition
- TIdx <= std::tuple_size<AllFields>::value
◆ doReadUntil()
|
protected |
Helper function that allows to read only limited number of fields.
Sometimes the default implementation of doRead() is incorrect. For example, some bit in specific field specifies whether other field exists or must be skipped. In this case the derived class must implement different read functionality. To help in such task this function provides an ability to read all the fields up to (not including) requested field. The overriding doRead() function in the custom message definition class may use this function for such task. This function exists only if comms::option::def::FieldsImpl or comms::option::def::ZeroFieldsImpl option was provided to comms::MessageBase. The requirements from field classes is the same as explained in doRead() documentation.
- Template Parameters
-
TIdx Zero based index of the field to read until. The function returns when field with index "TIdx - 1" (if such exists) has been read, while field with index "TIdx" still hasn't. TIter Type of the iterator used for reading.
- Parameters
-
[in,out] iter Iterator used for reading the data. [in] len Maximum number of bytes that can be read.
- Returns
- Status of the operation.
- Precondition
- TIdx <= std::tuple_size<AllFields>::value
◆ doReadUntilAndUpdateLen()
|
protected |
Same as doReadUntil(), but updating length parameter.
- Parameters
-
[in,out] iter Iterator used for reading the data. [in,out] len Maximum number of bytes that can be read.
◆ doRefresh()
| bool comms::MessageBase< TMessage, TOptions >::doRefresh | ( | ) | const |
Default implementation of refreshing functionality.
This function exists only if comms::option::def::FieldsImpl or comms::option::def::ZeroFieldsImpl option was provided to comms::MessageBase. To make this function works, every field class must provide "refresh()" function with following signature:
This function will invoke such "refresh()" member function for every field object listed with comms::option::def::FieldsImpl option and will return true if at least one of the invoked functions returned true.
- Returns
- true when at least one of the fields has been updated.
◆ doValid()
| bool comms::MessageBase< TMessage, TOptions >::doValid | ( | ) | const |
Default implementation of validity check functionality.
This function exists only if comms::option::def::FieldsImpl or comms::option::def::ZeroFieldsImpl option was provided to comms::MessageBase. To make this function works, every field class must provide "valid()" function with following signature:
This function will invoke such "valid()" member function for every field object listed with comms::option::def::FieldsImpl option.
- Returns
- true when all fields are valid.
◆ doWrite()
| ErrorStatus comms::MessageBase< TMessage, TOptions >::doWrite | ( | TIter & | iter, |
| std::size_t | size | ||
| ) | const |
Default implementation of write functionality.
This function exists only if comms::option::def::FieldsImpl or comms::option::def::ZeroFieldsImpl option was provided to comms::MessageBase.
To make this function works, every field class must provide "write" function with following signature:
This function will invoke such "write()" member function for every field object listed with comms::option::def::FieldsImpl option. If any field doesn't report ErrorStatus::Success, then write operation stops, i.e. the provided iterator is not advanced any more.
- Template Parameters
-
TIter Type of the iterator used for writing.
- Parameters
-
[in,out] iter Iterator used for writing the data. [in] size Maximum number of bytes that can be written.
- Returns
- Status of the operation.
◆ doWriteFrom()
|
protected |
Helper function that allows to write only limited number of fields.
In a similar way to doReadFrom(), this function allows writing limited number of fields starting from the requested one until the end. This function exists only if comms::option::def::FieldsImpl or comms::option::def::ZeroFieldsImpl option was provided to comms::MessageBase. The requirements from field classes is the same as explained in doWrite() documentation.
- Template Parameters
-
TIdx Zero based index of the field to write from. TIter Type of iterator used for writing.
- Parameters
-
[in,out] iter Iterator used for writing the data. [in] len Maximum number of bytes that can be written.
- Returns
- Status of the operation.
- Precondition
- TIdx < std::tuple_size<AllFields>::value
◆ doWriteFromUntil()
|
protected |
Helper function that allows to write only limited number of fields.
In a similar way to doReadFromUntil(), this function allows writing limited number of fields between the requested indices. This function exists only if comms::option::def::FieldsImpl or comms::option::def::ZeroFieldsImpl option was provided to comms::MessageBase. The requirements from field classes is the same as explained in doWrite() documentation.
- Template Parameters
-
TFromIdx Zero based index of the field to write from. TUntilIdx Zero based index of the field to write until (not including). TIter Type of iterator used for writing.
- Parameters
-
[in,out] iter Iterator used for writing the data. [in] len Maximum number of bytes that can be written.
- Returns
- Status of the operation.
- Precondition
- TFromIdx < std::tuple_size<AllFields>::value
- TUntilIdx <= std::tuple_size<AllFields>::value
- TFromIdx < TUntilIdx
◆ doWriteNoStatusFrom()
|
protected |
Helper function that allows to write only limited number of fields.
Similar to doWriteFrom(), but doesn't check for errors and doesn't report status. This function can be used instead of doWriteFrom() when correction of the write operation was ensured by other means prior to its invocation.
- Template Parameters
-
TIdx Zero based index of the field to write from. TIter Type of the iterator used for writing.
- Parameters
-
[in,out] iter Iterator used for reading the data.
- Precondition
- TIdx < std::tuple_size<AllFields>::value
◆ doWriteNoStatusFromUntil()
|
protected |
Helper function that allows to write only limited number of fields.
Similar to doWriteFromUntil(), but doesn't check for errors and doesn't report status. This function can be used instead of doWriteFromUntil() when correction of the write operation was ensured by other means prior to its invocation.
- Template Parameters
-
TFromIdx Zero based index of the field to write from. TUntilIdx Zero based index of the field to write until (not including). TIter Type of iterator used for writing.
- Parameters
-
[in,out] iter Iterator used for reading the data.
- Precondition
- TFromIdx < std::tuple_size<AllFields>::value
- TUntilIdx <= std::tuple_size<AllFields>::value
- TFromIdx < TUntilIdx
◆ doWriteNoStatusUntil()
|
protected |
Helper function that allows to write only limited number of fields.
Similar to doWriteUntil(), but doesn't check for errors and doesn't report status. This function can be used instead of doWriteUntil() when correction of the write operation was ensured by other means prior to its invocation.
- Template Parameters
-
TIdx Zero based index of the field to write until. The function returns when field with index "TIdx - 1" (if such exists) has been written, while field with index "TIdx" still hasn't. TIter Type of the iterator used for writing.
- Parameters
-
[in,out] iter Iterator used for reading the data.
- Precondition
- TIdx <= std::tuple_size<AllFields>::value
◆ doWriteUntil()
|
protected |
Helper function that allows to write only limited number of fields.
In a similar way to doReadUntil(), this function allows writing limited number of fields starting from the first one. This function exists only if comms::option::def::FieldsImpl or comms::option::def::ZeroFieldsImpl option was provided to comms::MessageBase. The requirements from field classes is the same as explained in doWrite() documentation.
- Template Parameters
-
TIdx Zero based index of the field to write until. The function returns when field with index "TIdx - 1" (if such exists) has been written, while field with index "TIdx" still hasn't. TIter Type of iterator used for writing.
- Parameters
-
[in,out] iter Iterator used for writing the data. [in] len Maximum number of bytes that can be written.
- Returns
- Status of the operation.
- Precondition
- TIdx <= std::tuple_size<AllFields>::value
◆ fields() [1/2]
| AllFields & comms::MessageBase< TMessage, TOptions >::fields | ( | ) |
Get an access to the fields of the message.
The function doesn't exist if comms::option::def::FieldsImpl option wasn't provided to comms::MessageBase.
- Returns
- Reference to the fields of the message.
◆ fields() [2/2]
| const AllFields & comms::MessageBase< TMessage, TOptions >::fields | ( | ) | const |
Get an access to the fields of the message.
The function doesn't exist if comms::option::def::FieldsImpl option wasn't provided to comms::MessageBase.
- Returns
- Const reference to the fields of the message.
◆ getId()
|
inherited |
Retrieve ID of the message.
Invokes pure virtual getIdImpl(). This function exists only if comms::option::def::MsgIdType option was used to specify type of the ID value and comms::option::app::IdInfoInterface option are used.
- Returns
- ID of the message.
- See also
- hasGetId();
◆ getIdImpl()
|
overrideprotectedvirtual |
Implementation of ID retrieval functionality.
This function may exist only if ID retrieval is possible, i.e. the ID type has been privded to comms::Message using comms::option::def::MsgIdType option and the polymorphic ID retrieval functionality was requested (using comms::option::app::IdInfoInterface). In addition to the conditions listed earlier this function is provided if local doGetId() function was generated. If not, it may still be provided if the derived class is known (comms::option::def::MsgType option was used) and the comms::option::def::HasDoGetId option is used to declare the derived type having doGetId() member function defined.
- Returns
- ID value passed as template parameter to comms::option::def::StaticNumIdImpl option.
Implements comms::Message< TOptions >.
◆ length()
|
inherited |
Get number of bytes required to serialise this message.
The function exists only if comms::option::app::LengthInfoInterface option was provided to comms::Message. The function invokes virtual lengthImpl() function.
- Returns
- Number of bytes required to serialise this message.
- See also
- hasLength()
◆ lengthImpl()
|
overrideprotectedvirtual |
Implementation of polymorphic length calculation functionality.
This function exists if comms::option::app::LengthInfoInterface option was provided to comms::Message class when specifying interface, and comms::option::app::NoLengthImpl option was NOT used to inhibit the implementation.
If comms::option::def::MsgType option was used to specify the actual type of the message, and if it contains custom doLength() function, it will be invoked. Otherwise, the invocation of comms::MessageBase::doLength() will be chosen in case fields were specified using comms::option::def::FieldsImpl option.
- Returns
- Serialisation length of the message.
Reimplemented from comms::Message< TOptions >.
◆ name()
|
inherited |
Get name of the message.
The function exists only if comms::option::app::NameInterface option was provided to comms::Message. The function invokes virtual nameImpl() function.
- See also
- hasName()
◆ nameImpl()
|
overrideprotectedvirtual |
Implementation of polymorphic name retrieval functionality.
This function exists if comms::option::app::NameInterface option was provided to comms::Message class when specifying interface, and comms::option::def::HasName as well as comms::option::def::MsgType options ware used for this class. This function downcasts this pointer to actual message type and invokes doName() member function.
- Returns
- true in case fields were updated, false if nothing has changed.
Implements comms::Message< TOptions >.
◆ read()
|
inherited |
Read message contents using provided iterator.
The function exists only if comms::option::app::ReadIterator option was provided to comms::Message to specify type of the ReadIterator. The contents of the message are updated with bytes being read. The buffer is external and maintained by the caller. The provided iterator is advanced. The function invokes virtual readImpl() function.
- Parameters
-
[in,out] iter Iterator used for reading the data. [in] size Maximum number of bytes that can be read.
- Returns
- Status of the operation.
- See also
- hasRead()
◆ readData() [1/2]
|
staticprotectedinherited |
Read data from input area.
Use this function to read data from the input area using provided iterator. This function requires knowledge about serialisation endian. It exists only if endian type was specified using comms::option::def::BigEndian or comms::option::def::LittleEndian options to the class.
- Template Parameters
-
T Return type TIter Type of input iterator
- Parameters
-
[in,out] iter Input iterator.
- Returns
- The integral type value.
- Precondition
- TSize <= sizeof(T)
- The iterator must be valid and can be successfully dereferenced and incremented at least sizeof(T) times.
- Postcondition
- The iterator is advanced.
- Note
- Thread safety: Safe for distinct stream buffers, unsafe otherwise.
◆ readData() [2/2]
|
staticprotectedinherited |
Read partial data from input area.
Use this function to read partial data from the input area using provided iterator. This function requires knowledge about serialisation endian. It exists only if endian type was specified using comms::option::def::BigEndian or comms::option::def::LittleEndian options to the class.
- Template Parameters
-
T Return type TSize number of bytes to read TIter Type of input iterator
- Parameters
-
[in,out] iter Input iterator.
- Returns
- The integral type value.
- Precondition
- TSize <= sizeof(T)
- The iterator must be valid and can be successfully dereferenced and incremented at least TSize times.
- Postcondition
- The internal pointer of the stream buffer is advanced.
- Note
- Thread safety: Safe for distinct stream buffers, unsafe otherwise.
◆ readImpl()
|
overrideprotectedvirtual |
Implementation of polymorphic read functionality.
This function exists if comms::option::app::ReadIterator option was provided to comms::Message class when specifying interface, and comms::option::app::NoReadImpl option was NOT used to inhibit the implementation.
If comms::option::def::MsgType option was used to specify the actual type of the message, and if it contains custom doRead() function, it will be invoked. Otherwise, the invocation of comms::MessageBase::doRead() will be chosen in case fields were specified using comms::option::def::FieldsImpl option.
- Parameters
-
[in,out] iter Iterator used for reading the data. [in] size Maximum number of bytes that can be read.
- Returns
- Status of the operation.
Reimplemented from comms::Message< TOptions >.
◆ refresh()
|
inherited |
Refresh to contents of the message.
Many protocols define their messages in a way that the content of some fields may depend on the value of the other field(s). For example, providing in one field the information about number of elements in the list that will follow later. Another example is having bits in a bitmask field specifying whether other optional fields exist. In this case, directly modifying value of some fields may leave a message contents in an inconsistent state. Having refresh() member function allows the developer to bring the message into a consistent state prior to sending it over I/O link .
The function exists only if comms::option::app::RefreshInterface option was provided to comms::Message. The function invokes virtual refreshImpl() function.
- Returns
- true in case the contents of the message were modified, false if all the fields of the message remained unchanged.
◆ refreshImpl()
|
overrideprotectedvirtual |
Implementation of polymorphic refresh functionality.
This function exists if comms::option::app::RefreshInterface option was provided to comms::Message class when specifying interface, and comms::option::def::HasCustomRefresh option was used (either on on of the fields or when defining a message class) to to notify about existence of custom refresh functionality. If comms::option::def::MsgType option was used to specify the actual message class, the this pointer will be downcasted to it to invoke doRefresh() member function defined there. If such is not defined the default doRefresh() member function from this class will be used.
- Returns
- true in case fields were updated, false if nothing has changed.
Reimplemented from comms::Message< TOptions >.
◆ staticMsgId()
|
staticconstexpr |
Compile time retrieval of the message id provided via comms::option::def::StaticNumIdImpl.
If comms::option::def::StaticNumIdImpl hasn't been used, std::numeric_limits<std::intmax_t>::max() is returned.
◆ transportFields() [1/2]
|
inherited |
Get access to extra transport fields.
The function exists only if comms::option::def::ExtraTransportFields option has been provided to comms::Message class to specify them. Some protocols may use additional values in transport information, such as message version for example. Such values may influence the way message data is being serialized / deserialized. The provided extra transport fields are NOT serialised as part of message payload. Their values are expected to be set by transport layer(s) when such information is read. The transport layers are also responsible to take the updated information from the relevant field and write it when message contents being written.
- See also
- hasTransportFields()
◆ transportFields() [2/2]
|
inherited |
Const version of transportFields.
The function exists only if comms::option::def::ExtraTransportFields option has been provided to comms::Message class to specify them.
- See also
- hasTransportFields()
◆ valid()
|
inherited |
Check validity of message contents.
The function exists only if comms::option::app::ValidCheckInterface option was provided to comms::Message. The function invokes virtual validImpl() function.
- Returns
- true for valid contents, false otherwise.
- See also
- hasValid()
◆ validImpl()
|
overrideprotectedvirtual |
Implementation of polymorphic validity check functionality.
This function exists if comms::option::app::ValidCheckInterface option was provided to comms::Message class when specifying interface, and comms::option::app::NoValidImpl option was NOT used to inhibit the implementation.
If comms::option::def::MsgType option was used to specify the actual type of the message, and if it contains custom doValid() function, it will be invoked. Otherwise, the invocation of comms::MessageBase::doValid() will be chosen in case fields were specified using comms::option::def::FieldsImpl option.
Reimplemented from comms::Message< TOptions >.
◆ version() [1/2]
|
inherited |
Access to version information.
The function exists only if comms::option::def::VersionInExtraTransportFields option has been provided.
◆ version() [2/2]
|
inherited |
Const access to version information.
The function exists only if comms::option::def::VersionInExtraTransportFields option has been provided.
◆ versionIdxInTransportFields()
|
staticconstexprinherited |
Compile type inquiry of version field index in transport field.
If comms::option::def::VersionInExtraTransportFields option hasn't been used, the std::numeric_limits<std::size_t>::max() is returned.
◆ write()
|
inherited |
Write message contents using provided iterator.
The function exists only if comms::option::app::WriteIterator option was provided to comms::Message to specify type of the WriteIterator. The contents of the message are serialised into buffer. The buffer is external and is maintained by the caller. The provided iterator is advanced. The function invokes virtual writeImpl() function.
- Parameters
-
[in,out] iter Iterator used for writing the data. [in] size Maximum number of bytes that can be written.
- Returns
- Status of the operation.
- See also
- hasWrite()
◆ writeData() [1/2]
|
staticprotectedinherited |
Write data into the output area.
Use this function to write data to the output area using provided iterator. This function requires knowledge about serialisation endian. It exists only if endian type was specified using comms::option::def::BigEndian or comms::option::def::LittleEndian options to the class.
- Template Parameters
-
T Type of the value to write. Must be integral. Type of output iterator
- Parameters
-
[in] value Integral type value to be written. [in,out] iter Output iterator.
- Precondition
- The iterator must be valid and can be successfully dereferenced and incremented at least sizeof(T) times.
- Postcondition
- The iterator is advanced.
- Note
- Thread safety: Safe for distinct buffers, unsafe otherwise.
◆ writeData() [2/2]
|
staticprotectedinherited |
Write partial data into the output area.
Use this function to write partial data to the output area using provided iterator. This function requires knowledge about serialisation endian. It exists only if endian type was specified using comms::option::def::BigEndian or comms::option::def::LittleEndian options to the class.
- Template Parameters
-
TSize Length of the value in bytes known in compile time. T Type of the value to write. Must be integral. TIter Type of output iterator
- Parameters
-
[in] value Integral type value to be written. [in,out] iter Output iterator.
- Precondition
- TSize <= sizeof(T)
- The iterator must be valid and can be successfully dereferenced and incremented at least TSize times.
- Postcondition
- The iterator is advanced.
- Note
- Thread safety: Safe for distinct buffers, unsafe otherwise.
◆ writeImpl()
|
overrideprotectedvirtual |
Implementation of polymorphic write functionality.
This function exists if comms::option::app::WriteIterator option was provided to comms::Message class when specifying interface, and comms::option::app::NoWriteImpl option was NOT used to inhibit the implementation.
If comms::option::def::MsgType option was used to specify the actual type of the message, and if it contains custom doWrite() function, it will be invoked. Otherwise, the invocation of comms::MessageBase::doWrite() will be chosen in case fields were specified using comms::option::def::FieldsImpl option.
- Parameters
-
[in,out] iter Iterator used for writing the data. [in] size Maximum number of bytes that can be written.
- Returns
- Status of the operation.
Reimplemented from comms::Message< TOptions >.
Friends And Related Symbol Documentation
◆ COMMS_MSG_FIELD_ALIAS
|
related |
Generate convinience alias types and access member functions for other member fields.
The COMMS_MSG_FIELDS_NAMES() macro generates inner types and convenience access member functions for member fields. Sometimes the fields may get renamed or moved to be a member of other fields, like comms::field::Bundle or comms::field::Bitfield. In such case the compilation of the existing client code (that already uses published protocol definition) may fail. To avoid such scenarios and make the transition to newer versions of the protocol easier, the COMMS_MSG_FIELD_ALIAS() macro can be used to create alias to other fields. For example, let's assume that some message class was defined: like this.
In the future versions of the protocol "name3" was renamed to "newName3". To keep the existing code (that uses "name3" name) compiling it is possible to create an alias access function(s) with:
The usage of COMMS_MSG_FIELD_ALIAS() in the code above is equivalent to having the following functions as well as type defined:
Another example would be a replacing a comms::field::IntValue with comms::field::Bitfield in the future version of the protocol. It can happen when the developer decides to split the used storage into multiple values (because the range of the used/valid values allows so). In order to keep the old client code compiling, the access to the replaced field needs to be an alias to the first member of the comms::field::Bitfield. In this case the usage of COMMS_MSG_FIELD_ALIAS() will look like this:
The usage of COMMS_MSG_FIELD_ALIAS() in the code above is equivalent to having the following functions defined:
- Parameters
-
[in] f_ Alias field name. [in] ... List of fields' names.
- Precondition
- The macro COMMS_MSG_FIELDS_NAMES() needs to be used before COMMS_MSG_FIELD_ALIAS() to define convenience access functions.
- See also
- COMMS_MSG_FIELD_ALIAS_ACCESS()
- Note
- Defined in "comms/MessageBase.h"
◆ COMMS_MSG_FIELD_ALIAS_ACCESS
|
related |
Generate convinience alias access member functions for other member fields.
Similar to COMMS_MSG_FIELD_ALIAS() but requires usage of COMMS_MSG_FIELDS_ACCESS() instead of COMMS_MSG_FIELDS_NAMES() and does NOT create alias to the field type, only access functions.
- Parameters
-
[in] f_ Alias field name. [in] ... List of fields' names.
- Precondition
- The macro COMMS_MSG_FIELDS_ACCESS() needs to be used before COMMS_MSG_FIELD_ALIAS_ACCESS() to define convenience access functions.
- Note
- Defined in "comms/MessageBase.h"
- See also
- COMMS_MSG_FIELD_ALIAS()
◆ COMMS_MSG_FIELDS_ACCESS
|
related |
Add convenience access enum and functions to message fields.
Very similar to COMMS_MSG_FIELDS_NAMES(), but does NOT require definition of Base inner member type (for some compilers) and does NOT define inner Field_* types for used fields.
- Parameters
-
[in] ... List of fields' names.
- See also
- COMMS_MSG_FIELDS_NAMES()
- Note
- Defined in "comms/MessageBase.h"
◆ COMMS_MSG_FIELDS_NAMES
|
related |
Provide names for message fields.
The comms::MessageBase class provides access to its fields via comms::MessageBase::fields() member function(s). The fields are bundled into std::tuple and can be accessed using indices with std::get. For convenience, the fields should be named. The COMMS_MSG_FIELDS_NAMES() macro does exactly that.
As an example, let's assume that custom message uses 3 fields of any types:
NOTE that there is a required to have Base member type that specifies base class used. It is needed to be able to access comms::MessageBase::AllFields type definition.
The usage of the COMMS_MSG_FIELDS_NAMES() macro with the list of the field's names is equivalent to having the following definitions inside the message class
NOTE, that provided names name1, name2, and name3 have found their way to the following definitions:
- FieldIdx enum. The names are prefixed with FieldIdx_. The FieldIdx_nameOfValues value is automatically added at the end.
- Accessor functions prefixed with field_*
- Types of fields prefixed with Field_*
As the result, the fields can be accessed using FieldIdx enum
or using accessor functions:
- Parameters
-
[in] ... List of fields' names.
- Precondition
- Requires (re)definition of the message base class as inner Base member type.
- See also
- COMMS_MSG_FIELDS_ACCESS()
- Note
- Defined in "comms/MessageBase.h"
◆ COMMS_MSG_TRANSPORT_FIELD_ALIAS
|
related |
Generate convinience alias access member functions for extra member transport fields.
The COMMS_MSG_TRANSPORT_FIELDS_NAMES() macro generates alias type as well as convenience access member functions for extra transport fields. Sometimes the fields may get renamed or moved to be a member of other fields, like comms::field::Bundle or comms::field::Bitfield. In such case the compilation of the existing client code (that already uses published protocol definition) may fail. To avoid such scenarios and make the transition to newer versions of the protocol easier, the COMMS_MSG_TRANSPORT_FIELD_ALIAS() macro can be used to create alias to other fields. For example, let's assume that some common interface class was defined: like this.
In the future versions of the protocol "name3" was renamed to "newName3". To keep the existing code (that uses "name3" name) compiling it is possible to create an alias access function(s) with:
The usage of COMMS_MSG_TRANSPORT_FIELD_ALIAS() in the code above is equivalent to having the following type and functions defined:
Another example would be a replacing a comms::field::IntValue with comms::field::Bitfield in the future version of the protocol. It can happen when the developer decides to split the used storage into multiple values (because the range of the used/valid values allows so). In order to keep the old client code compiling, the access to the replaced field needs to be an alias to the first member of the comms::field::Bitfield. In this case the usage of COMMS_MSG_TRANSPORT_FIELD_ALIAS() will look like this:
The usage of COMMS_MSG_TRANSPORT_FIELD_ALIAS() in the code above is equivalent to having the following functions defined:
- Parameters
-
[in] f_ Alias field name. [in] ... List of fields' names.
- Precondition
- The macro COMMS_MSG_TRANSPORT_FIELDS_NAMES() needs to be used before COMMS_MSG_TRANSPORT_FIELD_ALIAS() to define convenience access functions.
- See also
- COMMS_MSG_TRANSPORT_FIELD_ALIAS_ACCESS_NOTEMPLATE()
- COMMS_MSG_TRANSPORT_FIELD_ALIAS_NOTEMPLATE()
- Note
- Defined in "comms/Message.h"
◆ COMMS_MSG_TRANSPORT_FIELD_ALIAS_ACCESS
|
related |
Generate convinience alias access member functions for extra member transport fields.
Similar to COMMS_MSG_TRANSPORT_FIELD_ALIAS() but requires usage of COMMS_MSG_TRANSPORT_FIELDS_ACCESS() instead of COMMS_MSG_TRANSPORT_FIELDS_NAMES() and does NOT create alias to the field type, only access functions.
- Parameters
-
[in] f_ Alias field name. [in] ... List of fields' names.
- Precondition
- The macro COMMS_MSG_TRANSPORT_FIELDS_ACCESS() needs to be used before COMMS_MSG_TRANSPORT_FIELD_ALIAS_ACCESS() to define convenience access functions.
- Note
- Defined in "comms/Message.h"
◆ COMMS_MSG_TRANSPORT_FIELDS_ACCESS
|
related |
Add convenience access enum and functions to extra transport fields.
Very similar to COMMS_MSG_TRANSPORT_FIELDS_NAMES(), but does NOT require definition of Base inner member type (for some compilers) and does NOT define inner TransportField_* types for used fields.
- Parameters
-
[in] ... List of fields' names.
- Note
- Defined in "comms/Message.h"
◆ COMMS_MSG_TRANSPORT_FIELDS_NAMES
|
related |
Provide names for extra transport fields.
The comms::Message class provides access to its extra transport fields via comms::MessageBase::transportFields() member function(s). The fields are bundled into std::tuple and can be accessed using indices with std::get. For convenience, the fields should be named. The COMMS_MSG_TRANSPORT_FIELDS_NAMES() macro does exactly that.
As an example, let's assume that custom message uses 3 fields of any types:
The usage of the COMMS_MSG_TRANSPORT_FIELDS_NAMES() macro with the list of the extra transport field's names is equivalent to having the following definitions inside the message class
NOTE, that provided names name1, name2, and name3 have found their way to the following definitions:
- TransportFieldIdx enum. The names are prefixed with TransportFieldIdx_. The TransportFieldIdx_nameOfValues value is automatically added at the end.
- Accessor functions prefixed with transportField_*
- Types of fields prefixed with TransportField_*
As the result, the fields can be accessed using TransportFieldIdx enum
or using accessor functions:
- Parameters
-
[in] ... List of fields' names.
- Precondition
- Requires (re)definition of the message base class as inner Base member type.
- Note
- Defined in "comms/Message.h"
◆ operator!=()
|
related |
Message object inequality comparison operator.
Messages are considered not equal if any their fields are considered inequal.
◆ operator==()
|
related |
Message object equality comparison operator.
Messages are considered equal if all their fields are considered equal
The documentation for this class was generated from the following file:
- include/comms/MessageBase.h
