Example.dox

   1 /** \page example Sniffer: A simple example application
   2
   3     \dontinclude Sniffer.cc
   4
   5     The Sniffer application is a simple command line network sniffer
   6     like \c tcpdump or \c tethereal. The application uses a packet
   7     socket to read Ethernet packets from the \c eth0 interface and
   8     dumps the parsed packets out to the standard output.
   9
  10     We will be looking at \c Sniffer.cc in the \c Sniffer
  11     directory. We start by including the necessary headers
  12
  13     \skip // Custom includes
  14     \until Ethernet
  15
  16     (The additional includes are part of a short-time fix which will
  17     be removed as soon as possible). The example application now
  18     contains a helper routine to produce a packet hexdump. We will
  19     skip this routine here and go directly to the \c main function
  20
  21     \skip main
  22     \until try
  23
  24     We catch all exceptions in a \c try block. This is good for a
  25     deliverable binary. When debugging the application, it might be
  26     better to let the exception \c abort the execution so you can get
  27     a backtrace of the exception origin in the debugger.
  28
  29     We now create a packet socket and bind it to the \c eth0
  30     interface. By uncommenting the last line, you may switch the
  31     interface into promiscuous mode.
  32
  33     \until //
  34
  35     We will now read packets from the socket forever, that is until
  36     the user hits Ctrl-C
  37
  38     \skip while
  39     \until read
  40
  41     The next step is, to parse the data read from the socket as an
  42     Ethernet packet
  43
  44     \until ;
  45
  46     Lets digest this line step by step: We declare a variable named \c
  47     packet as a smart pointer to an \c EthernetPacket instance. \c ptr
  48     is a typedef member of all Packet classes for the corresponding
  49     smart pointer type. We then initialize this pointer with a call to
  50     the static \c create member of the \c Packet class. This member
  51     takes the type of Packet to parse as a template argument. We pass
  52     \c EthernetPacket here. The function takes an iterator range as an
  53     argument, and we pass it the complete packet just read by
  54     giving the range \c begin() to \c end() of our just read \c data
  55     string.
  56
  57     The next step is, to write out the packet to the standard output
  58
  59     \until \n\n
  60
  61     The \c dump call will write out a complete representation of the
  62     parsed packet data. The Packet library will \e not try to
  63     interpret payload data as long as no exact indication of the
  64     payload type is available (example: A UDP Payload is not parsed
  65     further unless you explicitly tell the library, how to parse it).
  66     Tools like \c tethereal guess the payload type by checking port
  67     numbers and the payload data, however this is not advisable for a
  68     general purpose packet library.
  69
  70     The next line, \c hexdump, will write out the \e last packet
  71     component. Packets are managed as a chain of headers. The last
  72     header is normally a \c DataPacket holding the payload data.
  73
  74     That's it. We finish of by catching the exception and giving as
  75     much detail as possible if an exception is caught
  76
  77     \until ;
  78     \until }
  79     \until }
  80
  81     The \c prettyName function from the \c Utils library is used, to
  82     get a nice, printable representation of the \e dynamic type of the
  83     exception instance. It is an interface to the g++ demangler. This
  84     is necessary since the \c name member of the C++ \c type_info
  85     instance is a mangled name in C++.
  86
  87     That's it. This is all, that's necessary to read and parse raw
  88     network packets using the SENF library. To try out the example
  89     application, check out the library, go to the \c Sniffer directory
  90     and execute
  91
  92     <pre>
  93     # scons -u
  94     # ./Sniffer
  95     </pre>
  96
  97     \see \ref components \n
  98          \ref build \n
  99          <a href="../../Socket/doc/html/index.html"><b>libSocket API reference</b></a> \n
 100          <a href="../../Packets/doc/html/index.html"><b>libPackets API reference</b></a> \n
 101          <a href="../../Utils/doc/html/index.html"><b>libUtils API reference</b></a>
 102  */
 103
 104 \f
 105 // Local Variables:
 106 // mode: c++
 107 // fill-column: 100
 108 // c-file-style: "senf"
 109 // indent-tabs-mode: nil
 110 // ispell-local-dictionary: "american"
 111 // mode: flyspell
 112 // mode: auto-fill
 113 // End: