X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Socket%2FClientSocketHandle.hh;h=49eafe9afffd23125151e690dba074d719dd1eb6;hb=15c5e1939d77dfea97da38df7526bcb84a53460b;hp=0e670ab45e57de1446dd2b3be426c129fcd25cb1;hpb=c52cd7d87dbb525c1267aad27391b8b7365dbb57;p=senf.git

diff --git a/Socket/ClientSocketHandle.hh b/Socket/ClientSocketHandle.hh
index 0e670ab..49eafe9 100644
--- a/Socket/ClientSocketHandle.hh
+++ b/Socket/ClientSocketHandle.hh
@@ -20,8 +20,9 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
-// TODO: Move all not template-parameter dependent code into a
-// non-template base class
+/** \file
+    \brief senf::ClientSocketHandle public header
+ */
 
 #ifndef HH_ClientSocketHandle_
 #define HH_ClientSocketHandle_ 1
@@ -33,12 +34,68 @@
 //#include "ClientSocketHandle.mpp"
 ///////////////////////////////hh.p////////////////////////////////////////
 
-namespace satcom {
-namespace lib {
-
+namespace senf {
+    
+    /// \addtogroup handle_group
+    /// @{
+    
     template <class Policy> class ServerSocketHandle;
 
-    /** \brief
+    /** \brief Generic SocketHandle with client interface
+	
+	This class provides the client side policy interface of the
+	socket abstraction. ClientSocketHandle defines the complete
+	policy interface. It does not implement any functionality
+	itself however. All calls are forward to the following policy
+	classes:
+
+	<table class="senf">
+	<tr><th>ClientSocketHandle member</th> <th>Policy member</th></tr>
+	<tr><td>read()</td>       <td>ReadPolicy::read (\ref senf::ReadPolicyBase)</td></tr>
+	<tr><td>readfrom()</td>   <td>ReadPolicy::readfrom (\ref senf::ReadPolicyBase)</td></tr>
+	<tr><td>write()</td>      <td>WritePolicy::write (\ref senf::WritePolicyBase)</td></tr>
+	<tr><td>writeto()</td>    <td>WritePolicy::writeto (\ref senf::WritePolicyBase)</td></tr>
+	<tr><td>connect()</td>    <td>AddressingPolicy::connect (\ref senf::AddressingPolicyBase)</td></tr>
+	<tr><td>bind()</td>       <td>AddressingPolicy::bind (\ref senf::AddressingPolicyBase)</td></tr>
+	<tr><td>peer()</td>       <td>AddressingPolicy::peer (\ref senf::AddressingPolicyBase)</td></tr>
+	<tr><td>local()</td>      <td>AddressingPolicy::local (\ref senf::AddressingPolicyBase)</td></tr>
+	<tr><td>rcvbuf()</td>     <td>BufferingPolicy::sndbuf (\ref senf::BufferingPolicyBase)</td></tr>
+	<tr><td>sndbuf()</td>     <td>BufferingPolicy::rcvbuf (\ref senf::BufferingPolicyBase)</td></tr>
+	</table>
+
+	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 depending 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 active members in the leaf protocol
+	class documentation.
+
+	\todo Move all not template-parameter dependent code into a
+	non-template base class
+
+	\idea Give SocketHandle (and therefore ClientSocketHandle and
+	ServerSocketHandle) a \c protocol() template member and an
+	additional template arg \c Policies. This arg should be a
+	typelist of Poclicy classes which can be accessed. You use
+	protocol<ProtocolClass>() to access a protocol class. \c
+	Policies can of course be underspecified or even empty.
+
+	\idea add more flexible read/write members for a)
+	boost::arrays and arrays of other types b) std::vector (which
+	uses contiguous memory ..) c) other random-access containers
+	(we should use some configurable trait class to identify
+	containers with contiguous storage). Probably we should just
+	use a generic Boost.Range interface. Here we again come to the
+	point: make all except the most basic members be non-member
+	algorithms ? this would make the configuration of such
+	extenden members more flexible.
+
+	\see \ref policy_group
+             \ref protocol_group
       */
     template <class Policy>
     class ClientSocketHandle
@@ -74,12 +131,12 @@ namespace lib {
         ///////////////////////////////////////////////////////////////////////////
 
         ///////////////////////////////////////////////////////////////////////////
-        ///\name reading and writing
+        ///\name Reading and Writing
         ///@{
 
         // read from socket (connected or unconnected)
-        std::string  read         ();
-        void         read         (std::string & buffer);
+        std::string  read         (unsigned limit=0);
+        void         read         (std::string & buffer, unsigned limit=0);
         unsigned     read         (char * buffer, unsigned size);
 
         // read from unconnected socket returning peer address
@@ -138,10 +195,11 @@ namespace lib {
     private:
         unsigned available();
 
-        friend class satcom::lib::ServerSocketHandle<Policy>;
+        friend class senf::ServerSocketHandle<Policy>;
     };
 
-}}
+    /// @}
+}
 
 ///////////////////////////////hh.e////////////////////////////////////////
 //#include "ClientSocketHandle.cci"
@@ -152,5 +210,5 @@ namespace lib {
 
 // Local Variables:
 // mode: c++
-// c-file-style: "satcom"
+// c-file-style: "senf"
 // End: