From: g0dil <g0dil@270642c3-0616-0410-b53a-bc976706d245>
Date: Mon, 8 Jun 2009 09:28:22 +0000 (+0000)
Subject: Utils/Console: UDPServer documentation
X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=9a4ab28bb53bc1a7719141a2263282d4cf73b258;p=senf.git

Utils/Console: UDPServer documentation

git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@1226 270642c3-0616-0410-b53a-bc976706d245
---

diff --git a/Utils/Console/Mainpage.dox b/Utils/Console/Mainpage.dox
index b46ce64..c7270dd 100644
--- a/Utils/Console/Mainpage.dox
+++ b/Utils/Console/Mainpage.dox
@@ -524,7 +524,7 @@
     \subsection console_noninteractive Non-interactive network console
 
     After a new connection is established, the console server waits a short time for data to arrive.
-    arrive. Only if nothing happens in the first 500ms, an interactive session is initialized.
+    Only if nothing happens in the first 500ms, an interactive session is initialized.
 
     By sending data immediately after opening the connection, the console is switched into
     non-interactive mode. In this mode, no prompt is displayed. In this mode, commands are \e not
@@ -549,6 +549,25 @@
 
     Commands are executed as soon as the terminating character (';', '{' or '}') is received or when
     the sending end of the connection is closed.    
+
+    \section console_udp Non-interactive UDP console
+
+    The UDP console allows to script the console tree via UDP packets. Every UDP packet must be a
+    complete command (or sequence of commands). The combined reply of all these commands will be
+    returned in a single UDP packet. This reply can be disabled or directed to a different address. 
+
+    To start a UDP server, just create an instance of the senf::console::UDPServer class
+    \code
+    senf::console::UDPServer server (senf::INet4SocketAddress("127.0.0.1:23232"));
+    \endcode
+    (Remember to enter the scheduler main-loop for processing)
+
+    Commands may then be sent to this UDP console e.g. using netcat
+    <pre>
+    $ echo "cd sys; ls" | nc6 -u --half-close localhost 23232 2>/dev/null
+    </pre>
+
+    \see senf::console::UDPServer
  */
 
 /** \defgroup console_commands Supported command types
diff --git a/Utils/Console/UDPServer.hh b/Utils/Console/UDPServer.hh
index 7ee589a..b5a91d0 100644
--- a/Utils/Console/UDPServer.hh
+++ b/Utils/Console/UDPServer.hh
@@ -40,7 +40,19 @@
 namespace senf {
 namespace console {
 
-    /** \brief
+    /** \brief UDP Console server
+
+        This class provides UDP access to the console to allow remote scripting. The UDP console
+        does support multicast operation.
+
+        Every UDP packet will be executed in a clean context: No directory groups are open/closed,
+        and the current directory is always the root directory. 
+
+        By default, the server will send command replies via UDP to the sender of the corresponding
+        incoming command. Replies may however either be completely disabled or be sent to a fixed
+        address (which may be a multicast address).
+
+        \ingroup console_access
       */
     class UDPServer
         : public boost::noncopyable
@@ -60,14 +72,18 @@ namespace console {
         ///@{
 
         explicit UDPServer(senf::INet4SocketAddress const & address);
+                                        ///< Open UDP server on \a address
         explicit UDPServer(senf::INet6SocketAddress const & address);
+                                        ///< Open UDP server on \a address
         
         ///@}
         ///////////////////////////////////////////////////////////////////////////
 
-        UDPServer & replies(bool enable);
+        UDPServer & replies(bool enable); ///< Enable or disable reply packets
         UDPServer & replies(senf::INet4SocketAddress const & address);
+                                        ///< Send replies to \a address
         UDPServer & replies(senf::INet6SocketAddress const & address);
+                                        ///< Send replies to \a address
 
         DirectoryNode & root() const;   ///< Get root node