1 /** \mainpage The SENF Packet Library
3 \section arch Overall Architecture
5 The Packet library consists of several components:
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.
14 All these components work together to provide a hopefully simple and intuitive interface to
15 packet parsing and creation.
17 \section intro Introduction
19 Whenever using the library, you will probably need to \c \#include it's header:
22 #include "Packets/Packets.hh"
25 \warning Never include any other Packets library header directly, always include \c
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.
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:
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!")));
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.
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
53 The packet created above already has the correct payload however all protocol fields are
54 empty. We need to set those protocol fields:
57 udp->source() = 2000u;
58 udp->destination() = 2001u;
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");
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
75 senf::PacketSocketHandle sock ("eth0");
76 sock.write(eth.data());
79 The packet library also provides lot's of facilities to navigate the packet chain:
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
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
93 udp.prev() == ip; // true
94 udp.prev<EthernetPacket>() == eth // true
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.
100 These chain navigation functions are also used to parse a packet. Let's read an Ethernet packet
101 from a packet socket handle:
104 senf::PacketSocketHandle sock ("eth0");
105 senf::EthernetPacket packet (senf::EthernetPacket::create(senf::Packet::noinit));
106 sock.read(packet.data(),0u);
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:
114 senf::UDPPacket udp (packet.findNext<UDPPacket>(senf::nothrow));
115 if (udp && udp->destination() == 2001u) {
118 } catch (senf::TruncatedPacketException const &) {
119 std::cerr << "Ooops !! Broken packet received ...\n"
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.
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.
131 /** \defgroup protocolbundles Protocol Bundles
133 Each protocol bundle provides a collection of related concrete packet classes for a group of
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
141 There are two ways to link with a bundle
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
156 // c-file-style: "senf"
157 // indent-tabs-mode: nil
158 // ispell-local-dictionary: "american"
160 // compile-command: "scons -u doc"