Packets/Mainpage.dox

   1 /** \mainpage The SENF Packet Library
   2
   3     \section arch Overall Architecture
   4
   5     The Packet library consists of several components:
   6
   7     \li The \ref packet_module manages the packet data and provides the framework for handling the
   8         chain of packet headers. The visible interface is provided by the Packet class.
   9     \li \ref packetparser provides the framework for interpreting packet data. It handles
  10         parsing the packet information into meaningful values.
  11     \li The \ref protocolbundles provide concrete implementations for interpreting packets of
  12         some protocol. The Protocol Bundles are built on top of the basic packet library.
  13
  14     All these components work together to provide a hopefully simple and intuitive interface to
  15     packet parsing and creation.
  16
  17     \section intro Introduction
  18
  19     Whenever using the library, you will probably need to \c \#include it's header:
  20
  21     \code
  22     #include "Packets/Packets.hh"
  23     \endcode
  24
  25     \warning Never include any other Packets library header directly, always include \c
  26     Packets/Packets.hh.
  27
  28     Additionally you will have to include the header files for the packet types you use, e.g. \c
  29     Packets/DefaultBundle/EthernetPacket.hh etc.
  30
  31     Most every use of the packet library starts with some concrete packet typedef. Some fundamental
  32     packet types are provided by \ref protocolbundle_default. Building on those packet types, this
  33     example will build a complex packet: This will be an Ethernet packet containing an IPv4 UDP
  34     packet. We begin by building the raw packet skeleton:
  35
  36     \code
  37     senf::EthernetPacket eth      (senf::EthernetPacket::create());
  38     senf::IPv4Packet     ip       (senf::IPv4Packet    ::createAfter(ethernet));
  39     senf::UDPPacket      udp      (senf::UDPPacket     ::createAfter(ip));
  40     senf::DataPacket     payload  (senf::DataPacket    ::createAfter(udp,
  41                                                                      std::string("Hello, world!")));
  42     \endcode
  43
  44     These commands create what is called an interpreter chain. This chain consists of four
  45     interpreters. All interpreters reference the same data storage. This data storage is a random
  46     access sequence which contains the data bytes of the packet.
  47
  48     \note The data structures allocated are automatically managed using reference counting. In this
  49         example we have four packet references each referencing the same underlying data
  50         structure. This data structure will be freed when the last reference to it goes out of
  51         scope.
  52
  53     The packet created above already has the correct payload however all protocol fields are
  54     empty. We need to set those protocol fields:
  55
  56     \code
  57     udp->source()      = 2000u;
  58     udp->destination() = 2001u;
  59     ip->ttl()          = 255u;
  60     ip->source()       = senf::INet4Address::from_string("192.168.0.1");
  61     ip->destination()  = senf::INet4Address::from_string("192.168.0.2");
  62     eth->source()      = senf::MACAddress::from_string("00:11:22:33:44:55");
  63     eth->destination() = senf::MACAddress::from_string("00:11:22:33:44:66");
  64
  65     eth.finalize();
  66     \endcode
  67
  68     As seen above, packet fields are accessed using the <tt>-></tt> operator whereas other packet
  69     facilities (like \c finalize()) are directly accessed using the member operator. The field
  70     values are simple set using appropriately named accessors. As a last step, the \c finalize()
  71     call will update all calculated fields (fields like next-protocol, header or payload length,
  72     checksums etc). Now the packet is ready. We may now send it out using a packet socket
  73
  74     \code
  75     senf::PacketSocketHandle sock ("eth0");
  76     sock.write(eth.data());
  77     \endcode
  78
  79     The packet library also provides lot's of facilities to navigate the packet chain:
  80
  81     \code
  82     eth.next() == ip;                   // true
  83     eth.next().is<IPv4Packet>();        // true
  84     eth.next().next() == udp;           // true
  85     eth.next().is<UDPPacket>();         // false
  86     eth.next<UDPPacket>() == udp;       // true
  87
  88     udp.next<UDPPacket>();              // throws InvalidPacketChainException
  89     udp.next<UDPPacket>(senf::nothrow); // a senf::Packet testing as false
  90     udp.findNext<UDPPacket()> == udp;   // true
  91     udp.first<IPv4Packet>() == ip;      // true
  92
  93     udp.prev() == ip;                   // true
  94     udp.prev<EthernetPacket>() == eth   // true
  95     \endcode
  96
  97     ... and so on. It is therefore not necessary to stash away a reference for every interpreter (as
  98     each of the sub-packets are called) as long as at least one reference is available.
  99
 100     These chain navigation functions are also used to parse a packet. Let's read an Ethernet packet
 101     from a packet socket handle:
 102
 103     \code
 104     senf::PacketSocketHandle sock ("eth0");
 105     senf::EthernetPacket packet (senf::EthernetPacket::create(senf::Packet::noinit));
 106     sock.read(packet.data(),0u);
 107     \endcode
 108
 109     This first creates an uninitialized Ethernet packet and then reads into this packet. We can now
 110     parse this packet. Let's find out, whether this is a UDP packet destined to port 2001:
 111
 112     \code
 113     try {
 114         senf::UDPPacket udp (packet.findNext<UDPPacket>(senf::nothrow));
 115         if (udp && udp->destination() == 2001u) {
 116             // Voila ...
 117         }
 118     } catch (senf::TruncatedPacketException const &) {
 119         std::cerr << "Ooops !! Broken packet received ...\n"
 120     }
 121     \endcode
 122
 123     TruncatedPacketException is thrown by <tt>udp->destination()</tt> if that field cannot be
 124     accessed. More generally, whenever a field cannot be accessed because it would be out of bounds
 125     of the data read, this exception is generated.
 126
 127     This is only a very short introduction to the library to give a feel for the implementation. For
 128     a detailed discussion see the respective reference documentation.
 129  */
 130
 131 /** \defgroup protocolbundles Protocol Bundles
 132
 133     Each protocol bundle provides a collection of related concrete packet classes for a group of
 134     related protocols:
 135
 136     \li <a href="../../DefaultBundle/doc/html/index.html">DefaultBundle</a>: Some basic
 137         default protocols: Ethernet, Ip, TCP, UDP
 138     \li <a href="../../MPEGDVBBundle/doc/html/index.html">MPEGDVBBundle</a>: MPEG and DVB
 139         protocols
 140
 141     There are two ways to link with a bundle
 142
 143     \li If you only work with known packets which you explicitly reference you may just link with
 144         the corresponding library.
 145     \li If you need to parse unknown packets and want those to be parsed as complete as possible
 146         without explicitly referencing the packet type, you will need to link against the combined
 147         object file built for every bundle. This way, all packets defined in the bundle will be
 148         included whether they are explicitly referenced or not (and they will all automatically be
 149         registered).
 150  */
 151
 152 \f
 153 // Local Variables:
 154 // mode: c++
 155 // fill-column: 100
 156 // c-file-style: "senf"
 157 // indent-tabs-mode: nil
 158 // ispell-local-dictionary: "american"
 159 // mode: auto-fill
 160 // compile-command: "scons -u doc"
 161 // End:
 162