-// Copyright (C) 2007
-// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
-// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
+// $Id$
+//
+// Copyright (C) 2007
+// Fraunhofer Institute for Open Communication Systems (FOKUS)
+// Competence Center NETwork research (NET), St. Augustin, GERMANY
// Stefan Bund <g0dil@berlios.be>
//
// This program is free software; you can redistribute it and/or modify
Here \c someField(), \c someOtherField() and \c someVector() are accessor methods named after
the field name. Each returns a parser object. Simple parsers can be used like their
- corresponding basic type (e.g. a Parse_UInt16 field can be used like an unsigned integer), more
+ 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).
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>\ref parserimpl_value</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::UInt16Parser which
returns an integer value).
\li <em>\ref parserimpl_collection</em> are parsers which model a collection of sub-elements like
- senf::Parse_List or senf::Parse_Vector.
+ senf::ListParser or senf::VectorParser.
\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>\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
- reference, use the senf::SafePacketParser wrapper. You still will need to take extra care to
+ reference, use the senf::SafePacketParserWrapper wrapper. You still will need to take extra care to
ensure the parser is not invalidated.
\section parserimpl Packet parser categories
\endcode
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
+ parser. Instead, you can rely on senf::VectorParser or senf::ListParser and implement new
policies.
\see parsecollection
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.
- \li If the parser just consists of a simple sequence of consecutive fields (sub-parsers),
- the \ref SENF_PACKET_PARSER_DEFINE_FIELDS and \ref
- SENF_PACKET_PARSER_DEFINE_FIXED_FIELDS macros provide a simple and convenient way to
- define the packet
+ \li If the parser just consists of sequence of consecutive fields (sub-parsers), the \ref
+ packetparsermacros provide a simple yet flexible way to define a packet parser.
\li In more complex cases, you need to implement the necessary members manually.
This documentation is about the manual implementation. You should nevertheless read through
// 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::Parse_UInt16 type() const { return parse<Parse_UInt16>( 0 ); }
- senf::Parse_UInt16 size() const { return parse<Parse_UInt16>( 2 ); }
+ senf::UInt16Parser type() const { return parse<UInt16Parser>( 0 ); }
+ senf::UInt16Parser size() const { return parse<UInt16Parser>( 2 ); }
};
\endcode
here. The size of the interpreted is given by
<tt>senf::bytes(</tt><em>parser
instance</em><tt>)</tt>. */
+
+ data_iterator i(size_type offset) const; ///< Return iterator \a offset bytes from the start
+ /**< The return value is the same as i() + \a
+ offset. However, the parser checks, that the iterator is
+ still within range of the raw data
+ container. Otherwise a TruncatedPacketException is
+ thrown.
+
+ \throws TruncatedPacketException if the raw data
+ container does not hold at least \a offset bytes
+ starting at i(). */
+
state_type state() const; ///< Return state of this parser
/**< The value returned should be interpreted as an opaque
value provided just to be forwarded to other
parsers. */
+
PacketData & data() const; ///< Access the packets raw data container
/**< This member will return the raw data container holding
the data which is parsed by \c this parser. */
/**< 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);
///< Size checking constructor
/**< In addition to the standard constructor, this
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) const; ///< Validate size of data container
/**< \throws TruncatedPacketException if the raw data
container does not hold at least \a size bytes
/**< Creates a new instance of \a Parser to parse data
beginning at \a i. Automatically passes \a state() to
the new parser. */
+
template <class Parser> Parser parse(size_type n) const; ///< Create sub-parser
/**< Creates a new instance of \a Parser to parse data
* beginning at i()<tt> + </tt>\a n. Automatically passes \a
parsers if needed. */
Packet packet() const; ///< Get packet this parser is parsing from
- /**< \important This member should only be used from packet
+ /**< \note This member should only be used from packet
parsers when access to previous or following packets is
needed e.g. for calculating checksums etc. */
data_iterator i_;
PacketData * data_;
- template <class Parser> friend class SafePacketParser;
+ template <class Parser> friend class SafePacketParserWrapper;
};
/** \brief Return raw size parsed by the given parser object
location will \e not be updated accordingly and therefore the parser will be
invalid.
- Additionally a SafePacketParser has an uninitialized state. The only allowed operations in
+ Additionally a SafePacketParserWrapper has an uninitialized state. The only allowed operations in
this state are the boolean test for validity and assigning another parser.
\ingroup packetparser
*/
template <class Parser>
- class SafePacketParser
- : public safe_bool< SafePacketParser<Parser> >
+ class SafePacketParserWrapper
+ : public safe_bool< SafePacketParserWrapper<Parser> >
{
public:
///////////////////////////////////////////////////////////////////////////
// default copy constructor
// default copy assignment
// default destructor
- SafePacketParser(); ///< Create an empty uninitialized SafePacketParser
+ SafePacketParserWrapper(); ///< Create an empty uninitialized SafePacketParserWrapper
// conversion constructors
- SafePacketParser(Parser parser); ///< Initialize SafePacketParser from \a parser
+ SafePacketParserWrapper(Parser parser); ///< Initialize SafePacketParserWrapper from \a parser
- SafePacketParser & operator=(Parser parser); ///< Assign \a parser to \c this
+ SafePacketParserWrapper & operator=(Parser parser); ///< Assign \a parser to \c this
///@}
///////////////////////////////////////////////////////////////////////////
projects / senf.git / blobdiff