X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Examples%2FSniffer%2FMainpage.dox;h=bc69f29591cbc93105ab69dd514df078b8806c13;hb=ff4249b4a9c23236b2e56dcd593c91a5c58f7b75;hp=ebd3c210f225d1b4968c0b03d2df0109bc890bec;hpb=9035ae419b1dc9dc537e00d0f7ffc4b22e19422a;p=senf.git diff --git a/Examples/Sniffer/Mainpage.dox b/Examples/Sniffer/Mainpage.dox index ebd3c21..bc69f29 100644 --- a/Examples/Sniffer/Mainpage.dox +++ b/Examples/Sniffer/Mainpage.dox @@ -1,8 +1,8 @@ // $Id$ // -// Copyright (C) 2007 -// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS) -// Kompetenzzentrum fuer Satelitenkommunikation (SatCom) +// 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 @@ -20,7 +20,7 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -/** \mainpage Sniffer: A simple example application +/** \mainpage Simple packet sniffer reading and dumping raw network packets \dontinclude Sniffer.cc @@ -28,7 +28,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,19 +39,16 @@
     < 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 + 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 \skip // Custom includes - \until membind + \until #include - (The additional includes found in the source but not shown here are part of a short-time fix - which will be removed as soon as possible). The example application now contains a helper - routine to produce a packet hexdump. We will skip this routine here. 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 implementations and go - straight to the \c main() function + 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 + implementations and go straight to the \c main() function \skip int main( \until return 1; @@ -75,20 +72,22 @@ 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 \c eth0 interface. 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 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. \until // We will now read packets from the socket forever, that is until the user hits Ctrl-C \skip while - \until read + \until while The next step is, to parse the data read from the socket as an Ethernet packet - \until ; + \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 @@ -123,8 +122,8 @@ 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 mangled name in \c g++. - - That's it for the simple blocking implementation. + + That's it for the simple blocking implementation. \section example_scheduler Using the Scheduler @@ -133,33 +132,31 @@ \until } - The class constructor binds the socket defined as a data member to the correct interface. + 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 isntance to out class. - \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 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, it does return in special cases if \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 }; @@ -175,8 +172,8 @@ 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. - \see \ref components \n - \ref build \n + \see \ref senf_components \n + \ref senf_build \n libSocket API reference \n libPackets API reference \n libUtils API reference @@ -190,7 +187,7 @@ // c-file-style: "senf" // indent-tabs-mode: nil // ispell-local-dictionary: "american" -// compile-command: "scons -u test" +// compile-command: "scons -u doc" // mode: flyspell // mode: auto-fill // End: