// $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 <g0dil@berlios.de>
//
// This program is free software; you can redistribute it and/or modify
// 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
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
<pre>
< Hit Ctrl-C when you've seen enough >
</pre>
- 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 <senf/Scheduler/Scheduler.hh>
- (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;
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
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
\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 <a
- href="http://www.boost.org/doc/html/function.html">Boost.Function</a> 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 <a
+ href="http://www.boost.org/doc/libs/release/doc/html/function.html">Boost.Function</a>
+ 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 };
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
<a href="../../../../Socket/doc/html/index.html"><b>libSocket API reference</b></a> \n
<a href="../../../../Packets/doc/html/index.html"><b>libPackets API reference</b></a> \n
<a href="../../../../Utils/doc/html/index.html"><b>libUtils API reference</b></a>
// 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:
projects / senf.git / blobdiff