X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Socket%2FGenericAddressingPolicy.hh;h=9094879e7bba9913a23a9146338e132b951f3576;hb=9a988902090d28007578e93bffd809f6bd913155;hp=fa7f5d193e5f3bab12d7a796fd93c9a8e5737492;hpb=ac6a813d9d99f7add4e13aff7a4bcd314d5604a6;p=senf.git

diff --git a/Socket/GenericAddressingPolicy.hh b/Socket/GenericAddressingPolicy.hh
index fa7f5d1..9094879 100644
--- a/Socket/GenericAddressingPolicy.hh
+++ b/Socket/GenericAddressingPolicy.hh
@@ -1,6 +1,6 @@
 // $Id$
 //
-// Copyright (C) 2006 
+// Copyright (C) 2006
 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
 //     Stefan Bund <stefan.bund@fokus.fraunhofer.de>
@@ -20,6 +20,10 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
+/** \file
+    \brief GenericAddressingPolicy public header
+ */
+
 #ifndef HH_GenericAddressingPolicy_
 #define HH_GenericAddressingPolicy_ 1
 
@@ -34,7 +38,13 @@
 
 namespace senf {
 
+    /// \addtogroup policy_impl_group
+    /// @{
+
+    /** \brief Non-template implementation class of GenericAddressingPolicy template
 
+        \internal
+     */
     struct GenericAddressingPolicy_Base
     {
         static void do_local(FileHandle handle, struct sockaddr * addr, unsigned len);
@@ -43,6 +53,30 @@ namespace senf {
         static void do_connect(FileHandle handle, struct sockaddr const * addr, unsigned len);
     };
 
+    /** \brief Template for generic AddressingPolicy implementation based on the BSD socket API
+
+        This template provides an implementation template to implement generic addressing policy
+        classes which rely on the standard BSD socket API for their implementation
+        (connect/bind/getsockname/getpeername).
+
+        The \a Address template parameter specifies the address type of the addressing policy. This
+        type must have two members: \c sockaddr_p() and \c sockaddr_len(). The first must return a
+        <tt>struct sockaddr *</tt> to the address, the second must return the size of the address in
+        bytes. The pointer returned by \c sockaddr_p() must be non-const if called on a non-const
+        address. <em>The underlying socket address stored at that pointer might be
+        modified</em>.
+
+        This template class is inherited into addressing policy classes via private
+        inheritance. Then the members supported by the respective addressing policy are made
+        available via \c using declarations (See INet4AddressingPolicy for an Example).
+
+        \idea We could explicitly provide open_sockaddr_p() and close_sockaddr_p()
+        members. sockaddr_p could always return a const * whereas open_sockaddr_p should return a
+        non-const pointer. The close operation would then explicitly signal, that the new value
+        should be incorporated into the class. With our current implementation, the close member
+        would be a no-op, however this should free us from using the sockaddr values as a direct
+        storage representation of the address.
+     */
     template <class Address>
     struct GenericAddressingPolicy
         : private GenericAddressingPolicy_Base
@@ -50,14 +84,35 @@ namespace senf {
         template <class Policy>
         static void peer(SocketHandle<Policy> handle, Address & addr,
                          typename IfCommunicationPolicyIs<Policy,ConnectedCommunicationPolicy>::type * = 0);
+                                        ///< Return address of remote peer on connected sockets
+                                        /**< This member is only available if the socket handles
+                                             communication policy is ConnectedCommunicationPolicy.
+
+                                             \param[in] handle socket handle to get peer address of
+                                             \param[out] addr address of remote peer */
         static void local(FileHandle handle, Address & addr);
+                                        ///< Return local of socket
+                                        /**< \param[in] handle socket handle to check
+                                             \param[out] addr local socket address */
 
         template <class Policy>
         static void connect(SocketHandle<Policy> handle, Address const & addr,
                             typename IfCommunicationPolicyIs<Policy,ConnectedCommunicationPolicy>::type * = 0);
+                                        ///< Connect to remote host
+                                        /**< This member is only available if the socket handles
+                                             communication policy is ConnectedCommunicationPolicy.
+
+                                             \param[in] handle socket handle
+                                             \param[in] addr address of remote peer to connect
+                                                 to */
         static void bind(FileHandle handle, Address const & addr);
+                                        ///< Set local socket address
+                                        /**< \param[in] handle socket handle
+                                             \param[in] addr local socket address */
     };
 
+    /// @}
+
 }
 
 ///////////////////////////////hh.e////////////////////////////////////////
@@ -70,5 +125,8 @@ namespace senf {
 
 // Local Variables:
 // mode: c++
+// fill-column: 100
 // c-file-style: "senf"
+// indent-tabs-mode: nil
+// ispell-local-dictionary: "american"
 // End: