X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Examples%2FSniffer%2FMainpage.dox;h=21946b65aed1bd0a8a31c5b6bfb80b06ffb19c78;hb=ab7ff164ab5ae711ec09ce2b24228510f1ffdcff;hp=3e0159dc28cae8906ff3f9e94ccc31d4fb3f9852;hpb=1aa319962e09f32d2dfd612ca1854e8d85e443ba;p=senf.git diff --git a/Examples/Sniffer/Mainpage.dox b/Examples/Sniffer/Mainpage.dox index 3e0159d..21946b6 100644 --- a/Examples/Sniffer/Mainpage.dox +++ b/Examples/Sniffer/Mainpage.dox @@ -2,23 +2,28 @@ // // 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. +// The contents of this file are subject to the Fraunhofer FOKUS Public License +// Version 1.0 (the "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// http://senf.berlios.de/license.html // -// 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. +// The Fraunhofer FOKUS Public License Version 1.0 is based on, +// but modifies the Mozilla Public License Version 1.1. +// See the full license text for the amendments. // -// 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. +// Software distributed under the License is distributed on an "AS IS" basis, +// WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License +// for the specific language governing rights and limitations under the License. +// +// The Original Code is Fraunhofer FOKUS code. +// +// The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V. +// (registered association), Hansastraße 27 c, 80686 Munich, Germany. +// +// Contributor(s): +// Stefan Bund + /** \mainpage Simple packet sniffer reading and dumping raw network packets @@ -28,7 +33,7 @@ tethereal. The application uses a packet socket to read Ethernet packets from the \c eth0 interface and dumps the parsed packets out to the standard output. - To try out the example application, check out the library, go to the \c Sniffer + To try out the example application, check out the library, go to the \c %Sniffer directory and execute 
@@ -39,15 +44,15 @@
     < Hit Ctrl-C when you've seen enough >
- We will now look at the code which is found in \c Sniffer.cc in the \c Sniffer directory. The - code starts out by including the necessary headers + We will now look at the code which is found in \c Sniffer.cc in the Examples/%Sniffer + directory. The code starts out by including the necessary headers \skip // Custom includes \until #include The example includes two implementations, one using blocking calls and a while loop, the other - using the senf::Scheduler for asynchronous event notification. They are implemented in - \c loop_main() and \c scheduler_main(). They will be documented below. For now, we skip these + using the senf::Scheduler for asynchronous event notification. They are implemented in + \c loop_main() and \c scheduler_main(). They will be documented below. For now, we skip these implementations and go straight to the \c main() function \skip int main( @@ -72,9 +77,10 @@ the application, it might be better to let the exception \c abort the execution so you can get a backtrace of the exception origin in the debugger. - We now create a packet socket and bind it to the interface given as second command line argument. - A packet socket is a linux specific type of socket which returns ethernet packets directly from - the network wire. By uncommenting the last line, you may switch the interface into promiscuous mode. + We create a packet socket and bind it to the interface given as second command line argument. A + packet socket is a linux specific type of socket which returns ethernet packets directly from + the network wire. By uncommenting the last line, you may switch the interface into promiscuous + mode. \until // @@ -87,15 +93,17 @@ \until sock.read - \doc the following section is obsolete! - - Lets digest this line step by step: We declare a variable named \c packet as a smart pointer to - an \c EthernetPacket instance. \c ptr is a typedef member of all Packet classes for the - corresponding smart pointer type. We then initialize this pointer with a call to the static \c - create member of the \c Packet class. This member takes the type of Packet to parse as a - template argument. We pass \c EthernetPacket here. The function takes an iterator range as an - argument, and we pass it the complete packet just read by giving the range \c begin() to \c - end() of our just read \c data string. + There are several ways to read and parse a packet with different tradeoffs between efficiency + and simplicity. The Version we use here is already quite efficient. + + We begin by pre-declaring an uninitialized senf::EthernetPacket instance. By uninitialized we + mean, that the instance is not parseable and has a length of 0 bytes. This differs from a + default-constructed packet instance which may have initial content and \e is parseable. + + We then tell the socket to read as much data as is available into the packet. The second arg to + read specifies the maximum number of bytes to read or 0 to read as much as possible. We pass + packet.data() to socket.read which is an STL compatible container holding the + data bytes of our previously created senf::EthernetPacket instance (which is currently empty). The next step is to write out the packet to the standard output @@ -120,45 +128,43 @@ The \c prettyName function from the \c Utils library is used, to get a nice, printable representation of the \e dynamic type of the exception instance. It is an interface to the g++ - demangler. This is necessary since the \c name member of the C++ \c type_info instance is a + de-mangler. This is necessary since the \c name member of the C++ \c type_info instance is a mangled name in \c g++. That's it for the simple blocking implementation. \section example_scheduler Using the Scheduler - However, we have another one which uses the Scheduler. We do this as it will be most of the - time: We define a class which manages reading the packets and dumping them out. + However, we have another one which uses the Scheduler. \until } - The class constructor binds the socket defined as a data member to the correct interface. - - \until add - - The public \c run() member is called to run the sniffer. It first adds the socket to the - Scheduler. The \c add() call takes two Arguments, the socket to bind to (which can be a lot of - things and must not necessarily be a socket instance) and callback to call, whenever there is an - event on that socket. A third argument may be specified to restrict the events, on which the - function is called, here we have left out this argument which defaults to - senf::Scheduler::EV_ALL. + The class constructor binds the socket defined as a data member to the correct interface. To + tell the scheduler to call us back whenever data is available on the socket, we add a + senf::scheduler::FdEvent instance to out class. - The callback is specified as a Boost.Function object. We use the \c - senf::membind helper from the Utils library to build such a function object. This helper takes - an arbitrary class member and binds it to a specific instance. + The senf::scheduler::FdEvent constructor takes several arguments: + \li a string describing the event. + \li the callback to call whenever the event occurs. The callback is specified as a Boost.Function + object. We use the \c senf::membind helper from the Utils library to build such a + function object. This helper takes an arbitrary class member and binds it to a specific + instance. + \li the handle or file descriptor to monitor. + \li and the events to watch for. \until } - Calling the Schedulers \c process() method will start the event loop. This call does not return - (ok, it does return in special cases if \c senf::Scheduler::terminate() is called which does not - apply here). + The public \c run() member is called to run the sniffer. Here we just forward the call to the + scheduler. Calling the Schedulers \c process() method will start the event loop. This call does + not return (ok, that's a lie. It does return when \c senf::scheduler::terminate() is called + which does not apply here). \until { The \c dumpPacket() member is called by the scheduler whenever an event on the socket is - encountered. The scheduler always passes two arguments: The socket and an event id which - identifies the type of event which triggered the call. + encountered. The scheduler calls this function with a mask of the events which triggered the + call. \until }; @@ -166,19 +172,18 @@ implementation. However, the scheduler guarantees, that a read on the socket will not block if the socket is triggered to be readable (even if the socket is not set to non-blocking mode). - We now only need to provide the \c scheduler_main() function to run this code + What's left is the \c scheduler_main() function to utilize this code \until 0; \until } - This function is straight forward. The exception handling is the same as in \c loop_main(). The - code then just creates a \c Sniffer instance and calls it's \c run() member. + This function is straight forward. The exception handling is the same as in \c loop_main(). \see \ref senf_components \n \ref senf_build \n - libSocket API reference \n - libPackets API reference \n - libUtils API reference + libSocket API reference \n + libPackets API reference \n + libUtils API reference */ @@ -189,7 +194,6 @@ // c-file-style: "senf" // indent-tabs-mode: nil // ispell-local-dictionary: "american" -// compile-command: "scons -u test" -// mode: flyspell +// compile-command: "scons -u doc" // mode: auto-fill // End: