X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Packets%2FMainpage.dox;h=889aa5f43f5667697e059ef0a259477637b555da;hb=8f1a688cea76f2e76bfa0193dff9c1538929147e;hp=d1437a746a1e726362fbea56f48d4a7cbab284f8;hpb=ef0a3583fc76292d631de6a4a5cad4a432351ac8;p=senf.git diff --git a/Packets/Mainpage.dox b/Packets/Mainpage.dox index d1437a7..889aa5f 100644 --- a/Packets/Mainpage.dox +++ b/Packets/Mainpage.dox @@ -1,3 +1,25 @@ +// $Id$ +// +// Copyright (C) 2007 +// Fraunhofer Institute for Open Communication Systems (FOKUS) +// Competence Center NETwork research (NET), St. Augustin, GERMANY +// Stefan Bund +// +// This program is free software; you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation; either version 2 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with this program; if not, write to the +// Free Software Foundation, Inc., +// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + /** \mainpage The SENF Packet Library \section arch Overall Architecture @@ -15,18 +37,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(eth)); + 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 +76,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::from_string("192.168.0.1"); + ip->destination() = senf::INet4Address::from_string("192.168.0.2"); + eth->source() = senf::MACAddress::from_string("00:11:22:33:44:55"); + eth->destination() = senf::MACAddress::from_string("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,62 +94,87 @@ 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.find() == udp; // true + + udp.find(); // throws InvalidPacketChainException + udp.find(senf::nothrow); // An in-valid() senf::Packet which tests as 'false' + udp.find == udp; // true + udp.first(); // throws InvalidPacketChainException + + udp.prev() == ip; // true + udp.prev(); // throws Inv \endcode - ... and so on. It is therefore not necessary to stash away a reference for every interpreter (as - each of the sub-packets are called) as long as at least one reference is available. + ... and so on. See the senf::Packet documentation for more. Using these members, the complete + chain of packet interpreters (as these sub-packets or headers are called) may be traversed from + any packet handle. These chain navigation functions are also used to parse a packet. Let's read an Ethernet packet 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::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.find()); + if (udp->destination() == 2001u) { + // Voila ... + } + } catch (senf::TruncatedPacketException &) { + std::cerr << "Ooops !! Broken packet received\n"; + } catch (senf::InvalidPacketChainException &) { + std::cerr << "Not a udp packet\n"; + } \endcode TruncatedPacketException is thrown by udp->destination() if that field cannot be - accessed. More generally, whenever a field cannot be accessed because it would be out of bounds + accessed (that is it would be beyond the data read which means we have read a truncated + packet). More generally, whenever a field cannot be accessed because it would be out of bounds of the data read, this exception is generated. This is only a very short introduction to the library to give a feel for the implementation. For 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 +186,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