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 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:
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!")));
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.
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
41 The packet created above already has the correct payload however all protocol fields are
42 empty. We need to set those protocol fields:
45 udp->source() = 2000u;
46 udp->destination() = 2001u;
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");
53 eth.finalize(); // (*)
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
63 senf::PacketSocketHandle sock ("eth0");
64 sock.write(eth.data());
67 The packet library also provides lot's of facilities to navigate the packet chain:
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
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
81 udp.prev() == ip; // true
82 udp.prev<EthernetPacket>() == eth // true
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.
88 These chain navigation functions are also used to parse a packet. Let's read an Ethernet packet
89 from a packet socket handle:
92 senf::PacketSocketHandle sock ("eth0");
93 senf::EthernetPacket packet (senf::EthernetPacket::create(senf::Packet::noinit));
94 sock.read(packet.data(),0u);
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:
102 senf::UDPPacket udp (packet.findNext<UDPPacket>(senf::nothrow));
103 if (udp && udp->destination() == 2001u) {
106 } catch (senf::TruncatedPacketException const &) {
107 std::cerr << "Ooops !! Broken packet received ...\n"
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.
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.
123 // c-file-style: "senf"
124 // indent-tabs-mode: nil
125 // ispell-local-dictionary: "american"
127 // compile-command: "scons -u doc"
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