X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Packets%2FMainpage.dox;h=f5416601f96483ab6af6cdb1fb1d1cd605095219;hb=81ffa1c459b96dd44472bcef37e1e373934ee138;hp=d1437a746a1e726362fbea56f48d4a7cbab284f8;hpb=ef0a3583fc76292d631de6a4a5cad4a432351ac8;p=senf.git
diff --git a/Packets/Mainpage.dox b/Packets/Mainpage.dox
index d1437a7..f541660 100644
--- a/Packets/Mainpage.dox
+++ b/Packets/Mainpage.dox
@@ -15,18 +15,30 @@
packet parsing and creation.
\section intro Introduction
+
+ Whenever using the library, you will probably need to \c \#include it's header:
+
+ \code
+ #include "Packets/Packets.hh"
+ \endcode
+
+ \warning Never include any other Packets library header directly, always include \c
+ Packets/Packets.hh.
+
+ Additionally you will have to include the header files for the packet types you use, e.g. \c
+ Packets/DefaultBundle/EthernetPacket.hh etc.
Most every use of the packet library starts with some concrete packet typedef. Some fundamental
- packet typedefs are provided by \ref protocolbundle_default. The first example will build a
- complex packet: This will be an Ethernet packet containing an IPv4 UDP packet. We begin by
- building the raw packet skeleton:
+ packet types are provided by \ref protocolbundle_default. Building on those packet types, this
+ example will build a complex packet: This will be an Ethernet packet containing an IPv4 UDP
+ packet. We begin by building the raw packet skeleton:
\code
- senf::EthernetPacket eth (senf::EthernetPacket::create());
- senf::IpV4Packet ip (senf::IpV4Packet::createAfter(ethernet));
- senf::UDPPacket udp (senf::UDPPacket::createAfter(ip));
- senf::DataPacket payload (senf::DataPacket::createAfter(udp,
- std::string("Hello, world!")));
+ senf::EthernetPacket eth (senf::EthernetPacket::create());
+ senf::IpV4Packet ip (senf::IpV4Packet ::createAfter(ethernet));
+ senf::UDPPacket udp (senf::UDPPacket ::createAfter(ip));
+ senf::DataPacket payload (senf::DataPacket ::createAfter(udp,
+ std::string("Hello, world!")));
\endcode
These commands create what is called an interpreter chain. This chain consists of four
@@ -42,15 +54,15 @@
empty. We need to set those protocol fields:
\code
- udp->source() = 2000u;
- udp->destination() = 2001u;
- ip->ttl() = 255u;
- ip->source() = senf::INet4Address("192.168.0.1"); // (*)
- ip->destination() = senf::INet4Address("192.168.0.2"); // (*)
- eth->source() = senf::MACAddress("00:11:22:33:44:55");
- eth->destination() = senf::MACAddress("00:11:22:33:44:66");
+ udp->source() = 2000u;
+ udp->destination() = 2001u;
+ ip->ttl() = 255u;
+ ip->source() = senf::INet4Address("192.168.0.1"); // (*)
+ ip->destination() = senf::INet4Address("192.168.0.2"); // (*)
+ eth->source() = senf::MACAddress("00:11:22:33:44:55");
+ eth->destination() = senf::MACAddress("00:11:22:33:44:66");
- eth.finalize(); // (*)
+ eth.finalize(); // (*)
\endcode
As seen above, packet fields are accessed using the -> operator whereas other packet
@@ -60,26 +72,26 @@
checksums etc). Now the packet is ready. We may now send it out using a packet socket
\code
- senf::PacketSocketHandle sock ("eth0");
- sock.write(eth.data());
+ senf::PacketSocketHandle sock ("eth0");
+ sock.write(eth.data());
\endcode
The packet library also provides lot's of facilities to navigate the packet chain:
\code
- eth.next() == ip; // true
- eth.next().is(); // true
- eth.next().next() == udp; // true
- eth.next().is(); // false
- eth.next() == udp; // true
-
- udp.next(); // throws InvalidPacketChainException
- udp.next(senf::nothrow); // a senf::Packet testing as false
- udp.findNext == udp; // true
- udp.first() == ip; // true
-
- udp.prev() == ip; // true
- udp.prev() == eth // true
+ eth.next() == ip; // true
+ eth.next().is(); // true
+ eth.next().next() == udp; // true
+ eth.next().is(); // false
+ eth.next() == udp; // true
+
+ udp.next(); // throws InvalidPacketChainException
+ udp.next(senf::nothrow); // a senf::Packet testing as false
+ udp.findNext == udp; // true
+ udp.first() == ip; // true
+
+ udp.prev() == ip; // true
+ udp.prev() == eth // true
\endcode
... and so on. It is therefore not necessary to stash away a reference for every interpreter (as
@@ -89,23 +101,23 @@
from a packet socket handle:
\code
- senf::PacketSocketHandle sock ("eth0");
- senf::EthernetPacket packet (senf::EthernetPacket::create(senf::Packet::noinit));
- sock.read(packet.data(),0u);
+ senf::PacketSocketHandle sock ("eth0");
+ senf::EthernetPacket packet (senf::EthernetPacket::create(senf::Packet::noinit));
+ sock.read(packet.data(),0u);
\endcode
This first creates an uninitialized Ethernet packet and then reads into this packet. We can now
parse this packet. Let's find out, whether this is a UDP packet destined to port 2001:
\code
- try {
- senf::UDPPacket udp (packet.findNext(senf::nothrow));
- if (udp && udp->destination() == 2001u) {
- // Voila ...
- }
- } catch (senf::TruncatedPacketException const &) {
- std::cerr << "Ooops !! Broken packet received ...\n"
- }
+ try {
+ senf::UDPPacket udp (packet.findNext(senf::nothrow));
+ if (udp && udp->destination() == 2001u) {
+ // Voila ...
+ }
+ } catch (senf::TruncatedPacketException const &) {
+ std::cerr << "Ooops !! Broken packet received ...\n"
+ }
\endcode
TruncatedPacketException is thrown by udp->destination() if that field cannot be
@@ -116,6 +128,27 @@
a detailed discussion see the respective reference documentation.
*/
+/** \defgroup protocolbundles Protocol Bundles
+
+ Each protocol bundle provides a collection of related concrete packet classes for a group of
+ related protocols:
+
+ \li DefaultBundle: Some basic
+ default protocols: Ethernet, Ip, TCP, UDP
+ \li MPEGDVBBundle: MPEG and DVB
+ protocols
+
+ There are two ways to link with a bundle
+
+ \li If you only work with known packets which you explicitly reference you may just link with
+ the corresponding library.
+ \li If you need to parse unknown packets and want those to be parsed as complete as possible
+ without explicitly referencing the packet type, you will need to link against the combined
+ object file built for every bundle. This way, all packets defined in the bundle will be
+ included whether they are explicitly referenced or not (and they will all automatically be
+ registered).
+ */
+
// Local Variables:
// mode: c++
@@ -127,8 +160,3 @@
// compile-command: "scons -u doc"
// End:
-// LocalWords: mainpage SENF packetparser protocolbundles protocolbundle IPv4
-// LocalWords: udp endcode li senf EthernetPacket eth IpV createAfter ip std
-// LocalWords: ethernet UDPPacket DataPacket ttl INet MACAddress nothrow prev
-// LocalWords: PacketSocketHandle InvalidPacketChainException findNext noinit
-// LocalWords: tt TruncatedPacketException const cerr Ooops