Release v1.2

Author: arobenko

comms/doc/page_custom_id_layer.dox

@@ -0,0 +1,182 @@
+/// @page page_custom_id_layer Defining Custom Message ID Protocol Stack Layer
+/// @tableofcontents
+/// The @b COMMS library provides default @ref comms::protocol::MsgIdLayer protocol 
+/// stack layer to manage message ID information in the protocol framing. 
+/// However, it may be insufficient (or incorrect) for some particular use cases, such as
+/// using @b bitfield field to store both numeric message ID and some extra flags
+/// (like <a href="http://mqtt.org">MQTT</a> protocol does). 
+/// The @ref page_prot_stack_tutorial_new_layers section of the 
+/// @ref page_prot_stack_tutorial page explains how to define new (custom)
+/// protocol layer. 
+///
+/// @b NOTE, that @ref comms::protocol::MsgIdLayer class
+/// contains significant amount of compile time logic of choosing the best
+/// code based on provided options as well as available polymorphic interface
+/// messages being read and/or written. It is very impractical to try to 
+/// implement something similar from scratch or copy-paste the existing 
+/// definition and introduce required changes.
+/// 
+/// Since @b v1.2 COMMS library provides an ability to extend the existing
+/// definition of @ref comms::protocol::MsgIdLayer and customize some bits
+/// and pieces. Let's implement the mentioned example of sharing the same byte
+/// for numeric ID and some flags.
+///
+/// First of all let's define the @ref page_define_prot_interface, which
+/// holds the @b flags information as data member of every message object.
+/// @code
+/// namespace my_prot
+/// {
+///
+/// // Enum used for numeric message IDs
+/// enum MsgId
+/// {
+///     MsgId_Message1,
+///     MsgId_Message2,
+///     ...
+/// };
+///
+/// // Base class for all the fields defining serialization endian
+/// using FieldBase = comms::field::Field<comms::option::BigEndian>;
+///
+/// // Definition of the message flags
+/// class MessageFlags : public
+///     comms::field::BitmaskValue<
+///         FieldBase,
+///         comms::option::BitmaskReservedBits<0xf0>
+///     >
+/// {
+/// public:
+///     // Provides names and generates access functions for internal bits.
+///     COMMS_BITMASK_BITS_SEQ(bit0, bit1, bit2, bit3);
+/// };
+///
+/// // Definition of the extensible common message interface
+/// template <typename... TOptions>
+/// class Message : public
+///     comms::Message<
+///         TOptions...,
+///         comms::option::BigEndian,
+///         comms::option::MsgIdType<MsgId>,
+///         comms::option::ExtraTransportFields<std::tuple<MessageFlags> >
+///     >
+/// {
+/// public:
+///     //  Allow access to extra transport fields.
+///     COMMS_MSG_TRANSPORT_FIELDS_ACCESS(flags);
+/// };
+///
+/// } // namespace my_prot
+/// @endcode
+/// Just to refresh the reader's memory: the usage of @ref COMMS_MSG_TRANSPORT_FIELDS_ACCESS()
+/// macro for the interface definition will generate @b transportField_flags() 
+/// convenience member function to access the stored @b flags field, while 
+/// usage of @ref COMMS_BITMASK_BITS_SEQ() in the flags field definition will
+/// genereate @b getBitValue_X() and @b setBitValue_X() convenience member
+/// functions to get / set values of the bits (where X is one of the defined
+/// names: @b bit0, @b bit1, @b bit2, and @b bit3).
+///
+/// Now, let's define the @b bitfield field, that splits one byte in half to
+/// store numeric message ID (in lower 4 bits) as well as extra flags (in upper 4 bits)
+/// @code
+/// namespace my_prot
+/// {
+///
+/// class IdAndFlagsField : public
+///     comms::field::Bitfield<
+///         FieldBase,
+///         std::tuple<
+///             comms::field::EnumValue<FieldBase, MsgId, comms::option::FixedBitLength<4> >,
+///             comms::field::IntValue<FieldBase, std::uint8_t, comms::option::FixedBitLength<4> >
+///         >
+///     >
+/// {
+/// public:
+///     // Allow access to internal member fields.
+///     COMMS_FIELD_MEMBERS_ACCESS(id, flags);
+/// };
+/// 
+/// } // my_prot
+/// @endcode
+/// Again, just to refresh the reader's memory: the usage of @ref COMMS_FIELD_MEMBERS_ACCESS()
+/// macro for the bitfield definition will generate @b field_X() 
+/// convenience access member functions for the listed names.
+///
+/// Now it's time to actually extend the provided definition of 
+/// the @ref comms::protocol::MsgIdLayer and support usage of the defined
+/// earlier @b IdAndFlagsField field.
+/// @code
+/// namespace my_prot
+/// {
+/// 
+/// template <typename TMessage, typename TAllMessages, typename TNextLayer, typename... TOptions>
+/// class MsgIdAndFlagsLayer : public
+///     comms::protocol::MsgIdLayer<
+///         IdAndFlagsField,   // Used field that contains message ID
+///         TMessage,          // Common interface class
+///         TAllMessages,      // std::tuple of all the supported input messages
+///         TNextLayer,        // Next layer in the protocol stack
+///         TOptions...,       // Application specific extension options
+///         comms::option::ExtendingClass<MsgIdAndFlagsLayer<TMessage, TAllMessages, TNextLayer, TOptions...> >
+///                            // Make the comms::protocol::MsgIdLayer aware of it being extended
+///     >
+/// {
+///     // Repeat definition of the base class
+///     using Base = comms::protocol::MsgIdLayer<...>;
+///
+/// public:
+///     // Repeat types defined in the base class (not visible by default)
+///     using MsgIdType = typename Base::MsgIdType;
+///     using MsgIdParamType = typename Base::MsgIdParamType;
+///     using Field = typename Base::Field; // same as IdAndFlagsField
+///     
+///     // Retrieve message ID value from the given IdAndFlagsField field
+///     static MsgIdType getMsgIdFromField(const Field& field)
+///     {
+///         return field.field_id().value();
+///     }
+/// 
+///     // Set flags value for the message object before proceeding to the next layer read
+///     // The message object is passed by reference
+///     template <typename TMsg>
+///     static void beforeRead(const Field& field, TMsg& msg)
+///     {
+///         msg.transportField_flags().value() = field.field_flags().value();
+///     }
+/// 
+///     // Assemble the field's value before its write given message ID as well
+///     // as message object itself.
+///     template <typename TMsg>
+///     static void prepareFieldForWrite(MsgIdParamType id, const TMsg& msg, Field& field)
+///     {
+///         field.field_id().value() = id;
+///         field.field_flags().value() = msg.transportField_flags().value();
+///     }
+/// };
+///
+/// } // namespace my_prot
+/// @endcode
+/// The @ref comms::protocol::MsgIdLayer doesn't have any virtual functions and
+/// as the result not able to provide any polymorphic behavior. In order to be
+/// able to extend its default functionality there is a need to use 
+/// <a href="https://en.wikipedia.org/wiki/Curiously_recurring_template_pattern">Curiously Recurring Template Pattern</a>.
+/// It is done by passing @ref comms::option::ExtendingClass extension option with
+/// the type of the layer class being defined to the @ref comms::protocol::MsgIdLayer.
+///
+/// The extending class is expected to define the listed below functions. They do not
+/// necessarily need to be @b static, accessing inner private state of the layer object
+/// is also acceptable.
+/// @li @b getMsgIdFromField() - Member function that is invoked to retrieve the
+/// numeric message ID out of the provided field object.
+/// @li @b beforeRead() - Member function that is invoked after appropriate
+/// message object has been created but the read operation has @b NOT yet been
+/// forwarded to the next protocol layer. It gives the developer a chance to
+/// update some extra transport fields accessible via message interface class.
+/// @li @b prepareFieldForWrite() - Member function that is invoked to prepare
+/// the field value before its write (serialization). After the function returns,
+/// the @ref comms::protocol::MsgIdLayer will invoke @b write member function
+/// of the passed field in order to serialize it.
+///
+/// The newly defined custom protocol stack layer can be used instead of
+/// @ref comms::protocol::MsgIdLayer when defining 
+/// @ref page_prot_stack_tutorial "protocol stack" (framing) of the protocol.
+///