Packet Handling

Classes
struct	senf::DataPacketType
	Generic payload-only packet. More...
class	senf::Packet
	Main Packet class. More...
class	senf::ConcretePacket< PacketType >
	Protocol specific packet handle. More...
class	senf::PacketData
	Packet data STL-sequence view. More...
class	senf::PacketRegistry< Tag >
	Packet registration facility More...
struct	senf::PacketTypeBase
	Helper base-class implementing the PacketType interface. More...
class	senf::PacketTypeMixin< Self, Registry >
	Mixin to provide standard implementations for nextPacketRange and nextPacketType. More...

Macros
#define	SENF_PACKET_REGISTRY_REGISTER(registry, value, type)
	Statically add an entry to a packet registry. More...
#define	SENF_PACKET_REGISTRY_REGISTER_PRIORITY(registry, value, priority, type)
	Statically add an entry to a packet registry with explicit priority. More...

Functions
std::ostream &	senf::operator<< (std::ostream &os, Packet const &packet)
template<class PacketType , class Parser >
Parser	senf::operator<< (Parser target, ConcretePacket< PacketType > const &packet)
	Generic parser copying. More...

Detailed Description

The basic groundwork of the Packet library is the packet handling:

• The packet classes provide access to a chain of packet headers (more generically called interpreters).
• They automatically manage the required memory resources and the shared packet data.

The Interpreter Chain

The central data structure for a packet is the interpreter chain

The Interpreter Chain

This image depicts a packet with several headers. Each interpreter is responsible for a specific sub-range of the complete packet. This range always includes the packets payload (This is, why we call the data structure interpreter and not header: The interpreter is responsible for interpreting a range of the packet according to a specific protocol), the packet interpreters are nested inside each other.

For each interpreter, this structure automatically divides the packet into three areas (each of which are optional): The header, the payload and the trailer. Every packet will have either a header or a payload section while most don't have a trailer.

As user of the library you always interact with the chain through one (or more) of the interpreters. The interpreter provides methods to traverse to the following or preceding header (interpreter) and provides two levels of access to the packet data: Generic low-level access in the form of an STL compatible sequence and access to the parsed fields which are provided by the parser associated with the concrete packet type.

Resource Management

The interface to the packet library is provided using a handle class (Packet for generic, protocol agnostic access and ConcretePacket derived from Packet to access a specific protocol). This handle automatically manages the resources associated with the packet (the interpreter chain and the data storage holding the packet data). The resources are automatically released when the last packet handle referencing a specific packet is destroyed.

Implementation note:

The packet chain is provided on two levels: The internal representation PacketInterpreterBase and PacketInterpreter which are referenced by the Handle classes Packet and ConcretePacket.
The internal representation classes are pertinent in the sense, that they exist regardless of the existence of a handle referencing them (as long as the packet exists). Still the interpreter chain is lazy and packet interpreters beside the first are only created dynamically when accessed (this is implemented in the handle not in the internal representation).
The packet interpreters make use of a pool allocator. This provides extremely efficient creation and destruction of packet interpreter's and removes the dynamic memory management overhead from the packet interpreter management. The packet implementation class (PacketImpl which holds the packet data itself) however is still dynamically managed (however there is only a single instance for each packet).

Macro Definition Documentation

SENF_PACKET_REGISTRY_REGISTER

#define SENF_PACKET_REGISTRY_REGISTER	(		registry,
			value,
			type
	)

Statically add an entry to a packet registry.

This macro will declare an anonymous global variable in such a way, that constructing this variable will add a registration to the given packet registry.

Definition at line 233 of file PacketRegistry.hh.

SENF_PACKET_REGISTRY_REGISTER_PRIORITY

#define SENF_PACKET_REGISTRY_REGISTER_PRIORITY	(		registry,
			value,
			priority,
			type
	)

Statically add an entry to a packet registry with explicit priority.

This macro will declare an anonymous global variable in such a way, that constructing this variable will add a registration to the given packet registry.

Definition at line 247 of file PacketRegistry.hh.

Function Documentation

operator<<() [1/2]

std::ostream & senf::operator<<	(	std::ostream &	os,
		Packet const &	packet
	)

Definition at line 75 of file Packet.cc.

operator<<() [2/2]

template<class PacketType , class Parser >

Parser senf::operator<<	(	Parser	target,
		ConcretePacket< PacketType > const &	packet
	)

Generic parser copying.

This operator allows to copy the value of identical parsers. This operation does not depend on the parsers detailed implementation, it will just replace the data bytes of the target parser with those from the source packet.