X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Socket%2FServerSocketHandle.hh;h=9875737755630f92d21bd23468f26b66b94bb63d;hb=a8a6c2992968ee32cbc0244851e25b57a03a323a;hp=40ce4bb85d5868ec28983c210ad1b1443733a6fb;hpb=15c5e1939d77dfea97da38df7526bcb84a53460b;p=senf.git

diff --git a/Socket/ServerSocketHandle.hh b/Socket/ServerSocketHandle.hh
index 40ce4bb..9875737 100644
--- a/Socket/ServerSocketHandle.hh
+++ b/Socket/ServerSocketHandle.hh
@@ -20,6 +20,10 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
+/** \file
+    \brief ServerSocketHandle public header
+ */
+
 #ifndef HH_ServerSocketHandle_
 #define HH_ServerSocketHandle_ 1
 
@@ -40,16 +44,33 @@ namespace senf {
 
     template <class Policy> class ClientSocketHandle;
 
-    /** \brief
+    /** \brief Generic SocketHandle with server interface
+
+	This class provides the server side policy interface of the socket abstraction.
+	ServerSocketHandle defines the complete policy interface. It does not implement any
+	functionality itself however. All calls are forwarded to the following policy classes:
 
-	<table>
+	<table class="senf">
 	<tr><td>senf::ServerSocketHandle::bind</td>       <td>AddressingPolicy::bind (\ref senf::AddressingPolicyBase)</td></tr>
 	<tr><td>senf::ServerSocketHandle::listen</td>     <td>CommunicationPolicy::listen (\ref senf::CommunicationPolicyBase)</td></tr>
 	<tr><td>senf::ServerSocketHandle::local</td>      <td>AddressingPolicy::local (\ref senf::AddressingPolicyBase)</td></tr>
 	<tr><td>senf::ServerSocketHandle::accept</td>     <td>CommunicationPolicy::accept (\ref senf::CommunicationPolicyBase)</td></tr>
 	<tr><td>senf::ServerSocketHandle::acceptfrom</td> <td>CommunicationPolicy::accept (\ref senf::CommunicationPolicyBase)</td></tr>
 	</table>
-	
+
+	A ServerSocketHandle is only meaningful for connection oriented addressable protocols
+	(CommunicationPolicy is ConnectedCommunicationPolicy and AddressingPolicy is not
+	NoAddressingPolicy).
+
+	It is important to note, that not all members are always accessible. Which are depends on
+	the \c Policy template argument. If any of the policy axis is left unspecified the
+	corresponding members will not be callable (you will get a compile time error). Even if
+	every policy axis is defined, some members might (and will) not exist if they are
+	meaningless for the protocol of the socket. This depends on the exact policy.
+
+	To find out, which members are available, you have to check the documentation of the policy
+	classes. You can also find a summary of all members available in the leaf protocol class
+	documentation.
       */
     template <class Policy>
     class ServerSocketHandle
@@ -59,8 +80,15 @@ namespace senf {
         ///////////////////////////////////////////////////////////////////////////
         // Types
 
+	/// Address type from the addressing policy
         typedef typename Policy::AddressingPolicy::Address Address;
+	/// 'Best' type for passing address as parameter
+	/** Depending on the type of \c Address, this will be either <tt>Address</tt> or <tt>Address
+	    const &</tt>. See <a href="http://www.boost.org/libs/utility/call_traits.htm"
+	    class="ext">call_traits documentation in the Boost.Utility library\endlink.</a>
+	 */
         typedef typename boost::call_traits<Address>::param_type AddressParam;
+	/// Corresponding client socket handle with the same policy
         typedef ClientSocketHandle<Policy> ClientSocketHandle;
 
         ///////////////////////////////////////////////////////////////////////////
@@ -88,21 +116,75 @@ namespace senf {
         ///\name Server socket interface
         ///@{
 
+	/** \brief Set local address
+	    
+	    For addressable protocols (AddressingPolicy is not NoAddressingPolicy), bind() will set
+	    the local address of the socket.
+
+	    \parm[in] addr Local socket address to asign
+
+	    \throws senf::SystemException
+	 */
         void         bind         (AddressParam addr);
+
+	/** \brief Allow clients to connect to this server socket
+	   
+	    \todo This is very protocol specific, I don't want it in the policy
+		interface. Especially the backlog argument seems quite protocol specific to
+		me. However, we cannot listen() before we bind() so listen() cannot reside in the
+		constructor. We need to find a good solution here.
+
+	    \throws senf::SystemException
+	 */
+	// Possible solution: Make listen() an abstract method of the protocol interface, make the
+	// backlog parameter into a member living in the body or protocol class and set it using
+	// some accessor. Hmm ... this all seems somehow futile ...
         void         listen       (unsigned backlog=0);
 
+	/** \brief Query local address
+
+	    This member will return the address of the local socket in addressable protocols
+	    (AddressingPolicy is not NoAddressingPolicy).
+
+	    There are two Variants of this member, one will return the address by value, the other
+	    takes a reference argument to elide the copy operation.
+
+	    \throws senf::SystemException
+	 */
         Address      local        ();
         void         local        (Address & addr);
+                                        ///< Query local address
+                                        /**< \see \ref local() */
+	
+	/** \brief Accept new connection
+
+	    If the handle is non-blocking, accept will NOT block. If no connection
+	    is available to be returned, accept will return a ClientSocketHandle
+	    which is not valid()
+
+	    \throws senf::SystemException
+
+	    This variant ...
 
-        // If the handle is non-blocking, accept will NOT block. If no connection
-        // is available to be returned, accept will return a ClientSocketHandle
-        // which is not valid()
+	    \returns handle of new client connection
+	 */
         ClientSocketHandle 
                      accept       ();
         std::pair<ClientSocketHandle, Address>
-                     acceptfrom   ();
+	             acceptfrom   ();   ///< Accept new connection
+                                        /**< This variant will additionally return the remote
+					   address of the client
+					   \returns \c std::pair with client handle and client
+					   address. 
+					   \see \ref accept() */
         ClientSocketHandle
                      acceptfrom   (Address & addr);
+                                        ///< Accept new connection
+                                        /**< This variant will additionally return the remote
+					   address of the client
+					   \params[out] client address
+					   \returns handle of new client connection
+					   \see \ref accept() */
         
         ///@}
 
@@ -134,4 +216,5 @@ namespace senf {
 // Local Variables:
 // mode: c++
 // c-file-style: "senf"
+// fill-column: 100
 // End: