Parsers can be grouped into several categories. These categories are not all defined rigorously
but are nevertheless helpful when working with the parsers:
- \li <em>Value parsers</em> provide the lowest level parsers (e.g. senf::Parse_UInt16 which
+ \li <em>\ref parserimpl_value</em> provide the lowest level parsers (e.g. senf::Parse_UInt16 which
returns an integer value).
- \li <em>Collection parsers</em> are parsers which model a collection of sub-elements like
+ \li <em>\ref parserimpl_collection</em> are parsers which model a collection of sub-elements like
senf::Parse_List or senf::Parse_Vector.
- \li <em>Composite parsers</em> collect several fields of arbitrary type into a new
+ \li <em>\ref parserimpl_composite</em> collect several fields of arbitrary type into a new
parser. Parsers defined using the \ref packetparsermacros fall under this category.
- \li <em>Packet parsers</em> are used to define a packet type.
+ \li <em>\ref parserimpl_packet</em> are used to define a packet type.
\warning Parsers are like iterators: They are invalidated <em>whenever the size of the packet's
data is changed</em>. You should not store a parser anywhere. If you want to keep a parser
You will probably only very seldom need to implement a completely new collection
parser. Instead, you can rely on senf::Parse_Vector or senf::Parse_List and implement new
- polcies.
+ policies.
\subsection parserimpl_composite Composite parsers
interface. These members may access the packet data in any way. You just need to ensure, that
the integration into the packet-type is correct (the senf::PacketTypeMixin will by default use
senf::bytes() to find the end of the header).
-
+
+ <hr>
*/
#ifndef HH_PacketParser_
#include <boost/utility/enable_if.hpp>
#include <boost/type_traits.hpp>
#include <boost/optional.hpp>
-#include "Utils/SafeBool.hh"
+#include "../Utils/SafeBool.hh"
#include "PacketTypes.hh"
#include "PacketData.hh"
///////////////////////////////hh.p////////////////////////////////////////
namespace senf {
+
+ class Packet;
/** \brief Parser Base class
- Parsers come in two favors: fixed and dynamically sized parsers. A <em>fixed size
+ Parsers come in two flavors: fixed and dynamically sized parsers. A <em>fixed size
parser</em> has a constant size, it will always parse a fixed number of bytes. The low-level
'final' parsers (like the integer parsers) are fixed size parsers as are composite parsers
built up only of fixed-size fields.
container does not hold at least \a size bytes
beginning at \a i. */
- bool check(size_type size); ///< Check size of data container
+ bool check(size_type size) const; ///< Check size of data container
/**< \returns \c true, if the data container holds at least
\a size beginning at i(), \c false otherwise. */
- void validate(size_type size); ///< Validate size of data container
+ void validate(size_type size) const; ///< Validate size of data container
/**< \throws TruncatedPacketException if the raw data
container does not hold at least \a size bytes
beginning at i(). */
implementation. Re-implement this member in your own
parsers if needed. */
+ Packet packet() const; ///< Get packet this parser is parsing from
+ /**< \important This member should only be used from packet
+ parsers when access to previous or following packets is
+ needed e.g. for calculating checksums etc. */
+
private:
- data_iterator end();
+ data_iterator end() const;
data_iterator i_;
PacketData * data_;
# else
/** \brief Generic parser copying
+
This operator allows to copy the values of identical parsers. This operation does \e not
depend on the parsers detailed implementation, it will just replace the data bytes of the
target parser with those from the source parser. This allows to easily copy around complex
Parser operator<<(Parser target, Value const & value);
# endif
+# ifndef DOXYGEN
+ template <class Parser, class Value>
+ typename boost::enable_if_c <
+ boost::is_base_of<PacketParserBase, Parser>::value
+ && ! boost::is_base_of<PacketParserBase, Value>::value,
+ Parser >::type
+ operator<<(Parser target, boost::optional<Value> const & value);
+# else
+ /** \brief Generic parser value assignment
+
+ This operator allows to assign a value to parsers which implement a <tt>value(</tt>\a
+ value<tt>)</tt> member. This special version allows to assign optional values: IF the
+ optional value is not set, the assignment will be skipped.
+
+ This operator allows to use a common syntax for assigning values or parsers to a parser.
+
+ \ingroup packetparser
+ */
+ template <class Parser, class Value>
+ Parser operator<<(Parser target, boost::optional<Value> const & value);
+# endif
+
/** \defgroup packetparsermacros Helper macros for defining new packet parsers
To simplify the definition of simple packet parsers, several macros are provided. Before
using these macros has the following form (This is a concrete example from the definition of
the ethernet packet in <tt>DefaultBundle/EthernetPacket.hh</tt>)
- \dontinclude EthernetPacket.hh
- \skipline struct Parse_EthVLan : public PacketParserBase
- \until };
-
+ \code
+ struct Parse_EthVLan : public PacketParserBase
+ {
+ typedef Parse_UIntField < 0, 3 > Parse_Priority;
+ typedef Parse_Flag < 3 > Parse_CFI;
+ typedef Parse_UIntField < 4, 16 > Parse_VLanId;
+ typedef Parse_UInt16 Parse_Type;
+
+ SENF_PACKET_PARSER_INIT(Parse_EthVLan);
+
+ SENF_PACKET_PARSER_DEFINE_FIXED_FIELDS(
+ ((OverlayField)( priority, Parse_Priority ))
+ ((OverlayField)( cfi, Parse_CFI ))
+ ((Field )( vlanId, Parse_VLanId ))
+ ((Field )( type, Parse_Type )) );
+ };
+ \endcode
+
The macros take care of the following:
\li They define the accessor functions returning parsers of the given type.
\li They automatically calculate the offset of the fields from the preceding fields.