Packets/Mainpage.dox

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