X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Packets%2FMainpage.dox;h=889aa5f43f5667697e059ef0a259477637b555da;hb=8f1a688cea76f2e76bfa0193dff9c1538929147e;hp=f5416601f96483ab6af6cdb1fb1d1cd605095219;hpb=32573fc81844083b2aa02d3d224e4cb327de0d9d;p=senf.git

diff --git a/Packets/Mainpage.dox b/Packets/Mainpage.dox
index f541660..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 <g0dil@berlios.de>
+//
+// 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
@@ -35,7 +57,7 @@
 
     \code
     senf::EthernetPacket eth      (senf::EthernetPacket::create());
-    senf::IpV4Packet     ip       (senf::IpV4Packet    ::createAfter(ethernet));
+    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!")));
@@ -57,12 +79,12 @@
     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");
+    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 <tt>-></tt> operator whereas other packet
@@ -80,29 +102,30 @@
 
     \code
     eth.next() == ip;                   // true
-    eth.next().is<IpV4Packet>();        // true
+    eth.next().is<IPv4Packet>();        // true
     eth.next().next() == udp;           // true
     eth.next().is<UDPPacket>();         // false
-    eth.next<UDPPacket>() == udp;       // true
+    eth.find<UDPPacket>() == udp;       // true
 
-    udp.next<UDPPacket>();              // throws InvalidPacketChainException
-    udp.next<UDPPacket>(senf::nothrow); // a senf::Packet testing as false
-    udp.findNext<UDPPacket()> == udp;   // true
-    udp.first<IpV4Packet>() == ip;      // true
+    udp.find<EthernetPacket>();         // throws InvalidPacketChainException
+    udp.find<EthernetPacket>(senf::nothrow); // An in-valid() senf::Packet which tests as 'false'
+    udp.find<UDPPacket()> == udp;       // true
+    udp.first<IPv4Packet>();            // throws InvalidPacketChainException
 
     udp.prev() == ip;                   // true
-    udp.prev<EthernetPacket>() == eth   // true
+    udp.prev<EthernetPacket>();         // 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));
+    senf::EthernetPacket packet (senf::EthernetPacket::create(senf::noinit));
     sock.read(packet.data(),0u);
     \endcode
 
@@ -111,17 +134,20 @@
 
     \code
     try {
-        senf::UDPPacket udp (packet.findNext<UDPPacket>(senf::nothrow));
-        if (udp && udp->destination() == 2001u) {
+        senf::UDPPacket udp (packet.find<UDPPacket>());
+        if (udp->destination() == 2001u) {
             // Voila ...
         }
-    } catch (senf::TruncatedPacketException const &) {
-        std::cerr << "Ooops !! Broken packet received ...\n"
+    } 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 <tt>udp->destination()</tt> 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