Packets/Mainpage.dox

   1 /** \mainpage The SENF Packet Library
   2
   3     \section arch Overall Architecture
   4
   5     The general Architecture of the Packet Framework (pkf for short)
   6     is seperated into two components: The basic packet handling and
   7     the parser framework.
   8
   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.
  18
  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.
  27
  28     \section handling Packet Handling
  29
  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).
  35
  36     \section framework Parser Framework
  37
  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.
  45
  46     The parser framework contains some basic parsers to be used to
  47     build up more complex parsers:
  48
  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
  52        parse boolean flags.
  53
  54      - ParseArray.hh: The senf::Parse_Array parser to parse
  55        arbitrary fixed-size arrays of fixed-size elements (that is
  56        sub-parsers).
  57
  58      - ParseVec.hh: The senf::Parse_Vector parser to parse
  59        dynamically sized arrays of fixed-size elements (that is
  60        sub-parsers).
  61
  62     See senf::ParserBase for further information.
  63
  64     \section stuff Other Utilities
  65
  66     The pkf also comprises some additional utilities to support the
  67     development of packet classes.
  68
  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.
  75
  76     \todo The Packet Libarary really needs a refactoring of the public
  77         interfaface ...
  78
  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
  84         ...
  85
  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.
  93
  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
 102         them tunable.
 103  */
 104
 105 \f
 106 // Local Variables:
 107 // mode: c++
 108 // fill-column: 100
 109 // c-file-style: "senf"
 110 // indent-tabs-mode: nil
 111 // ispell-local-dictionary: "american"
 112 // mode: flyspell
 113 // mode: auto-fill
 114 // End: