1 /** \mainpage The SENF Packet Library
3 \section arch Overall Architecture
5 The general Architecture of the Packet Framework (pkf for short)
6 is seperated into two components: The basic packet handling and
9 The basic packet handling implements a packet interpreter
10 chain. Every packet is represented as a chain of interpreters
11 where each interpreter is a facade looking into the same
12 packet. Each interpreter will interpret a specific header of a
13 packet. For example, an ethernet frame might have an interpreter
14 chain consisting of EthernetPacket, IPPacket, UDPPacket and
15 DataPacket. Each of these interpreters will interpret a section of
16 the raw data bytes. The interpreter ranges overlap since every
17 packet also includes it's payload.
19 The parser framework is used to interpret the raw bytes of a
20 specific packet and parse the values present in that packet. For
21 example, Parse_Ethernet will parse the ethernet source MAC,
22 destination MAC and ethertype given any random access iterator to
23 the first byte of the ethernet frame. Parsers are extremely light
24 classes. They are temporary classes passed around by value. In
25 most cases, they are just comprised of a single pointer adorned
26 with type information.
28 \section handling Packet Handling
30 The packet handling is implemented within
31 senf::Packet. This class is the baseclass to all packet
32 interpreter facades. To implement a new packet type, publically
33 derive from senf::Packet and implement the virtual
34 interface (see the class documentation for details).
36 \section framework Parser Framework
38 The parser framework provides an abstract framwork to parse packet
39 oriented data. A Parser is a template class taking an arbitrary
40 iterator as input and allowing random access to data elements of
41 the interpreted type, like source and destination MAC of an
42 ethernet frame. The parser framework is to be used hierarchically
43 and recursively, the parser methods should return further parsers
44 which can return further parsers and so on.
46 The parser framework contains some basic parsers to be used to
47 build up more complex parsers:
49 - ParseInt.hh: Lots of parsers for integer numbers like
50 senf::Parse_UInt8, for integer bitfields like
51 senf::Parse_UIntField and senf::Parse_Flag to
54 - ParseArray.hh: The senf::Parse_Array parser to parse
55 arbitrary fixed-size arrays of fixed-size elements (that is
58 - ParseVec.hh: The senf::Parse_Vector parser to parse
59 dynamically sized arrays of fixed-size elements (that is
62 See senf::ParserBase for further information.
64 \section stuff Other Utilities
66 The pkf also comprises some additional utilities to support the
67 development of packet classes.
69 The senf::PacketRegistry implements a registry of packets
70 keyed by an arbitrary type. The registry is used to find a packet
71 type given some kind of id (like the ethertype value from the
72 ethernet header). Together with it's support classes (especially
73 senf::PacketRegistryMixin) this class greatly simplifies
74 implementing the needed table lookups.
76 \todo The Packet Libarary really needs a refactoring of the public
79 \idea Add the Handle-Body idiom to the mix with a PacketRef (or
80 HeaderRef or InterpreterRef or whatever class). This would
81 have members for all the API defined in Packet now. \c
82 operator-> would return a parser object to interpret the
83 data. This would make awayy with the inheritance relationship
86 \idea Templating the parsers on the iterator type does not
87 introduce additional coupling (because of the inlining) but
88 looking at it after the fact it looks like severe overdesign
89 and it does introduce some problems (e.g. rebind and all this
90 entails). If we just implement all parsers for
91 Packet::byte_iterator they are no tmplates any more which
92 should simplify things a log.
94 \idea we need some better and automatic checking on data access
95 especially after data has changed. Idea 1: give the parser the
96 end iterator as additional member. Enforce, that all parsers
97 must ultimately be based on ParseInt and have ParseInt check
98 against end() at construction time. Idea 2: add a dirty flag
99 to the interpreters. Set this flag whenever the packet is
100 changed and recall check() in operator-> of the PacketRef
101 object if the packet is dirty. Maybe we need both and make
110 // ispell-local-dictionary: "american"