From 98b8b98c5dc773dee184e2c5a2ef877601f6e990 Mon Sep 17 00:00:00 2001
From: g0dil <g0dil@wiback.org>
Date: Tue, 6 Feb 2007 16:19:56 +0000
Subject: [PATCH] Finished documentation of non protocol specific socket
library classes
---
Socket/AddressingPolicy.hh | 14 +++++
Socket/ClientSocketHandle.ct | 2 +-
Socket/ClientSocketHandle.cti | 2 +-
Socket/ClientSocketHandle.hh | 2 +-
Socket/CommunicationPolicy.cc | 4 +-
Socket/CommunicationPolicy.cti | 4 +-
Socket/CommunicationPolicy.hh | 37 +++++++++++++
Socket/FileHandle.cc | 2 +-
Socket/FileHandle.cci | 2 +-
Socket/FileHandle.hh | 2 +-
Socket/FileHandle.ih | 4 +-
Socket/FramingPolicy.hh | 24 +++++++++
Socket/GenericAddressingPolicy.cc | 4 +-
Socket/GenericAddressingPolicy.cti | 4 +-
Socket/GenericAddressingPolicy.hh | 52 ++++++++++++++++++
Socket/Mainpage.dox | 18 +++++++
Socket/PacketSocketHandle.cc | 4 +-
Socket/PacketSocketHandle.ct | 4 +-
Socket/PacketSocketHandle.cti | 4 +-
Socket/PacketSocketHandle.hh | 13 +++--
Socket/PacketSocketHandle.ih | 4 ++
Socket/ProtocolClientSocketHandle.cti | 2 +-
Socket/ProtocolClientSocketHandle.hh | 2 +-
Socket/ProtocolClientSocketHandle.mpp | 2 +-
Socket/ProtocolServerSocketHandle.cti | 2 +-
Socket/ProtocolServerSocketHandle.hh | 2 +-
Socket/ReadWritePolicy.cc | 4 +-
Socket/ReadWritePolicy.cti | 4 +-
Socket/ReadWritePolicy.hh | 61 +++++++++++++++++++++
Socket/ServerSocketHandle.cti | 2 +-
Socket/ServerSocketHandle.hh | 2 +-
Socket/SocketHandle.cc | 2 +-
Socket/SocketHandle.cci | 2 +-
Socket/SocketHandle.ct | 2 +-
Socket/SocketHandle.cti | 2 +-
Socket/SocketHandle.hh | 2 +-
Socket/SocketHandle.ih | 4 +-
Socket/SocketPolicy.hh | 8 +++
Socket/SocketProtocol.cc | 4 +-
Socket/SocketProtocol.cci | 4 +-
Socket/SocketProtocol.cti | 4 +-
Socket/SocketProtocol.hh | 1 +
Socket/TCPSocketHandle.cc | 4 +-
Socket/TCPSocketHandle.hh | 77 +++++++++++++++++++++++++--
senfscons/SENFSCons.py | 2 +-
45 files changed, 364 insertions(+), 43 deletions(-)
diff --git a/Socket/AddressingPolicy.hh b/Socket/AddressingPolicy.hh
index 238dfcb17..b932456fe 100644
--- a/Socket/AddressingPolicy.hh
+++ b/Socket/AddressingPolicy.hh
@@ -20,6 +20,10 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+/** \file
+ \brief NoAddressingPolicy public header
+ */
+
#ifndef HH_AddressingPolicy_
#define HH_AddressingPolicy_ 1
@@ -31,10 +35,20 @@
namespace senf {
+ /// \addtogroup policy_impl_group
+ /// @{
+
+ /** \brief AddressingPolicy for non-addressable sockets
+ This is different from UndefinedAddressingPolicy (which is the
+ same as AddressingPolicyBase). This policy class defines the
+ addressing -- it explicitly states, that the socket does not
+ support any addressing.
+ */
struct NoAddressingPolicy : public AddressingPolicyBase
{};
+ /// @}
}
///////////////////////////////hh.e////////////////////////////////////////
diff --git a/Socket/ClientSocketHandle.ct b/Socket/ClientSocketHandle.ct
index 9379c7c6a..33ef74be6 100644
--- a/Socket/ClientSocketHandle.ct
+++ b/Socket/ClientSocketHandle.ct
@@ -21,7 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief senf::ClientSocketHandle non-inline template implementation
+ \brief ClientSocketHandle non-inline template implementation
*/
//#include "ClientSocketHandle.ih"
diff --git a/Socket/ClientSocketHandle.cti b/Socket/ClientSocketHandle.cti
index 669aa38ff..21aea1c56 100644
--- a/Socket/ClientSocketHandle.cti
+++ b/Socket/ClientSocketHandle.cti
@@ -21,7 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief senf::ClientSocketHandle inline template implementation
+ \brief ClientSocketHandle inline template implementation
*/
//#include "ClientSocketHandle.ih"
diff --git a/Socket/ClientSocketHandle.hh b/Socket/ClientSocketHandle.hh
index 3c836a4b6..64e73724b 100644
--- a/Socket/ClientSocketHandle.hh
+++ b/Socket/ClientSocketHandle.hh
@@ -21,7 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief senf::ClientSocketHandle public header
+ \brief ClientSocketHandle public header
*/
#ifndef HH_ClientSocketHandle_
diff --git a/Socket/CommunicationPolicy.cc b/Socket/CommunicationPolicy.cc
index 816da3a77..9fef12b61 100644
--- a/Socket/CommunicationPolicy.cc
+++ b/Socket/CommunicationPolicy.cc
@@ -20,7 +20,9 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-// Definition of non-inline non-template functions
+/** \file
+ \brief CommunicationPolicy non-inline non-template implementation
+ */
#include "CommunicationPolicy.hh"
//#include "CommunicationPolicy.ih"
diff --git a/Socket/CommunicationPolicy.cti b/Socket/CommunicationPolicy.cti
index 98711da3e..50e4f7ff5 100644
--- a/Socket/CommunicationPolicy.cti
+++ b/Socket/CommunicationPolicy.cti
@@ -20,7 +20,9 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-// Definition of inline template functions
+/** \file
+ \brief CommunicationPolicy inline template implementation
+ */
//#include "CommunicationPolicy.ih"
diff --git a/Socket/CommunicationPolicy.hh b/Socket/CommunicationPolicy.hh
index 4d8cdce77..097a8bfe0 100644
--- a/Socket/CommunicationPolicy.hh
+++ b/Socket/CommunicationPolicy.hh
@@ -20,6 +20,10 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+/** \file
+ \brief CommunicationPolicy public header
+ */
+
#ifndef HH_CommunicationPolicy_
#define HH_CommunicationPolicy_ 1
@@ -35,23 +39,55 @@ struct sockaddr;
namespace senf {
+ /// \addtogroup policy_impl_group
+ /// @{
template <class Policy> class ServerSocketHandle;
+ /** \brief CommunicationPolicy for connected sockets
+
+ The ConnectedCommunicationPolicy provides support for standard BSD socket API based
+ connected communication. It provides the server side listen() and accept() members.
+ */
struct ConnectedCommunicationPolicy : public CommunicationPolicyBase
{
static void listen(FileHandle handle, unsigned backlog);
+ ///< Enable establishing new connections on the socket
+ /** \param[in] handle socket handle to enable reception on
+ \param[in] backlog size of backlog queue
+
+ \fixme listen probably makes no sense without accpept,
+ so listen() should debend on AddressingPolicy too. */
template <class Policy>
static int accept(ServerSocketHandle<Policy> handle,
typename ServerSocketHandle<Policy>::Address & address,
typename IfAddressingPolicyIsNot<Policy,NoAddressingPolicy>::type * = 0);
+ ///< accept a new connection on the socket.
+ /**< The accept() member will return a new client file
+ descriptor. This file descriptor will be used by the
+ ServerSocketHandle implementation to build a new
+ ClientSocketHandle for the new connection.
+
+ \param[in] handle socket handle to accept connection on
+ \param[out] address address of newly connected remote
+ peer
+ \returns file descriptor of new client socket */
private:
static int do_accept(FileHandle handle, struct sockaddr * addr, unsigned len);
};
+ /** \brief CommunicationPolicy for unconnected sockets
+
+ This is different from UndefinedCommunicationPolicy (which is the same as
+ CommunicationPolicyBase). This policy class defines the communication policy -- it
+ explicitly states, that the socket does not support connected communication. This
+ effektively disables ther ServerSocketHandle.
+ */
struct UnconnectedCommunicationPolicy : public CommunicationPolicyBase
{};
+ /// @}
+
}
@@ -65,4 +101,5 @@ namespace senf {
// Local Variables:
// mode: c++
// c-file-style: "senf"
+// fill-column: 100
// End:
diff --git a/Socket/FileHandle.cc b/Socket/FileHandle.cc
index c482e6db6..3e6b0237a 100644
--- a/Socket/FileHandle.cc
+++ b/Socket/FileHandle.cc
@@ -21,7 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief senf::FileHandle non-inline non-template implementation
+ \brief FileHandle non-inline non-template implementation
*/
#include "FileHandle.hh"
diff --git a/Socket/FileHandle.cci b/Socket/FileHandle.cci
index 0fc5f3e52..f66a34807 100644
--- a/Socket/FileHandle.cci
+++ b/Socket/FileHandle.cci
@@ -21,7 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief senf::FileHandle inline non-template implementation
+ \brief FileHandle inline non-template implementation
*/
//#include "FileHandle.ih"
diff --git a/Socket/FileHandle.hh b/Socket/FileHandle.hh
index 5f82eaf10..a0b2de58f 100644
--- a/Socket/FileHandle.hh
+++ b/Socket/FileHandle.hh
@@ -21,7 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief senf::FileHandle public header
+ \brief FileHandle public header
*/
/** \defgroup handle_group The Handle Hierarchy
diff --git a/Socket/FileHandle.ih b/Socket/FileHandle.ih
index 24c05283c..f79466f2d 100644
--- a/Socket/FileHandle.ih
+++ b/Socket/FileHandle.ih
@@ -21,7 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief senf::FileHandle internal header
+ \brief FileHandle internal header
*/
#ifndef IH_FileHandle_
@@ -36,7 +36,7 @@
namespace senf {
- /** \brief senf::FileHandle referenced body
+ /** \brief FileHandle referenced body
\internal
diff --git a/Socket/FramingPolicy.hh b/Socket/FramingPolicy.hh
index 97a440c26..a873239d0 100644
--- a/Socket/FramingPolicy.hh
+++ b/Socket/FramingPolicy.hh
@@ -20,6 +20,10 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+/** \file
+ \brief FramingPolicy public header
+ */
+
#ifndef HH_FramingPolicy_
#define HH_FramingPolicy_ 1
@@ -31,13 +35,33 @@
namespace senf {
+ /// \addtogroup policy_impl_group
+ /// @{
+ /** \brief FramingPolicy for stream oriented sockets
+
+ This policy does not explicitly modify the SocketHAndle
+ API. It however affects the semantics of the read and write
+ operations. On a stream oriented socket, read() and write()
+ operations may be combined, the boundary between separate
+ write() calls will be lost on the receiving side.
+ */
struct StreamFramingPolicy : public FramingPolicyBase
{};
+ /** \brief FramingPolicy for datagram oriented sockets
+
+ This policy does not explicitly modify the SocketHAndle
+ API. It however affects the semantics of the read and write
+ operations. On a datagram socket, each read() or write() call
+ we read or write a single datagram. Datagram boundaries are
+ kept intact accross the network.
+ */
struct DatagramFramingPolicy : public FramingPolicyBase
{};
+ /// @}
+
}
///////////////////////////////hh.e////////////////////////////////////////
diff --git a/Socket/GenericAddressingPolicy.cc b/Socket/GenericAddressingPolicy.cc
index a59d1746f..c9d1b6385 100644
--- a/Socket/GenericAddressingPolicy.cc
+++ b/Socket/GenericAddressingPolicy.cc
@@ -20,7 +20,9 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-// Definition of non-inline non-template functions
+/** \file
+ \brief GenericAddressingPolicy non-inline non-template implementation
+ */
#include "GenericAddressingPolicy.hh"
//#include "GenericAddressingPolicy.ih"
diff --git a/Socket/GenericAddressingPolicy.cti b/Socket/GenericAddressingPolicy.cti
index 33e6120c5..c9a050f79 100644
--- a/Socket/GenericAddressingPolicy.cti
+++ b/Socket/GenericAddressingPolicy.cti
@@ -20,7 +20,9 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-// Definition of inline template functions
+/** \file
+ \brief GenericAddressingPolicy inline template implementation
+ */
//#include "GenericAddressingPolicy.ih"
diff --git a/Socket/GenericAddressingPolicy.hh b/Socket/GenericAddressingPolicy.hh
index fa7f5d193..f4e82162b 100644
--- a/Socket/GenericAddressingPolicy.hh
+++ b/Socket/GenericAddressingPolicy.hh
@@ -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 implemenatation class of GenericAddressingPolicy template
+ \internal
+ */
struct GenericAddressingPolicy_Base
{
static void do_local(FileHandle handle, struct sockaddr * addr, unsigned len);
@@ -43,6 +53,26 @@ 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>.
+
+ \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 ould free us from using the sockaddr values as a direct
+ sotrage representation of the address.
+ */
template <class Address>
struct GenericAddressingPolicy
: private GenericAddressingPolicy_Base
@@ -50,14 +80,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] address 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////////////////////////////////////////
@@ -71,4 +122,5 @@ namespace senf {
// Local Variables:
// mode: c++
// c-file-style: "senf"
+// fill-column: 100
// End:
diff --git a/Socket/Mainpage.dox b/Socket/Mainpage.dox
index 29496dc37..2296b5d96 100644
--- a/Socket/Mainpage.dox
+++ b/Socket/Mainpage.dox
@@ -193,8 +193,26 @@ namespace senf {
*/
/** \page implementation Implementation notes
+
+ \section class_diagram Class Diagram
\image html SocketLibrary-classes.png
+
+ \section impl_notes Arbitrary Implementation Notes
+
+ \li The implementation tries to isolate the library user as much
+ as possible from the system header files since those headers
+ define a lot of define symbols and introduce a host of symbols
+ into the global namespace. This is, why some classes define
+ their own \c enum types to replace system defined define
+ constants. This also precludes inlining some functionality.
+
+ \li To reduce overhead, template functions/members which are
+ more than one-liners are often implemented in terms of a
+ non-template function/member. This is also used to further the
+ isolation from system headers as defined above (template code
+ must always be included into every compilation unit together
+ with all headers need for the implementation).
*/
}
diff --git a/Socket/PacketSocketHandle.cc b/Socket/PacketSocketHandle.cc
index b995959a1..88b841013 100644
--- a/Socket/PacketSocketHandle.cc
+++ b/Socket/PacketSocketHandle.cc
@@ -20,7 +20,9 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-// Definition of non-inline non-template functions
+/** \file
+ \brief PacketProtocol and PacketSocketHandle non-inline non-template implementation
+ */
#include "PacketSocketHandle.hh"
#include "PacketSocketHandle.ih"
diff --git a/Socket/PacketSocketHandle.ct b/Socket/PacketSocketHandle.ct
index bc2ac294d..ca002ab2f 100644
--- a/Socket/PacketSocketHandle.ct
+++ b/Socket/PacketSocketHandle.ct
@@ -20,7 +20,9 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-// Definition of non-inline template functions
+/** \file
+ \brief PacketProtocol and PacketSocketHandle non-inline template implementation
+ */
#include "PacketSocketHandle.ih"
diff --git a/Socket/PacketSocketHandle.cti b/Socket/PacketSocketHandle.cti
index c162b8ecf..f7bdd052e 100644
--- a/Socket/PacketSocketHandle.cti
+++ b/Socket/PacketSocketHandle.cti
@@ -20,7 +20,9 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-// Definition of inline template functions
+/** \file
+ \brief PacketProtocol and PacketSocketHandle inline template implementation
+ */
#include "PacketSocketHandle.ih"
diff --git a/Socket/PacketSocketHandle.hh b/Socket/PacketSocketHandle.hh
index b8748ff64..48e31d88b 100644
--- a/Socket/PacketSocketHandle.hh
+++ b/Socket/PacketSocketHandle.hh
@@ -20,6 +20,10 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+/** \file
+ \brief PacketProtocol and PacketSocketHandle public header
+ */
+
#ifndef HH_PacketSocketHandle_
#define HH_PacketSocketHandle_ 1
@@ -55,7 +59,7 @@ namespace senf {
/** \brief Raw Packet-Socket access (Linux)
\par Socket Handle typedefs:
- \ref PacketSocketHandle
+ \ref PacketSocketHandle (ProtocolClientSocketHandle)
\par Protocol Interface:
ClientSocketHandle::read(), ClientSocketHandle::readfrom(), ClientSocketHandle::writeto(),
@@ -69,8 +73,8 @@ namespace senf {
the low level network packets. The packet socket allows read() and write() operations. The
PacketProtocol has no concept of a server socket.
- \see \ref ProtocolClientSocketHandle \n
- \ref protocol_group
+ This class is utilized as the protocol class of the ProtocolClientSocketHandle via the
+ Socket Handle typedefs above.
*/
class PacketProtocol
: public ConcreteSocketProtocol<Packet_Policy>,
@@ -101,6 +105,9 @@ namespace senf {
\param[in] type socket type
\param[in] protocol IEEE 802.3 protocol number */
+ /**< \note This member is implicitly called from the
+ ProtocolClientSocketHandle::ProtocolClientSocketHandle()
+ constructor */
///@}
///\name Protocol Interface
diff --git a/Socket/PacketSocketHandle.ih b/Socket/PacketSocketHandle.ih
index 9ae920e19..62ead4035 100644
--- a/Socket/PacketSocketHandle.ih
+++ b/Socket/PacketSocketHandle.ih
@@ -20,6 +20,10 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+/** \file
+ \brief PacketProtocol and PacketSocketHandle internal header
+ */
+
#ifndef IH_PacketSocketHandle_
#define IH_PacketSocketHandle_ 1
diff --git a/Socket/ProtocolClientSocketHandle.cti b/Socket/ProtocolClientSocketHandle.cti
index 1b20fdbca..2fbc07720 100644
--- a/Socket/ProtocolClientSocketHandle.cti
+++ b/Socket/ProtocolClientSocketHandle.cti
@@ -21,7 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief senf::ProtocolClientSocketHandle inline template
+ \brief ProtocolClientSocketHandle inline template
implementation
*/
diff --git a/Socket/ProtocolClientSocketHandle.hh b/Socket/ProtocolClientSocketHandle.hh
index 43e81346d..c81dae45d 100644
--- a/Socket/ProtocolClientSocketHandle.hh
+++ b/Socket/ProtocolClientSocketHandle.hh
@@ -21,7 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief senf::ProtocolClientSocketHandle public header
+ \brief ProtocolClientSocketHandle public header
*/
#ifndef HH_ProtocolClientSocketHandle_
diff --git a/Socket/ProtocolClientSocketHandle.mpp b/Socket/ProtocolClientSocketHandle.mpp
index a7b463ac6..74231e6ea 100644
--- a/Socket/ProtocolClientSocketHandle.mpp
+++ b/Socket/ProtocolClientSocketHandle.mpp
@@ -21,7 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief senf::ProtocolClientSocketHandle Boost.Preprocessor external iteration include
+ \brief ProtocolClientSocketHandle Boost.Preprocessor external iteration include
*/
#if !BOOST_PP_IS_ITERATING && !defined(MPP_ProtocolClientSocketHandle_)
diff --git a/Socket/ProtocolServerSocketHandle.cti b/Socket/ProtocolServerSocketHandle.cti
index 2fd0720b3..e96fd2c02 100644
--- a/Socket/ProtocolServerSocketHandle.cti
+++ b/Socket/ProtocolServerSocketHandle.cti
@@ -21,7 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief senf::ProtocolServerSocketHandle inline template implementation
+ \brief ProtocolServerSocketHandle inline template implementation
*/
// Definition of inline template functions
diff --git a/Socket/ProtocolServerSocketHandle.hh b/Socket/ProtocolServerSocketHandle.hh
index a60c6c12a..a928f06a1 100644
--- a/Socket/ProtocolServerSocketHandle.hh
+++ b/Socket/ProtocolServerSocketHandle.hh
@@ -21,7 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief senf::ProtocolServerSocketHandle public header
+ \brief ProtocolServerSocketHandle public header
*/
#ifndef HH_ProtocolServerSocketHandle_
diff --git a/Socket/ReadWritePolicy.cc b/Socket/ReadWritePolicy.cc
index c441f198c..b1f280c17 100644
--- a/Socket/ReadWritePolicy.cc
+++ b/Socket/ReadWritePolicy.cc
@@ -20,7 +20,9 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-// Definition of non-inline non-template functions
+/** \file
+ \brief ReadPolicy and WritePolicy non-inline non-template implementation
+ */
#include "ReadWritePolicy.hh"
//#include "ReadWritePolicy.ih"
diff --git a/Socket/ReadWritePolicy.cti b/Socket/ReadWritePolicy.cti
index 84a378f35..d9c065de0 100644
--- a/Socket/ReadWritePolicy.cti
+++ b/Socket/ReadWritePolicy.cti
@@ -20,7 +20,9 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-// Definition of inline template functions
+/** \file
+ \brief ReadPolicy and WritePolicy inline template implementation
+ */
//#include "ReadWritePolicy.ih"
diff --git a/Socket/ReadWritePolicy.hh b/Socket/ReadWritePolicy.hh
index 644ad8792..73edd344e 100644
--- a/Socket/ReadWritePolicy.hh
+++ b/Socket/ReadWritePolicy.hh
@@ -21,6 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
+ \brief ReadPolicy and WritePolicy public header
\todo ReadWritePolicy.test.cc
*/
@@ -41,33 +42,84 @@ struct sockaddr;
namespace senf {
+ /// \addtogroup policy_impl_group
+ /// @{
+ /** \brief ReadPolicy for readable sockets
+
+ This policy provides support for readable sockets via the standard UNIX read/recvfrom system
+ cals. The concreate semantics of the read calls depend on the framing policy of the socket.
+ */
struct ReadablePolicy : public ReadPolicyBase
{
static unsigned read(FileHandle handle, char * buffer, unsigned size);
+ ///< read data from socket
+ /**< \param[in] handle socket handle to read from
+ \param[in] buffer address of buffer to write data to
+ \param[in] size size of buffer
+ \returns number of bytes read */
template <class Policy>
static unsigned readfrom(ClientSocketHandle<Policy> handle, char * buffer, unsigned size,
typename Policy::AddressingPolicy::Address & address,
typename IfCommunicationPolicyIs<Policy,UnconnectedCommunicationPolicy>::type * = 0);
+ ///< read data from socket returning peer address
+ /**< \param[in] handle socket handle to read from
+ \param[in] buffer address of buffer to write data to
+ \param[in] size size of buffer
+ \param[out] address peer address
+ \returns number of bytes read */
+*/
private:
static unsigned do_readfrom(FileHandle handle, char * buffer, unsigned size,
struct ::sockaddr * addr, socklen_t len);
};
+ /** \brief ReadPolicy for unreadable sockets
+
+ This is different from UndefinedReadPolicy (which is the same as ReadPolicyBase). This
+ policy class defines the socket readability -- it explicitly states, that the socket does
+ not support reading.
+ */
struct NotReadablePolicy : public ReadPolicyBase
{};
+ /** \brief WritePolicy for writeable sockets
+
+ This policy provides support for writable sockets via the standard UNIX write/sendto system
+ cals. The concreate semantics of the write calls depend on the framing policy of the socket.
+ */
struct WriteablePolicy : public WritePolicyBase
{
template <class Policy>
static unsigned write(ClientSocketHandle<Policy> handle, char const * buffer, unsigned size,
typename IfCommunicationPolicyIs<Policy,ConnectedCommunicationPolicy>::type * = 0);
+ ///< write data to socket
+ /**< This member is only enabled if the socket uses
+ connected communication. Otherwise the communication
+ partner must be specified explicitly using the sendto
+ call
+
+ \param[in] handle socket handle to write data to
+ \param[in] buffer address of buffer to send
+ \param[in] size number of bytes to write
+ \returns number of bytes written */
template <class Policy>
static unsigned writeto(ClientSocketHandle<Policy> handle,
typename boost::call_traits<typename Policy::AddressingPolicy::Address>::param_type addr,
char const * buffer, unsigned size,
typename IfCommunicationPolicyIs<Policy,UnconnectedCommunicationPolicy>::type * = 0);
+ ///< write data to socket sending to given peer
+ /**< This member is only enabled if the socket uses
+ unconnected communication. Otherwise no target may be
+ specified since it is implied in the connection.
+
+ \param[in] handle socket handle to write data to
+ \param[in] buffer address of buffer to send
+ \param[in] size number of bytes to write
+ \param[in] address peer to send data to
+ \returns number of bytes written
+ */
private:
static unsigned do_write(FileHandle handle, char const * buffer, unsigned size);
@@ -75,9 +127,17 @@ namespace senf {
struct sockaddr * addr, socklen_t len);
};
+ /** \brief WritePolicy for unwriteable sockets
+
+ This is different from UndefinedWritePolicy (which is the same as WritePolicyBase). This
+ policy class defines the socket writeability -- it explicitly states, that the socket does
+ not support writing.
+ */
struct NotWriteablePolicy : public WritePolicyBase
{};
+ /// @}
+
}
@@ -91,4 +151,5 @@ namespace senf {
// Local Variables:
// mode: c++
// c-file-style: "senf"
+// fill-column: 100
// End:
diff --git a/Socket/ServerSocketHandle.cti b/Socket/ServerSocketHandle.cti
index 643e477de..35299c65c 100644
--- a/Socket/ServerSocketHandle.cti
+++ b/Socket/ServerSocketHandle.cti
@@ -21,7 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief senf::ServerSocketHandle inline template implementation
+ \brief ServerSocketHandle inline template implementation
*/
// Definition of inline template functions
diff --git a/Socket/ServerSocketHandle.hh b/Socket/ServerSocketHandle.hh
index 0c58c00eb..987573775 100644
--- a/Socket/ServerSocketHandle.hh
+++ b/Socket/ServerSocketHandle.hh
@@ -21,7 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief senf::ServerSocketHandle public header
+ \brief ServerSocketHandle public header
*/
#ifndef HH_ServerSocketHandle_
diff --git a/Socket/SocketHandle.cc b/Socket/SocketHandle.cc
index 7d9281556..807639bd1 100644
--- a/Socket/SocketHandle.cc
+++ b/Socket/SocketHandle.cc
@@ -21,7 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief senf::SocketHandle non-inline non-template implementation
+ \brief SocketHandle non-inline non-template implementation
*/
#include "SocketHandle.hh"
diff --git a/Socket/SocketHandle.cci b/Socket/SocketHandle.cci
index e138ec263..c62ccb4af 100644
--- a/Socket/SocketHandle.cci
+++ b/Socket/SocketHandle.cci
@@ -21,7 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief senf::SocketHandle inline non-template implementation
+ \brief SocketHandle inline non-template implementation
*/
#include "SocketHandle.ih"
diff --git a/Socket/SocketHandle.ct b/Socket/SocketHandle.ct
index eac4a09e8..c90c6bed4 100644
--- a/Socket/SocketHandle.ct
+++ b/Socket/SocketHandle.ct
@@ -21,7 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief senf::SocketHandle non-inline template implementation
+ \brief SocketHandle non-inline template implementation
*/
#include "SocketHandle.ih"
diff --git a/Socket/SocketHandle.cti b/Socket/SocketHandle.cti
index 08a3e4db5..4d03d6768 100644
--- a/Socket/SocketHandle.cti
+++ b/Socket/SocketHandle.cti
@@ -21,7 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief senf::SocketHandle inline template implementation
+ \brief SocketHandle inline template implementation
*/
#include "SocketHandle.ih"
diff --git a/Socket/SocketHandle.hh b/Socket/SocketHandle.hh
index d8f71de39..96995915d 100644
--- a/Socket/SocketHandle.hh
+++ b/Socket/SocketHandle.hh
@@ -21,7 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief senf::SocketHandle public header
+ \brief SocketHandle public header
*/
#ifndef HH_SocketHandle_
diff --git a/Socket/SocketHandle.ih b/Socket/SocketHandle.ih
index 4c52c6597..a7ddf6105 100644
--- a/Socket/SocketHandle.ih
+++ b/Socket/SocketHandle.ih
@@ -21,7 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
- \brief senf::SocketHandle internal header
+ \brief SocketHandle internal header
*/
#ifndef IH_SocketHandle_
@@ -104,7 +104,7 @@ namespace senf {
std::string dumpState(SocketStateMap const & map);
}
- /** \brief senf::SocketHandle referenced body
+ /** \brief SocketHandle referenced body
\internal
diff --git a/Socket/SocketPolicy.hh b/Socket/SocketPolicy.hh
index c0723b0a4..db8cee50f 100644
--- a/Socket/SocketPolicy.hh
+++ b/Socket/SocketPolicy.hh
@@ -228,6 +228,14 @@
with \c SocketPolicyIsBaseOf.
*/
+/** \defgroup policy_impl_group Policy Implementation classes
+ \ingroup policy_group
+
+ Here you will find all policy classes. Also included are some
+ supporting classes which are used as base classes to build other
+ policy classes.
+ */
+
#ifndef HH_SocketPolicy_
#define HH_SocketPolicy_ 1
diff --git a/Socket/SocketProtocol.cc b/Socket/SocketProtocol.cc
index d5afd7528..354a221c0 100644
--- a/Socket/SocketProtocol.cc
+++ b/Socket/SocketProtocol.cc
@@ -20,7 +20,9 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-// Definition of non-inline non-template functions
+/** \file
+ \brief SocketProtocol and ConcreteSocketProtocol non-inline non-template implementation
+ */
#include "SocketProtocol.hh"
//#include "SocketProtocol.ih"
diff --git a/Socket/SocketProtocol.cci b/Socket/SocketProtocol.cci
index a8a848b93..0dcff103f 100644
--- a/Socket/SocketProtocol.cci
+++ b/Socket/SocketProtocol.cci
@@ -20,7 +20,9 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-// Definition of inline non-template functions
+/** \file
+ \brief SocketProtocol and ConcreteSocketProtocol inline non-template implementation
+ */
//#include "SocketProtocol.ih"
diff --git a/Socket/SocketProtocol.cti b/Socket/SocketProtocol.cti
index ff56cc193..eb9315746 100644
--- a/Socket/SocketProtocol.cti
+++ b/Socket/SocketProtocol.cti
@@ -20,7 +20,9 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-// Definition of inline template functions
+/** \file
+ \brief SocketProtocol and ConcreteSocketProtocol inline template implementation
+ */
//#include "SocketProtocol.ih"
diff --git a/Socket/SocketProtocol.hh b/Socket/SocketProtocol.hh
index 95e38e881..863dc4fd4 100644
--- a/Socket/SocketProtocol.hh
+++ b/Socket/SocketProtocol.hh
@@ -21,6 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
+ \brief SocketProtocol and ConcreteSocketProtocol public header
\idea We should optimize the protocol handling. Allocating a protocol instance for every socket
body seems quite wasteful. We could derive SocketPolicy from SocketBody (probably privately,
diff --git a/Socket/TCPSocketHandle.cc b/Socket/TCPSocketHandle.cc
index e7bb95cef..7202fe384 100644
--- a/Socket/TCPSocketHandle.cc
+++ b/Socket/TCPSocketHandle.cc
@@ -20,7 +20,9 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-// Definition of non-inline non-template functions
+/** \file
+ \brief TCPv4SocketHandle and TCPv6SocketHandle non-inline non-template implementation
+ */
#include "TCPSocketHandle.hh"
//#include "TCPSocketHandle.ih"
diff --git a/Socket/TCPSocketHandle.hh b/Socket/TCPSocketHandle.hh
index a566d9398..484e6222f 100644
--- a/Socket/TCPSocketHandle.hh
+++ b/Socket/TCPSocketHandle.hh
@@ -21,6 +21,7 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
+ \brief TCPv4SocketHandle and TCPv6SocketHandle public header
\todo Implement possibly non-blocking connect and SO_ERROR in the
protocol interface
@@ -57,7 +58,27 @@ namespace senf {
SocketBufferingPolicy
>::policy TCPv4Socket_Policy; ///< Socket Policy of the TCPv4 Protocol
- /** \brief
+ /** \brief IPv4 TCP Socket Protocol
+
+ \par Socket Handle typedefs:
+ \ref TCPv4ClientSocketHandle (ProtocolClientSocketHandle), \ref TCPv4ServerSocketHandle
+ (ProtocolServerSocketHandle)
+
+ \par Protocol Interface:
+ ClientSocketHandle::read(), ClientSocketHandle::write(), ClientSocketHandle::bind(),
+ ClientSocketHandle::local(), ClientSocketHandle::connect(), ClientSocketHandle::peer(),
+ ClientSocketHandle::rcvbuf(), ClientSocketHandle::sndbuf()
+
+ \par Address Type:
+ INet4Address
+
+ TCPv4SocketProtocol provides an internet protocol stream socket based on the TCP protocol
+ and IPv4 addressing.
+
+ This class is utilized as the protocol class of the ProtocolClientSocketHandle and
+ ProtocolServerSocketHandle via the Socket Handle typedefs above.
+
+ \see TCPv6SocketProtocol
*/
class TCPv4SocketProtocol
: public ConcreteSocketProtocol<TCPv4Socket_Policy>,
@@ -73,10 +94,34 @@ namespace senf {
///\name Constructors
///@{
- void init_client() const;
+ void init_client() const; ///< Create unconnected client socket
+ /**< \note This member is implicitly called from the
+ ProtocolClientSocketHandle::ProtocolClientSocketHandle()
+ constructor */
void init_client(INet4Address const & address) const;
- void init_server() const;
+ ///< Create client socket and connect
+ /**< Creates a new client socket and connects to the given
+ address.
+
+ \param[in] address remote address to connect to */
+ /**< \note This member is implicitly called from the
+ ProtocolClientSocketHandle::ProtocolClientSocketHandle()
+ constructor */
+ void init_server() const; ///< Create server socket
+ /**< \note This member is implicitly called from the
+ ProtocolServerSocketHandle::ProtocolServerSocketHandle()
+ constructor */
void init_server(INet4Address const & address, unsigned backlog=1) const;
+ ///< Create server socket and listen
+ /**< Creates a new server socket, binds to \a address end
+ starts listening for new connections with a backlog of
+ \a backlog connections. It also enables reuseaddr().
+
+ \param[in] address address to listen on
+ \param[in] backlog size of the listen backlog */
+ /**< \note This member is implicitly called from the
+ ProtocolServerSocketHandle::ProtocolServerSocketHandle()
+ constructor */
///@}
///\name Abstract Interface Implementation
@@ -94,6 +139,30 @@ namespace senf {
INet6AddressingPolicy
>::policy TCPv6Socket_Policy;
+ /** \brief IPv6 TCP Socket Protocol
+
+ \par Socket Handle typedefs:
+ \ref TCPv6ClientSocketHandle (ProtocolClientSocketHandle), \ref TCPv6ServerSocketHandle
+ (ProtocolServerSocketHandle)
+
+ \par Protocol Interface:
+ ClientSocketHandle::read(), ClientSocketHandle::write(), ClientSocketHandle::bind(),
+ ClientSocketHandle::local(), ClientSocketHandle::connect(), ClientSocketHandle::peer(),
+ ClientSocketHandle::rcvbuf(), ClientSocketHandle::sndbuf()
+
+ \par Address Type:
+ INet6Address
+
+ TCPv6SocketProtocol provides an internet protocol stream socket based on the TCP protocol
+ and IPv6 addressing.
+
+ This class is utilized as the protocol class of the ProtocolClientSocketHandle and
+ ProtocolServerSocketHandle via the Socket Handle typedefs above.
+
+ \see TCPv4SocketProtocol
+
+ \todo Implement
+ */
class TCPv6SocketProtocol
: public ConcreteSocketProtocol<TCPv6Socket_Policy>,
public IPv6Protocol,
@@ -101,7 +170,6 @@ namespace senf {
public BSDSocketProtocol,
public AddressableBSDSocketProtocol
{
- /** \todo Implement */
};
typedef ProtocolClientSocketHandle<TCPv6SocketProtocol> TCPv6ClientSocketHandle;
@@ -121,4 +189,5 @@ namespace senf {
// Local Variables:
// mode: c++
// c-file-style: "senf"
+// fill-column: 100
// End:
diff --git a/senfscons/SENFSCons.py b/senfscons/SENFSCons.py
index 0484e5695..771d4fada 100644
--- a/senfscons/SENFSCons.py
+++ b/senfscons/SENFSCons.py
@@ -177,7 +177,7 @@ def Doxygen(env, doxyfile = "Doxyfile", extra_sources = []):
env.Action(("for html in %s/*.html; do " +
" echo $$html;" +
" sed -e 's/id=\"current\"/class=\"current\"/' $${html}" +
- " | tidy -ascii -q --show-warnings no" +
+ " | tidy -ascii -q --show-warnings no --fix-uri no" +
" | xsltproc --nonet --html -o $${html}.new %s - 2>&1" +
" | grep '^-'" +
" | grep -v 'ID .* already defined';" +
--
GitLab