Parser Base class. More...

#include <senf/Packets/PacketParser.hh>

Public Types
typedef detail::packet::iterator	data_iterator
	Raw data iterator type. More...

typedef detail::packet::size_type	size_type
	Unsigned integral type. More...

typedef detail::packet::difference_type	difference_type
	Signed integral type. More...

typedef detail::packet::byte	byte
	Unsigned 8bit value, the raw value type. More...

typedef PacketData *	state_type
	Type of the 'state' parameter. More...

typedef PacketParserBase	parser_base_type
	Base type of the next parser. More...

Public Member Functions
data_iterator	i () const
	Return beginning of data to parse. More...

data_iterator	i (size_type offset) const
	Return iterator offset bytes from the start. More...

state_type	state () const
	Return state of this parser. More...

PacketData &	data () const
	Access the packets raw data container. More...

void	init () const
	Default implementation. More...

Protected Member Functions
ParserProtector	protect () const

	PacketParserBase (data_iterator i, state_type s)
	Standard constructor. More...

	PacketParserBase (data_iterator i, state_type s, size_type size)
	Size checking constructor. More...

bool	check (size_type size) const
	Check size of data container. More...

void	validate (size_type size) const
	Validate size of data container. More...

template<class Parser >
Parser	parse (data_iterator i) const
	Create sub-parser. More...

template<class Parser , class Arg >
Parser	parse (Arg const &arg, data_iterator i) const
	Create sub-parser. More...

template<class Parser >
Parser	parse (size_type n) const
	Create sub-parser. More...

template<class Parser , class Arg >
Parser	parse (Arg const &arg, size_type n) const
	Create sub-parser. More...

void	defaultInit () const
	Default implementation. More...

Packet	packet () const
	Get packet this parser is parsing from. More...

void	resize (size_type oldSize, size_type newSize)
	Resize data container. More...

Detailed Description

Parser Base class.

Parsers come in two flavors: fixed and dynamically sized parsers. A fixed size parser 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.

A dynamically sized 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.

If the parser just consists of sequence of consecutive fields (sub-parsers), the Helper macros for defining new packet parsers provide a simple yet flexible way to define a packet parser.
In more complex cases, you need to implement the necessary members manually.

This documentation is about the manual implementation. You should nevertheless read through this to understand, what above macros are doing.

The following example documents the interface (which must be) provided by a parser:

struct FooParser : public PacketParserBase
{
    FooParser(data_iterator i, state_type s) : PacketParserBase(i,s) {}
    // If this parser has a fixed size, you must define this size here This definition
    // allows the parser to be used within the list, vector and array parsers static
    static const size_type fixed_bytes = some_constant_size;
    // If the parser does not have a fixed size, you must implement the bytes() member to
    // return the size. ONLY EVER DEFINE ONE OF fixed_bytes OR bytes().
    size_type bytes() const;
    // If you define bytes(), you also need to define the init_bytes. This is the number
    // of bytes to allocate when creating a new object
    static const size_type init_bytes = some_constant_size;
    // You also may define an init() member. This will be called to initialize a newly
    // created data object. The default implementation just does nothing.
    void init() const;
    //-////////////////////////////////////////////////////////////////////////
    // 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 type() const { return parse<UInt16Parser>( 0 ); }
    senf::UInt16Parser size() const { return parse<UInt16Parser>( 2 ); }
};

    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
    will restrict your code to fixed size parsers (which depending on the circumstances may be
    exactly what you want).

    In the same way, don't access \c init_bytes directly, always use the senf::init_bytes
    meta-function class which correctly supports fixed size parsers.

Definition at line 228 of file PacketParser.hh.

Member Typedef Documentation

◆ byte

typedef detail::packet::byte senf::PacketParserBase::byte

Unsigned 8bit value, the raw value type.

Definition at line 237 of file PacketParser.hh.

◆ data_iterator

typedef detail::packet::iterator senf::PacketParserBase::data_iterator

Raw data iterator type.

Definition at line 234 of file PacketParser.hh.

◆ difference_type

typedef detail::packet::difference_type senf::PacketParserBase::difference_type

Signed integral type.

Definition at line 236 of file PacketParser.hh.

◆ parser_base_type

typedef PacketParserBase senf::PacketParserBase::parser_base_type

Base type of the next parser.

Definition at line 239 of file PacketParser.hh.

◆ size_type

typedef detail::packet::size_type senf::PacketParserBase::size_type

Unsigned integral type.

Definition at line 235 of file PacketParser.hh.

◆ state_type

typedef PacketData* senf::PacketParserBase::state_type

Type of the 'state' parameter.

Definition at line 238 of file PacketParser.hh.

Constructor & Destructor Documentation

◆ PacketParserBase() [1/2]

senf::PacketParserBase::PacketParserBase	(	data_iterator	i,
		state_type	s
	)

protected

Standard constructor.

This is the constructor used by most parsers. The parameters are just forwarded from the derived classes constructor parameters.

◆ PacketParserBase() [2/2]

senf::PacketParserBase::PacketParserBase	(	data_iterator	i,
		state_type	s,
		size_type	size
	)

protected

Size checking constructor.

In addition to the standard constructor, this constructor will validate, that there is enough data in the raw data container to parse size bytes after i.

This constructor is called by all 'final' parsers (e.g. the integer parsers) and only by those parsers. Most parsers do not check the validity of the iterator, this is delayed until the very last parser. This allows to partial parse truncated packets.

Exceptions

TruncatedPacketException if the raw data container does not hold at least size bytes beginning at i.

Member Function Documentation

◆ check()

bool senf::PacketParserBase::check ( size_type size ) const

protected

Check size of data container.

Returns: true, if the data container holds at least size beginning at i(), false otherwise.

◆ data()

PacketData& senf::PacketParserBase::data ( ) const

Access the packets raw data container.

This member will return the raw data container holding the data which is parsed by this parser.

◆ defaultInit()

void senf::PacketParserBase::defaultInit ( ) const

protected

Default implementation.

This is just an empty default implementation. Re-implement this member in your own parsers if needed.

◆ i() [1/2]

data_iterator senf::PacketParserBase::i ( ) const

Return beginning of data to parse.

The parser is expected to interpret the data beginning here. The size of the interpreted is given by senf::bytes(parser instance).

◆ i() [2/2]

data_iterator senf::PacketParserBase::i ( size_type offset ) const

Return iterator offset bytes from the start.

The return value is the same as i() + offset. However, the parser checks, that the iterator is still within range of the raw data container. Otherwise a TruncatedPacketException is thrown.

Exceptions

TruncatedPacketException if the raw data container does not hold at least offset bytes starting at i().

◆ init()

void senf::PacketParserBase::init ( ) const

Default implementation.

This is just an empty default implementation. Re-implement this member in your own parsers if needed.

◆ packet()

Packet senf::PacketParserBase::packet ( ) const

protected

Get packet this parser is parsing from.

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.

◆ parse() [1/4]

template<class Parser >

Parser senf::PacketParserBase::parse ( data_iterator i ) const

protected

Create sub-parser.

Creates a new instance of Parser to parse data beginning at i. Automatically passes state() to the new parser.

◆ parse() [2/4]

template<class Parser , class Arg >

Parser senf::PacketParserBase::parse	(	Arg const &	arg,
		data_iterator	i
	)		const

protected

Create sub-parser.

This is like parse(data_iterator), however it passes the extra argument arg to the Parser constructor.

◆ parse() [3/4]

template<class Parser >

Parser senf::PacketParserBase::parse ( size_type n ) const

protected

Create sub-parser.

Creates a new instance of Parser to parse data beginning at i() + n. Automatically passes state() to the new parser.

◆ parse() [4/4]

template<class Parser , class Arg >

Parser senf::PacketParserBase::parse	(	Arg const &	arg,
		size_type	n
	)		const

protected

Create sub-parser.

This is like parse(size_type), however it passes the extra argument arg to the Parser constructor.

◆ protect()

ParserProtector senf::PacketParserBase::protect ( ) const

protected

◆ resize()

void senf::PacketParserBase::resize	(	size_type	oldSize,
		size_type	newSize
	)

protected

Resize data container.

This command will erase or insert bytes from/into the data container at the end of the parser (at i() + newSize). If oldSize is > newSize, bytes will be removed, otherwise bytes will be inserted.

Warning: This may invalidate iterators and other parsers. The current parser itself is automatically updated

Definition at line 26 of file PacketParser.cc.

◆ state()

state_type senf::PacketParserBase::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.

◆ validate()

void senf::PacketParserBase::validate ( size_type size ) const

protected

Validate size of data container.

Exceptions

TruncatedPacketException if the raw data container does not hold at least size bytes beginning at i().

The documentation for this class was generated from the following files:

SENF Extensible Network Framework

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ byte

◆ data_iterator

◆ difference_type

◆ parser_base_type

◆ size_type

◆ state_type

Constructor & Destructor Documentation

◆ PacketParserBase() [1/2]

◆ PacketParserBase() [2/2]

Member Function Documentation

◆ check()

◆ data()

◆ defaultInit()

◆ i() [1/2]

◆ i() [2/2]

◆ init()

◆ packet()

◆ parse() [1/4]

◆ parse() [2/4]

◆ parse() [3/4]

◆ parse() [4/4]

◆ protect()

◆ resize()

◆ state()

◆ validate()