\brief PacketParser public header */
/** \defgroup packetparser The PacketParser facility
-
+
The PacketParser facility provides a framework to implement very lightweight classes which parse
the raw content of a packet into meaningful values. PacketParsers are always passed around
<em>by value</em>, they can be understood as pointers into the packet data with added type
the field name. Each returns a parser object. Simple parsers can be used like their
corresponding basic type (e.g. a UInt16Parser field can be used like an unsigned integer), more
complex parsers provide type specific access members. Assigning a value to a parser will change
- the underlying representation (the packet data).
+ the underlying representation (the packet data).
Parsers can be grouped into several categories. These categories are not all defined rigorously
but are nevertheless helpful when working with the parsers:
processing fields in some way and so on). You should however be very wary to access data outside
the range assigned to the packet (the range starting at \c i() and with a size of senf::bytes()
bytes).
-
+
Each parser type has specific features
\subsection parserimpl_value Value parsers
\code
// SomeParser must have a 'value_type', The 'value_type' must be default constructible, copy
// constructible and assignable
- SomeParser::value_type v;
+ SomeParser::value_type v;
// An instance of 'SomeParser' must have a 'value' member which returns a value which may be
// assigned to a variable of type 'value_type'
\see parsecollection
\subsection parserimpl_composite Composite parsers
-
+
If possible, composite parsers should be implemented using the \ref packetparsermacros. In
addition to the normal parser requirements, these macros ensure, that for each field,
<em>fieldname</em><tt>_t</tt> is a typedef for the fields parser and
namespace senf {
class Packet;
-
+
/** \brief Parser Base class
Parsers come in two flavors: fixed and dynamically sized parsers. A <em>fixed size
A <em>dynamically sized</em> parser on the other hand infers it's size from the contents of
the data parsed. Any parser containing at least one dynamically sized sub-parser will itself
be dynamically sized.
-
+
Both kinds of parser need to derive from PacketParserBase and implement several required
members. Which members to implement depends on the parsers flavor. There are two ways how to
do this.
// ////////////////////////////////////////////////////////////////////////
- // Add here members returning (sub-)parsers for the fields. The 'parse' member is
+ // Add here members returning (sub-)parsers for the fields. The 'parse' member is
// used to construct the sub-parsers. This member either takes an iterator to the
// data to be parsed or just an offset in bytes.
senf::UInt16Parser size() const { return parse<UInt16Parser>( 2 ); }
};
\endcode
-
+
You should never call the \c bytes() member of a parser directly. Instead you should use the
freestanding senf::bytes() function. This function will return the correct size irrespective
of the parsers flavor. You may access \c fixed_bytes directly, however be aware that this
offset. However, the parser checks, that the iterator is
still within range of the raw data
container. Otherwise a TruncatedPacketException is
- thrown.
-
+ thrown.
+
\throws TruncatedPacketException if the raw data
container does not hold at least \a offset bytes
starting at i(). */
struct ParserProtector {
senf::safe_data_iterator safe_i_;
mutable PacketParserBase const * parser_;
-
+
ParserProtector( PacketParserBase const * parser);
ParserProtector(ParserProtector const & other_);
~ParserProtector();
};
protected:
ParserProtector protect() const;
-
+
PacketParserBase(data_iterator i, state_type s); ///< Standard constructor
/**< This is the constructor used by most parsers. The
parameters are just forwarded from the derived classes
constructor parameters. */
- PacketParserBase(data_iterator i, state_type s, size_type size);
+ PacketParserBase(data_iterator i, state_type s, size_type size);
///< Size checking constructor
/**< In addition to the standard constructor, this
constructor will validate, that there is enough data in
};
/** \brief Return raw size parsed by the given parser object
-
+
This function will either call <tt>p.bytes()</tt> or return <tt>Parser::fixed_bytes</tt>
depending on the type of parser.
*/
template <class Parser>
PacketParserBase::size_type bytes(Parser p);
-
+
namespace detail { template <class Parser> class ParserInitBytes; }
namespace detail { template <class Parser> class ParserIsFixed; }
# ifndef DOXYGEN
template <class Parser>
- typename boost::enable_if<
+ typename boost::enable_if<
boost::is_base_of<PacketParserBase, Parser>,
Parser >::type
operator<<(Parser target, Parser source);
# ifndef DOXYGEN
template <class Parser, class Value>
- typename boost::enable_if_c <
- boost::is_base_of<PacketParserBase, Parser>::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, Value const & value);
-# else
+# 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 operator allows to use a common syntax for assigning values or
- parsers to a parser.
+ parsers to a parser.
\ingroup packetparser
*/
# ifndef DOXYGEN
template <class Parser, class Value>
- typename boost::enable_if_c <
- boost::is_base_of<PacketParserBase, Parser>::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
+# 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.
+ 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.
/** \brief Default parser parsing nothing
*/
- struct VoidPacketParser
+ struct VoidPacketParser
: public PacketParserBase
{
# include SENF_FIXED_PARSER()
projects / senf.git / blobdiff