4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
6 // Stefan Bund <g0dil@berlios.de>
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.
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.
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.
23 /** \mainpage The SENF Packet Library
25 \section arch Overall Architecture
27 The Packet library consists of several components:
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.
36 All these components work together to provide a hopefully simple and intuitive interface to
37 packet parsing and creation.
39 \section intro Introduction
41 Whenever using the library, you will probably need to \c \#include it's header:
44 #include "Packets/Packets.hh"
47 \warning Never include any other Packets library header directly, always include \c
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.
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:
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!")));
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.
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
75 The packet created above already has the correct payload however all protocol fields are
76 empty. We need to set those protocol fields:
79 udp->source() = 2000u;
80 udp->destination() = 2001u;
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");
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
97 senf::PacketSocketHandle sock ("eth0");
98 sock.write(eth.data());
101 The packet library also provides lot's of facilities to navigate the packet chain:
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
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
115 udp.prev() == ip; // true
116 udp.prev<EthernetPacket>(); // throws Inv
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
123 These chain navigation functions are also used to parse a packet. Let's read an Ethernet packet
124 from a packet socket handle:
127 senf::PacketSocketHandle sock ("eth0");
128 senf::EthernetPacket packet (senf::EthernetPacket::create(senf::noinit));
129 sock.read(packet.data(),0u);
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:
137 senf::UDPPacket udp (packet.find<UDPPacket>());
138 if (udp->destination() == 2001u) {
141 } catch (senf::TruncatedPacketException &) {
142 std::cerr << "Ooops !! Broken packet received\n";
143 } catch (senf::InvalidPacketChainException &) {
144 std::cerr << "Not a udp packet\n";
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.
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.
157 /** \defgroup protocolbundles Protocol Bundles
159 Each protocol bundle provides a collection of related concrete packet classes for a group of
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
167 There are two ways to link with a bundle
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
182 // c-file-style: "senf"
183 // indent-tabs-mode: nil
184 // ispell-local-dictionary: "american"
186 // compile-command: "scons -u doc"