Examples/UDPClientServer/Mainpage.dox

   1 // $Id$
   2 //
   3 // Copyright (C) 2008
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   8 // This program is free software; you can redistribute it and/or modify
   9 // it under the terms of the GNU General Public License as published by
  10 // the Free Software Foundation; either version 2 of the License, or
  11 // (at your option) any later version.
  12 //
  13 // This program is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 // GNU General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU General Public License
  19 // along with this program; if not, write to the
  20 // Free Software Foundation, Inc.,
  21 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23 /** \mainpage UDP Client/Server example application
  24
  25     \dontinclude udpServer.cc
  26
  27     This Application is a command line based client/server application, which sends some strings from
  28     client to server, where they are printed on the command line.
  29
  30     After installing the Library, the udpServer and the udpClient can be found in the
  31     senf/Example/udpServer directory and compiled with
  32
  33     <pre>
  34         # scons -u
  35         <Then you can start the client/server with>
  36
  37         # ./udpServer
  38         # ./udpClient
  39     </pre>
  40
  41     When we take a look to the code, we start with the Server:
  42     First we include the necessary headers:
  43
  44     \skip // Custom includes
  45     \until membind
  46
  47     The Scheduler will be needed because we implement a non blocking UDP Server with the %senf
  48     integrated Scheduler. The  scheduler library provides a simple yet flexible abstraction of
  49     the standard asynchronous UNIX mainloop utilizing \c select or \c poll.
  50
  51     \section UDP_serverApplication UDP server application
  52
  53     First we define a class which is responsible for opening a socket and print out the incoming
  54     data on stdout. We create a \c ::UDPv4ClientSocketHandle, which is an unconnected and
  55     uninitialized UDP (Ipv4) socket.
  56
  57     \until serverSock;
  58
  59     The constructor initialize the Server Object with a given address and port. In our case the
  60     server listens static on the loopback device with port 4243.
  61
  62     \until {}
  63
  64     The public \c run() member is called to run the sniffer. It first adds the socket to the
  65     Scheduler. The <tt> \link senf::Scheduler::add add() \endlink </tt> call takes two Arguments,
  66     the socket to bind to (which can be a lot of things and must not necessarily be a socket
  67     instance) and callback function to call, whenever there is an event on that socket.The callback
  68     is specified as a <a href="http://www.boost.org/doc/libs/release/doc/html/function.html">
  69     Boost.Function</a> object. A third argument may be specified to restrict the events, on which
  70     the function is called, here we used the EV_READ Argument, because we just want the program to
  71     read from the socket. The default argument is set to \c senf::Scheduler::EV_ALL, which allows
  72     all actions on the socket.
  73
  74     \until }
  75
  76     Calling the Schedulers <tt> \link senf::Scheduler::process process()\endlink </tt> method will
  77     start the event loop. This call does not return (ok, it does return in special cases if
  78     \c senf::Scheduler::terminate() is called which does not apply here). The Callback Function is
  79     the \c readFromClient() Function, which is declared as private here and will be called whenever
  80     an event on the socket is encountered. The scheduler passes the event ID to the function.
  81
  82     \until event)
  83
  84     In the function the data from the socket is put into a standard string and dumped out on stdout.
  85
  86     \until };
  87
  88     In the main function we need to create an Object of our Server with the loopback address and the port.
  89
  90     \until return 0;
  91
  92     That's it. We finish of by catching the exception and giving as much %detail as possible if an
  93     exception is caught. The \c prettyName function from the \c Utils library is used, to get a nice,
  94     printable representation of the dynamic type of the exception instance. It is an interface to
  95     the g++ demangler. This is necessary since the name member of the C++ \c type_info instance is
  96     a mangled name in g++.
  97
  98     \section UDP_clientApplication UDP client application
  99
 100     \dontinclude udpClient.cc
 101
 102     The client application uses the same mechanisms, but implements them in a small main function.
 103     It sends numbers as strings to the server.
 104
 105     \skip  argv[])
 106     \until return 0;
 107
 108     First a \c ::UDPv4ClientSocketHandle is created. With the function
 109     \c writeto(senf::INet4SocketAddress, string) the string s will be written to the specified
 110     address and port, which is constructed here from a  static string read from the console with the format \c IP:PORT. In this
 111     example Integers from zero to ten are send to the Server socket.
 112
 113     The exception handling is again the same as with the server application.
 114 */
 115
 116 \f
 117 // Local Variables:
 118 // mode: c++
 119 // fill-column: 100
 120 // comment-column: 40
 121 // c-file-style: "senf"
 122 // indent-tabs-mode: nil
 123 // ispell-local-dictionary: "american"
 124 // compile-command: "scons -u test"
 125 // mode: flyspell
 126 // mode: auto-fill
 127 // End: