senf::Packet Class Reference
[Packet Handling]

Main Packet class. More...

#include <senf/Packets/Packet.hh>

Inheritance diagram for senf::Packet:

Detailed Description

Main Packet class.

Packet is the main externally visible class of the packet library. Packet is a handle into the internal packet representation. From Packet you may access the data of that specific sub-packet/header/interpreter and navigate to the neighboring sub-packets/headers/interpreters.

Packet is protocol agnostic. This class only provides non-protocol dependent members. To access the protocol specific features of a packet (like header fields) the ConcretePacket class extending Packet is provided.

Semantics

All operations accessing the data of this packet in some way will ignore any preceding packets/headers/interpreters in the chain. It does not matter, whether a given packet is taken from the middle or the beginning of the chain, all operations (except those explicitly accessing the chain of course) should work the same.

This especially includes members like clone() or append(): clone() will clone only from this packet until the end of the chain, append() will append the given packet ignoring any possibly preceding packets/headers/interpreters.

In the same way, the data() member provides an STL-sequence compatible view of the packet data. This only includes the data which is part of this packet including header, trailer and payload but not the headers or trailers of packets before this packet in the packet/header/interpreter chain (nonetheless, this data overlaps with the data of other packets).

Several members are member templates taking an OtherPacket template parameter. This parameter must be the ConcretePacket instantiation associated with some concrete packet type (protocol). For each implemented protocol, typedefs should be provided for these instantiations (Example: EthernetPacket is a typedef for ConcretePacket < EthernetPacketType >).

See also:: ConcretePacket for the type specific interface
PacketData for the sequence interface
The PacketParser facility for a specification of the parser interface

Definition at line 140 of file Packet.hh.


Public Types
typedef void	type
	Type of the packet.
typedef senf::detail::packet::size_type	size_type
	Unsigned type to represent packet size.
typedef PacketInterpreterBase::factory_t	factory_t
	Packet factory type (see below).
Structors and default members
	Packet ()
	Create uninitialized packet handle.
Packet	clone () const
	Create copy packet.
template<class PacketType >
	Packet (ConcretePacket< PacketType > const &packet)
	Copy-construct Packet from ConcretePacket.
Interpreter chain access
Packet	next () const
	Get next packet in chain.
Packet	next (NoThrow_t) const
	Get next packet in chain.
template<class OtherPacket >
OtherPacket	next () const
	Get next packet in chain and cast to OtherPacket.
template<class OtherPacket >
OtherPacket	next (NoThrow_t) const
	Get next packet in chain and cast to OtherPacket.
template<class OtherPacket >
OtherPacket	find () const
	Search chain forward for packet of type OtherPacket.
template<class OtherPacket >
OtherPacket	find (NoThrow_t) const
	Search chain forward for packet of type OtherPacket.
Packet	prev () const
	Get previous packet in chain.
Packet	prev (NoThrow_t) const
	Get previous packet in chain.
template<class OtherPacket >
OtherPacket	prev () const
	Get previous packet in chain and cast to OtherPacket.
template<class OtherPacket >
OtherPacket	prev (NoThrow_t) const
	Get previous packet in chain and cast to OtherPacket.
template<class OtherPacket >
OtherPacket	rfind () const
	Search chain backwards for packet of type OtherPacket.
template<class OtherPacket >
OtherPacket	rfind (NoThrow_t) const
	Search chain backwards for packet of type OtherPacket.
Packet	first () const
	Return first packet in chain.
template<class OtherPacket >
OtherPacket	first () const
	Return first packet in chain and cast.
Packet	last () const
	Return last packet in chain.
template<class OtherPacket >
OtherPacket	last () const
	Return last packet in chain and cast.
template<class OtherPacket >
OtherPacket	parseNextAs () const
	Interpret payload of `this` as OtherPacket.
Packet	parseNextAs (factory_t factory) const
	Interpret payload of `this` as factory type packet.
template<class OtherPacket >
bool	is () const
	Check, whether `this` packet is of the given type.
template<class OtherPacket >
OtherPacket	as () const
	Cast current packet to the given type.
template<class OtherPacket >
OtherPacket	as (NoThrow_t) const
	Cast current packet to the given type.
Packet	append (Packet const &packet) const
	Append the given packet to `this` packet.
void	reparse () const
	Reparse the payload the packet.
Data access
PacketData &	data () const
	Access the packets raw data container.
size_type	size () const
	Return size of packet in bytes.
Annotations
template<class Annotation >
Annotation &	annotation ()
	Get packet annotation.
template<class Annotation >
Annotation const &	annotation () const
	Get packet annotation.
void	clearAnnotations ()
	Clear all packet annotations.
Other methods
bool	operator== (Packet const &other) const
	Check for packet identity.
bool	boolean_test () const
	Check, whether the packet is valid().
bool	valid () const
	Check, whether the packet is valid().
void	finalizeThis ()
	Update calculated fields.
template<class Other >
void	finalizeTo ()
	Update calculated fields.
void	finalizeTo (Packet const &other)
	Update calculated fields.
void	finalizeAll ()
	Update calculated fields.
void	dump (std::ostream &os) const
	Write out a printable packet representation.
TypeIdValue	typeId () const
	Get type of `this` packet.
factory_t	factory () const
	Return factory instance of `this` packet.
unsigned long	id () const
	Unique packet id.
bool	is_shared () const
	check if this packet shares data with any another packet handle.
Protected Member Functions
	Packet (PacketInterpreterBase::ptr const &packet)
PacketInterpreterBase::ptr const &	ptr () const

Member Typedef Documentation

typedef PacketInterpreterBase::factory_t senf::Packet::
factory_t

Packet factory type (see below).

Definition at line 151 of file Packet.hh.

typedef senf::detail::packet::size_type senf::Packet::
size_type

Unsigned type to represent packet size.

Definition at line 150 of file Packet.hh.

typedef void senf::Packet::
type

Type of the packet.

Reimplemented in senf::ConcretePacket< PacketType >.

Definition at line 148 of file Packet.hh.

Constructor & Destructor Documentation

senf::Packet::
Packet	()

Create uninitialized packet handle.

An uninitialized handle is in - valid(). It does not allow any operation except assignment and checking for validity.

Definition at line 50 of file Packet.cci.

template<class PacketType >

senf::Packet::
Packet	(	ConcretePacket< PacketType > const &	packet	)

Copy-construct Packet from ConcretePacket.

This constructor allows to convert an arbitrary ConcretePacket into a general Packet, loosing the protocol specific interface.

Definition at line 40 of file Packet.cti.

senf::Packet::
Packet	(	PacketInterpreterBase::ptr const &	packet	)

Definition at line 37 of file Packet.cci.

Member Function Documentation

template<class Annotation >

Annotation const & senf::Packet::
annotation	()

Get packet annotation.

See also:: annotation()

Definition at line 158 of file Packet.cti.

template<class Annotation >

Annotation & senf::Packet::
annotation	()

Get packet annotation.

This member will retrieve an arbitrary packet annotation. Every annotation is identified by a unique Annotation type. This type should always be a struct.

struct MyAnnotation {
    int value;
};

senf::Packet p (...);

p.annotation<MyAnnotation>().value = 1;

Annotations are shared by all headers / interpreters within a single packet chain.

If an annotation is not a POD type (more specifically, if it's constructor or destructor is not trivial including base classes and members), the Annotation type must inherit from senf::ComplexAnnotation. Failing to follow this rule will result in undefined behavior and will probably lead to a program crash.

struct MyStringAnnotation : senf::ComplexAnnotation {
    std::string value;
};

(This type is not POD since std::string is not POD)

See also:: Annotations

Implementation note:: The annotation system is implemented quite efficiently since annotations are stored within a packet embedded vector of fixed size (the size is determined automatically at runtime by the number of different annotations used). Additionally, non-complex small annotations require no additional memory management (new / delete).

Idea:: Pool the annotation vectors: In the destructor swap the vector into a vector graveyard (swapping two vectors is an O(1) no allocation operation). In the constructor, if there is a vector in the graveyard, swap it in from there. Of course, it would be better to do away with the vector and just allocate the space together with the packet but that looks quite complicated to do ... especially considering that the packetimpl itself uses a pool.

Definition at line 152 of file Packet.cti.

senf::Packet senf::Packet::
append	(	Packet const &	packet	)

Append the given packet to this packet.

This operation will replace the payload section of this packet with packet. This operation will replace the packet chain after this packet with a clone of packet and will replace the raw data of the payload of this with the raw data of packet. this packet will not share any data with packet.

Returns:: Packet handle to the cloned packet, placed after this in the packet/header/interpreter chain.

Definition at line 113 of file Packet.cci.

template<class OtherPacket >

OtherPacket senf::Packet::
as	(	NoThrow_t	)

Cast current packet to the given type.

This operations returns a handle to the same packet header/interpreter however upcast to the given ConcretePacket type which have been instantiated before.

Warning:: You must make absolutely sure that the packet is of the given type. If not, calling this member crashes your program in a unkindly way.

Definition at line 73 of file Packet.cti.

template<class OtherPacket >

OtherPacket senf::Packet::
as	()

Cast current packet to the given type.

This operations returns a handle to the same packet header/interpreter however upcast to the given ConcretePacket type which have been instantiated before.

Exceptions:

std::bad_cast

if the current packet is not of type OtherPacket

Definition at line 61 of file Packet.cti.

bool senf::Packet::
boolean_test	()

Check, whether the packet is valid().

See also:: valid()

Definition at line 174 of file Packet.cci.

void senf::Packet::
clearAnnotations	()

Clear all packet annotations.

All packet annotations will be cleared. Afterwards the annotations equates to a new created packet.

Warning:: all references to existing complex annotations become invalid.

Definition at line 198 of file Packet.cci.

senf::Packet senf::Packet::
clone	()

Create copy packet.

clone() will create a complete copy of this packet. The returned packet will have the same data, annotations and packet chain. It does however not share any data with the original packet.

Reimplemented in senf::ConcretePacket< PacketType >.

Definition at line 55 of file Packet.cci.

senf::PacketData & senf::Packet::
data	()

Access the packets raw data container.

Definition at line 121 of file Packet.cci.

void senf::Packet::
dump	(	std::ostream &	os	)

Write out a printable packet representation.

This method is provided mostly to help debugging packet problems. Each concrete packet should implement a dump method writing out all fields of the packet in a readable representation. dump() will call this member for each packet/header/interpreter in the chain from this packet up to the end of the chain.

Definition at line 57 of file Packet.cc.

senf::Packet::factory_t senf::Packet::
factory	()

Return factory instance of this packet.

The returned factory instance can be used to create new packets of the given type without knowing the concrete type of the packet. The value may be stored away for later use if needed.

Definition at line 162 of file Packet.cci.

void senf::Packet::
finalizeAll	()

Update calculated fields.

The finalize() family of members will update calculated packet fields: checksums, size fields and so on. This includes any field, which can be set from other information in the packet. Each concrete packet type should document, which fields are set by finalize().

finalizeAll() will automatically process all packets/headers/interpreters from the end of the chain (the most inner packet) backwards up to this.

This call is equivalent to

    p.finalizeTo(p.last())

Beware, that finalizeAll() will not finalize any headers before this, it will only process inner headers.

Definition at line 151 of file Packet.cci.

void senf::Packet::
finalizeThis	()

Update calculated fields.

The finalize() family of members will update calculated packet fields: checksums, size fields and so on. This includes any field, which can be set from other information in the packet. Each concrete packet type should document, which fields are set by finalize().

finalizeThis() will only process the current header. Even if only changing fields in this protocol, depending on the protocol it may not be enough to finalize this header only. See the packet type documentation.

Definition at line 141 of file Packet.cci.

void senf::Packet::
finalizeTo	(	Packet const &	other	)

Update calculated fields.

The finalize() family of members will update calculated packet fields: checksums, size fields and so on. This includes any field, which can be set from other information in the packet. Each concrete packet type should document, which fields are set by finalize().

finalizeTo(other) will automatically process all packets/headers/interpreters beginning at other backwards towards outer packets up to this.

Definition at line 146 of file Packet.cci.

template<class Other >

void senf::Packet::
finalizeTo	()

Update calculated fields.

The finalize() family of members will update calculated packet fields: checksums, size fields and so on. This includes any field, which can be set from other information in the packet. Each concrete packet type should document, which fields are set by finalize().

finalizeTo() will automatically process all packets/headers/interpreters from the first occurrence of packet type Other (beginning at this packet searching forward towards deeper nested packets) backwards up to this.

This call is equivalent to

    p.finalizeTo(p.next<Other>())

Definition at line 145 of file Packet.cti.

template<class OtherPacket >

OtherPacket senf::Packet::
find	(	NoThrow_t	)

Search chain forward for packet of type OtherPacket.

The search will start with the current packet.

Returns:: in - valid() packet if no packet of type OtherPacket can be found.

Definition at line 37 of file Packet.ct.

template<class OtherPacket >

OtherPacket senf::Packet::
find	()

Search chain forward for packet of type OtherPacket.

The search will start with the current packet.

Exceptions:

InvalidPacketChainException

if no packet of type OtherPacket can be found.

Definition at line 97 of file Packet.cti.

template<class OtherPacket >

OtherPacket senf::Packet::
first	()

Return first packet in chain and cast.

Exceptions:

std::bad_cast

if the first() packet is not of type OtherPacket

OtherPacket senf::Packet::
first	()

Return first packet in chain.

Definition at line 94 of file Packet.cci.

unsigned long senf::Packet::
id	()

Unique packet id.

Get a unique packet id. If two packets have the same id, they share the internal data representation.

Definition at line 168 of file Packet.cci.

template<class OtherPacket >

bool senf::Packet::
is	()

Check, whether this packet is of the given type.

Definition at line 54 of file Packet.cti.

bool senf::Packet::
is_shared	()

check if this packet shares data with any another packet handle.

This method returns true if there is any other packet handle pointing to any header in the packet chain.

Definition at line 186 of file Packet.cci.

template<class OtherPacket >

OtherPacket senf::Packet::
last	()

Return last packet in chain and cast.

Exceptions:

std::bad_cast

if the last() packet is not of type OtherPacket

OtherPacket senf::Packet::
last	()

Return last packet in chain.

Definition at line 100 of file Packet.cci.

template<class OtherPacket >

OtherPacket senf::Packet::
next	(	NoThrow_t	)

Get next packet in chain and cast to OtherPacket.

Returns:: in - valid() packet if no next packet exists or if next() packet is not of type OtherPacket

template<class OtherPacket >

OtherPacket senf::Packet::
next	()

Get next packet in chain and cast to OtherPacket.

Exceptions:

	std::bad_cast	if the next() packet is not of type OtherPacket
	InvalidPacketChainException	if no next packet exists

OtherPacket senf::Packet::
next	(	NoThrow_t	)

Get next packet in chain.

Returns:: in - valid() packet if no next packet exists

Definition at line 63 of file Packet.cci.

OtherPacket senf::Packet::
next	()

Get next packet in chain.

Exceptions:

InvalidPacketChainException

if no next packet exists

Definition at line 72 of file Packet.cci.

bool senf::Packet::
operator==	(	Packet const &	other	)

Check for packet identity.

Two packet handles compare equal if they really are the same packet header in the same packet chain.

Definition at line 135 of file Packet.cci.

senf::Packet senf::Packet::
parseNextAs	(	factory_t	factory	)

Interpret payload of this as factory type packet.

parseNextAs() will throw away the packet chain after the current packet if necessary. It will then parse the payload section of this packet as given by factory. The new packet is added to the chain after this.

Returns:: new packet instance sharing the same data and placed after this packet in the chain.

Exceptions:

InvalidPacketChainException

if no next packet header is allowed (viz. nextPacketRange() of the the current PacketType returns no_range() )

Definition at line 107 of file Packet.cci.

template<class OtherPacket >

OtherPacket senf::Packet::
parseNextAs	()

Interpret payload of this as OtherPacket.

parseNextAs() will throw away the packet chain after the current packet if necessary. It will then parse the payload section of this packet as given by OtherPacket. The new packet is added to the chain after this.

Returns:: new packet instance sharing the same data and placed after this packet in the chain.

Exceptions:

InvalidPacketChainException

if no next packet header is allowed (viz. nextPacketRange() of the the current PacketType returns no_range() )

Definition at line 47 of file Packet.cti.

template<class OtherPacket >

OtherPacket senf::Packet::
prev	(	NoThrow_t	)

Get previous packet in chain and cast to OtherPacket.

Returns:: in - valid() packet if no previous packet exists or if the previous packet is not of type OtherPacket

template<class OtherPacket >

OtherPacket senf::Packet::
prev	()

Get previous packet in chain and cast to OtherPacket.

Exceptions:

	std::bad_cast,if	the previous packet is not of type OtherPacket
	InvalidPacketChainException	if no previous packet exists

OtherPacket senf::Packet::
prev	(	NoThrow_t	)

Get previous packet in chain.

Returns:: in - valid() packet if no previous packet exists

Definition at line 80 of file Packet.cci.

OtherPacket senf::Packet::
prev	()

Get previous packet in chain.

Exceptions:

InvalidPacketChainException

if no previous packet exists

Definition at line 86 of file Packet.cci.

senf::PacketInterpreterBase::ptr const & senf::Packet::
ptr	()

Definition at line 41 of file Packet.cci.

void senf::Packet::
reparse	()

Reparse the payload the packet.

This member will throw away the packet chain after the current packet. The payload will be reparsed automatically when calling next()

Definition at line 192 of file Packet.cci.

template<class OtherPacket >

OtherPacket senf::Packet::
rfind	(	NoThrow_t	)

Search chain backwards for packet of type OtherPacket.

The search will start with the current packet.

Returns:: in - valid() packet if no packet of type OtherPacket can be found.

Definition at line 50 of file Packet.ct.

template<class OtherPacket >

OtherPacket senf::Packet::
rfind	()

Search chain backwards for packet of type OtherPacket.

The search will start with the current packet.

Exceptions:

InvalidPacketChainException

if no packet of type OtherPacket can be found.

Definition at line 122 of file Packet.cti.

senf::Packet::size_type senf::Packet::
size	()

Return size of packet in bytes.

This size does not include the size of any preceding headers/packets/interpreters. It does however include this packets payload.

Definition at line 127 of file Packet.cci.

senf::TypeIdValue senf::Packet::
typeId	()

Get type of this packet.

This value is used e.g. in the packet registry to associate packet types with other information.

Returns:: A type holding the same information as a type_info object, albeit assignable

Definition at line 156 of file Packet.cci.

bool senf::Packet::
valid	()

Check, whether the packet is valid().

An in - valid() packet does not allow any operation except checking for validity and assignment. in - valid() packets serve the same role as 0-pointers.

This is an alias for boolean_test() which is called when using a packet in a boolean context.

Definition at line 180 of file Packet.cci.

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

SENF Extensible Network Framework

senf::Packet Class Reference[Packet Handling]

Detailed Description

Semantics

Public Types

Structors and default members

Interpreter chain access

Data access

Annotations

Other methods

Protected Member Functions

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

senf::Packet Class Reference
[Packet Handling]