From: g0dil Date: Mon, 21 Jan 2008 14:45:23 +0000 (+0000) Subject: Documentation updates X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=d04ae6002c7fa6eccaa2acdfb49b16cccdb81845;p=senf.git Documentation updates git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@631 270642c3-0616-0410-b53a-bc976706d245 --- diff --git a/PPI/Mainpage.dox b/PPI/Mainpage.dox index f4d8be7..8f4a8a8 100644 --- a/PPI/Mainpage.dox +++ b/PPI/Mainpage.dox @@ -78,8 +78,9 @@ \section ppi_packets Packets The PPI processes packets and uses the Packet - library to handle them. All packets are passed around as generic \ref senf::Packet - references, the PPI does not enforce any packet type restrictions. + library to handle them. All packets are internally passed around as generic \ref + senf::Packet references, however connectors may optionally be defined as sending or receiving + packets of a specific type only. \section ppi_modules Modules @@ -212,6 +213,9 @@ To provide this flexibility, all input connectors incorporate a packet queue. This queue is exposed to the module and allows the module to optionally process packets in batches. + Connectors take an optional template argument which allows to specify the type of packet this + connector sends or received. This template arguments defaults to \ref senf::Packet. + \see \ref senf::ppi::connector \section ppi_connections Connections diff --git a/Packets/Mainpage.dox b/Packets/Mainpage.dox index 5bff312..18a835d 100644 --- a/Packets/Mainpage.dox +++ b/Packets/Mainpage.dox @@ -105,19 +105,20 @@ eth.next().is(); // true eth.next().next() == udp; // true eth.next().is(); // false - eth.next() == udp; // true + eth.find() == 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.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() == eth // 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: @@ -133,17 +134,20 @@ \code try { - senf::UDPPacket udp (packet.findNext(senf::nothrow)); - if (udp && udp->destination() == 2001u) { + senf::UDPPacket udp (packet.find()); + 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 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 diff --git a/Socket/Handle.dia b/Socket/Handle.dia index 251f3f1..c93b3ee 100644 Binary files a/Socket/Handle.dia and b/Socket/Handle.dia differ diff --git a/Socket/Protocols/BSDSocketProtocol.hh b/Socket/Protocols/BSDSocketProtocol.hh index 988a627..5e08b59 100644 --- a/Socket/Protocols/BSDSocketProtocol.hh +++ b/Socket/Protocols/BSDSocketProtocol.hh @@ -92,18 +92,22 @@ namespace senf { \param[in] v new socket priority */ unsigned rcvbuf() const; ///< Check receive buffer size - /**< \param[in] handle socket handle to check - \returns size of receive buffer in bytes */ + /**< \returns size of receive buffer in bytes + \internal Linux doubles the buffer size internally when + changing it to cater for additional space needed by + the linux kernel. This call will therefore return + only half the value reported by the kernel. */ void rcvbuf(unsigned size) const; ///< Change receive buffer size - /**< \param[in] handle socket handle - \param[in] size new receive buffer size */ + /**< \param[in] size new receive buffer size */ unsigned sndbuf() const; ///< Check send buffer size - /**< \param[in] handle socket handle to check - \returns size of send buffer in bytes */ + /**< \returns size of send buffer in bytes + \internal Linux doubles the buffer size internally when + changing it to cater for additional space needed by + the linux kernel. This call will therefore return + only half the value reported by the kernel. */ void sndbuf(unsigned size) const; ///< Change size of send buffer - /**< \param[in] handle socket handle - \param[in] size new send buffer size */ + /**< \param[in] size new send buffer size */ }; diff --git a/Socket/SocketPolicy.dia b/Socket/SocketPolicy.dia index 56ff6e8..f768c2c 100644 Binary files a/Socket/SocketPolicy.dia and b/Socket/SocketPolicy.dia differ