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     Most every use of the packet library starts with some concrete packet typedef. Some fundamental
  20     packet typedefs are provided by \ref protocolbundle_default. The first example will build a
  21     complex packet: This will be an Ethernet packet containing an IPv4 UDP packet. We begin by
  22     building the raw packet skeleton:
  23
  24     \code
  25       senf::EthernetPacket eth      (senf::EthernetPacket::create());
  26       senf::IpV4Packet     ip       (senf::IpV4Packet::createAfter(ethernet));
  27       senf::UDPPacket      udp      (senf::UDPPacket::createAfter(ip));
  28       senf::DataPacket     payload  (senf::DataPacket::createAfter(udp,
  29                                                                    std::string("Hello, world!")));
  30     \endcode
  31
  32     These commands create what is called an interpreter chain. This chain consists of four
  33     interpreters. All interpreters reference the same data storage. This data storage is a random
  34     access sequence which contains the data bytes of the packet.
  35
  36     \note The data structures allocated are automatically managed using reference counting. In this
  37         example we have four packet references each referencing the same underlying data
  38         structure. This data structure will be freed when the last reference to it goes out of
  39         scope.
  40
  41     The packet created above already has the correct payload however all protocol fields are
  42     empty. We need to set those protocol fields:
  43
  44     \code
  45       udp->source()      = 2000u;
  46       udp->destination() = 2001u;
  47       ip->ttl()          = 255u;
  48       ip->source()       = senf::INet4Address("192.168.0.1"); // (*)
  49       ip->destination()  = senf::INet4Address("192.168.0.2"); // (*)
  50       eth->source()      = senf::MACAddress("00:11:22:33:44:55");
  51       eth->destination() = senf::MACAddress("00:11:22:33:44:66");
  52
  53       eth.finalize(); // (*)
  54     \endcode
  55
  56     As seen above, packet fields are accessed using the <tt>-></tt> operator whereas other packet
  57     facilities (like \c finalize()) are directly accessed using the member operator. The field
  58     values are simple set using appropriately named accessors. As a last step, the \c finalize()
  59     call will update all calculated fields (fields like next-protocol, header or payload length,
  60     checksums etc). Now the packet is ready. We may now send it out using a packet socket
  61
  62     \code
  63       senf::PacketSocketHandle sock ("eth0");
  64       sock.write(eth.data());
  65     \endcode
  66
  67     The packet library also provides lot's of facilities to navigate the packet chain:
  68
  69     \code
  70       eth.next() == ip;                   // true
  71       eth.next().is<IpV4Packet>();        // true
  72       eth.next().next() == udp;           // true
  73       eth.next().is<UDPPacket>();         // false
  74       eth.next<UDPPacket>() == udp;       // true
  75
  76       udp.next<UDPPacket>();              // throws InvalidPacketChainException
  77       udp.next<UDPPacket>(senf::nothrow); // a senf::Packet testing as false
  78       udp.findNext<UDPPacket()> == udp;   // true
  79       udp.first<IpV4Packet>() == ip;      // true
  80
  81       udp.prev() == ip;                   // true
  82       udp.prev<EthernetPacket>() == eth   // true
  83     \endcode
  84
  85     ... and so on. It is therefore not necessary to stash away a reference for every interpreter (as
  86     each of the sub-packets are called) as long as at least one reference is available.
  87
  88     These chain navigation functions are also used to parse a packet. Let's read an Ethernet packet
  89     from a packet socket handle:
  90
  91     \code
  92       senf::PacketSocketHandle sock ("eth0");
  93       senf::EthernetPacket packet (senf::EthernetPacket::create(senf::Packet::noinit));
  94       sock.read(packet.data(),0u);
  95     \endcode
  96
  97     This first creates an uninitialized Ethernet packet and then reads into this packet. We can now
  98     parse this packet. Let's find out, whether this is a UDP packet destined to port 2001:
  99
 100     \code
 101       try {
 102           senf::UDPPacket udp (packet.findNext<UDPPacket>(senf::nothrow));
 103           if (udp && udp->destination() == 2001u) {
 104               // Voila ...
 105           }
 106       } catch (senf::TruncatedPacketException const &) {
 107           std::cerr << "Ooops !! Broken packet received ...\n"
 108       }
 109     \endcode
 110
 111     TruncatedPacketException is thrown by <tt>udp->destination()</tt> if that field cannot be
 112     accessed. More generally, whenever a field cannot be accessed because it would be out of bounds
 113     of the data read, this exception is generated.
 114
 115     This is only a very short introduction to the library to give a feel for the implementation. For
 116     a detailed discussion see the respective reference documentation.
 117  */
 118
 119 \f
 120 // Local Variables:
 121 // mode: c++
 122 // fill-column: 100
 123 // c-file-style: "senf"
 124 // indent-tabs-mode: nil
 125 // ispell-local-dictionary: "american"
 126 // mode: auto-fill
 127 // compile-command: "scons -u doc"
 128 // End:
 129
 130 //  LocalWords:  mainpage SENF packetparser protocolbundles protocolbundle IPv4
 131 //  LocalWords:  udp endcode li senf EthernetPacket eth IpV createAfter ip std
 132 //  LocalWords:  ethernet UDPPacket DataPacket ttl INet MACAddress nothrow prev
 133 //  LocalWords:  PacketSocketHandle InvalidPacketChainException findNext noinit
 134 //  LocalWords:  tt TruncatedPacketException const cerr Ooops