Packets: Fix VariantParser invalid parser access bug

[senf.git] / Socket / ProtocolClientSocketHandle.hh

diff --git a/Socket/ProtocolClientSocketHandle.hh b/Socket/ProtocolClientSocketHandle.hh
index eeca1e7..835733e 100644 (file)
--- a/Socket/ProtocolClientSocketHandle.hh
+++ b/Socket/ProtocolClientSocketHandle.hh
@@ -1,9 +1,9 @@
 // $Id$
 //
-// Copyright (C) 2006 
-// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
-// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
-//     Stefan Bund <stefan.bund@fokus.fraunhofer.de>
+// Copyright (C) 2006
+// 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
 // it under the terms of the GNU General Public License as published by
@@ -20,21 +20,43 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
-#ifndef HH_ProtocolClientSocketHandle_
-#define HH_ProtocolClientSocketHandle_ 1
+/** \file
+    \brief ProtocolClientSocketHandle public header
+ */
+
+#ifndef HH_SENF_Socket_ProtocolClientSocketHandle_
+#define HH_SENF_Socket_ProtocolClientSocketHandle_ 1
 
 // Custom includes
 #include "ClientSocketHandle.hh"
+#include "../config.hh"
+#include "../Utils/Tags.hh"
 
 #include "ProtocolClientSocketHandle.mpp"
 ///////////////////////////////hh.p////////////////////////////////////////
 
-namespace satcom {
-namespace lib {
+namespace senf {
+
+    /// \addtogroup handle_group
+    /// @{
 
     template <class Protocol> class ProtocolServerSocketHandle;
 
-    /** \brief
+    /** \brief Protocol specific socket handle (client interface)
+
+        The ProtocolClientSocketHandle is the client interface leaf class of the handle
+        hierarchy. This is the class to instantiate to open a new socket. This is also the \e only
+        class, which can be used to open a client socket.
+
+        The \a Protocol template argument defines the protocol of the socket. This protocol provides
+        the protocol interface of the socket as well as the complete socket policy of this protocol.
+
+        The ProtocolClientSocketHandle adds the protocol interface as an additional interface to the
+        socket handle. This interface is only accessible via the protocol class. All socket
+        functionality not available through the policy interface (see ClientSocketHandle) is
+        accessible via the protocol() member.
+
+        \see \ref protocol_group
       */
     template <class SocketProtocol>
     class ProtocolClientSocketHandle
@@ -44,21 +66,45 @@ namespace lib {
         ///////////////////////////////////////////////////////////////////////////
         // Types
 
-        typedef SocketProtocol Protocol;
+        typedef SocketProtocol Protocol; ///< The sockets protocol
 
         ///////////////////////////////////////////////////////////////////////////
         ///\name Structors and default members
         ///@{
 
+        /** \brief Create new client socket
+
+            This constructor is one of the possible constructors. The exact Signature of the
+            constructor (or constructors) is defined by the \c init_client() member (or members) of
+            the \a Protocol class. ProtocolClientSocketHandle defines a number of constructors
+            taking up to 9 arguments which just forward to a corresponding \a Protocol\c
+            ::init_client() member. See the documentation of the respective Protocol class for a
+            detailed documentation of that protocols constructors.
+         */
         ProtocolClientSocketHandle();
 
-#       define BOOST_PP_ITERATION_PARAMS_1 (4, (1, 9, "Socket/ProtocolClientSocketHandle.mpp", 1))
+#       define BOOST_PP_ITERATION_PARAMS_1 (4, (1, 9, SENF_ABSOLUTE_INCLUDE_PATH(Socket/ProtocolClientSocketHandle.mpp), 1))
 #       include BOOST_PP_ITERATE()
-        
+
+        /** \brief Create uninitialized socket variable
+
+            This special constructor is called when passing
+            ProtocolClientSocketHandle::Uninitialized as only argument to the constructor. This will
+            create an in-\ref valid() socket handle which can however be assigned later with another
+            socket instance.
+
+            \implementation The socket handle will have no \c body allocated.
+         */
+        ProtocolClientSocketHandle(senf::NoInit_t);
+
         ///@}
         ///////////////////////////////////////////////////////////////////////////
 
-        Protocol const & protocol();
+        Protocol const & protocol();    ///< Access the protocol interface
+                                        /**< The returned protocol class reference gives access to
+                                           the complete protocol interface as defined by that
+                                           class. See the respective protocol class documentation.
+                                           \returns \a Protocol class reference */
 
         static ProtocolClientSocketHandle cast_static(FileHandle handle);
         static ProtocolClientSocketHandle cast_dynamic(FileHandle handle);
@@ -73,7 +119,8 @@ namespace lib {
         friend class ProtocolServerSocketHandle<Protocol>;
     };
 
-}}
+    /// @}
+}
 
 ///////////////////////////////hh.e////////////////////////////////////////
 //#include "ProtocolClientSocketHandle.cci"
@@ -85,5 +132,10 @@ namespace lib {
 \f
 // Local Variables:
 // mode: c++
-// c-file-style: "satcom"
+// fill-column: 100
+// c-file-style: "senf"
+// indent-tabs-mode: nil
+// ispell-local-dictionary: "american"
+// compile-command: "scons -u test"
+// comment-column: 40
 // End: