X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Examples%2FSniffer%2FMainpage.dox;h=e7526bbf631f51a3f5da4be9951f394cc35ae39c;hb=99c145da3884f5c20a74337927ef2cbc073d80d7;hp=3e0159dc28cae8906ff3f9e94ccc31d4fb3f9852;hpb=1aa319962e09f32d2dfd612ca1854e8d85e443ba;p=senf.git
diff --git a/Examples/Sniffer/Mainpage.dox b/Examples/Sniffer/Mainpage.dox
index 3e0159d..e7526bb 100644
--- a/Examples/Sniffer/Mainpage.dox
+++ b/Examples/Sniffer/Mainpage.dox
@@ -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,15 +39,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 +72,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 +88,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 +123,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 +167,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 +189,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: