diff --git a/Socket/AddressingPolicy.hh b/Socket/AddressingPolicy.hh
index 238dfcb17b87dc44f5a7798eca207b5b22ee6495..b932456fe4cea36d4cdcedb8fd5d19f2cf00dd35 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 9379c7c6a2f14365068cdd4d897e83e4399a8dd4..33ef74be651e00d8f8c307c2d35696bc242e69d7 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 669aa38ffa203c05931464ccdd5df47b138dcd55..21aea1c562868197926c12bedac6b5a4414b3842 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 3c836a4b6d36571980129d30455b8219b0c38d5f..64e73724b885bc30e99585b663d421b235e40124 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 816da3a77858b0bdb21e837f972769d01b698e32..9fef12b61318cec4eaccb143b15279c3c230b1c2 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 98711da3e6c4c73cef15377da5e4cbf6180fdc39..50e4f7ff533cd97f0d7e41d4b3862dfeadda2b3d 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 4d8cdce77588407939f36112eae0e1e27b1e3d78..097a8bfe0e4fdb895c1dfa368eb32dc6926a4fdc 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 c482e6db641edbdce1dc5a67faf9179f427b7715..3e6b0237a550b84eb3e96363d12b178ea4552d4b 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 0fc5f3e52537650a243434b8e82f1da2d5e97363..f66a34807fa43235c7e2e086e456904230721c70 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 5f82eaf103c5bb175999b8a842017dab3ef3b3a2..a0b2de58fc02552f9f519bdfd3e2213974e77091 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 24c05283c9abc66c67f1f5fc85d4e5dea757e6a9..f79466f2dd2ed6841b337c92683563fc4309828f 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 97a440c263bc571ffc9d2a28d5d571e459a1d359..a873239d0fe87521cd185f79d30ad94a3eb112c7 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 a59d1746f719309f12467e32aaba6605b42ac847..c9d1b63854ce84cf8312bd5c513fd16c09afcad0 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 33e6120c5e15e4c690ffd5b3245a4392c9913978..c9a050f796755cc4912ccec08e02c284ca5b1962 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 fa7f5d193e5f3bab12d7a796fd93c9a8e5737492..f4e82162b404634937cec97a01b28876da32ffd4 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 29496dc37f201d7b12fbe423c836a8c7e15bd7e0..2296b5d965178cc16eb5e23efde7a706131ee0f6 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 b995959a12026e6942ab130e9f4c74ff8b82e44f..88b8410132fa2956ce0d4f240d99b748748e1c2b 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 bc2ac294d489951ee68bfc65523194214af0094b..ca002ab2f0ecd3bbb0437f06a0ec7098fde2dd5c 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 c162b8ecf51de9d50731d1d6dfea6d3e13317dff..f7bdd052ee72d8767fe1e6f39958700de5045ee7 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 b8748ff6412780da146d8432bf06db2f36c8117e..48e31d88b691553a72c74fcc68a793f635916891 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 9ae920e1934fca612db0c0955db902acc6c30549..62ead40354880718f0cec476705d967ceb48e23d 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 1b20fdbcaa10ba4915bf603e2845d594319a9f98..2fbc07720e0afbd2acf3ec04c7ce57b18fc83bff 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 43e81346d0088ddf0041f3edc4ea1ceed63405fe..c81dae45d0745562de32b56b1db0e2d896d78ce7 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 a7b463ac6aa20a5ce25f90ff80d8f91c9f0db853..74231e6eaa9be5c070a7738bf66d7fa61052f903 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 2fd0720b31f485e808c5e81b6952b0415f3fe521..e96fd2c02a817e23a146ca69c37a5363ffadbd7b 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 a60c6c12aa787f375e0e87531392752664904640..a928f06a1e0e00ca60b268ad2aac48ec3cad33b0 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 c441f198cd973f581adab2889e9fdbaec351b308..b1f280c17b5ead91a4c9b6bc79e436275da10478 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 84a378f350c83d30aaa32b565bc58523ea1556b4..d9c065de014d054182ae281050aefc6c38065486 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 644ad879297f9cf0e036bfe1f563fc5481cc31f2..73edd344e44ad097e125991ea2e0c39e47f3803e 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 643e477deb4ab4a003b55d205a9e8429a25a0f2b..35299c65c522ced1b477354d599361d253e09292 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 0c58c00ebfeef4685afa3d55b0f53dd58e17f48d..9875737755630f92d21bd23468f26b66b94bb63d 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 7d9281556ec2a9a7288d729695ebd951cfa445a8..807639bd1781de81855ed9f9895f0f5e45c0d639 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 e138ec263607bdafb7952ba15ae1e87cf7806cc5..c62ccb4af6bb090e3f654c0137efc43a4025cf74 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 eac4a09e8f4d106d0db40e5221bbf52109e21bec..c90c6bed4c0699d6c74bef6012f75ff2873aab9d 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 08a3e4db5b00c563dd94a9b6f7ca944131bb67f0..4d03d6768277b89ead9be3c062d7d0fa89e637c0 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 d8f71de390351a55a207ae43e2b50ca4ff02f06d..96995915d16dc1e53e7ad6cc99c9a04ef242242b 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 4c52c6597acc0ce7df1fde2f9ee356d6a09f3042..a7ddf61055cb456231d911cf88f71913873d8986 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 c0723b0a49b6a2c69cc65d2a52b08399346d137f..db8cee50f2d3704da4f2666c797478198700a105 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 d5afd75286eb9baad37e82d3cc0653612a689efd..354a221c0711be4c49bc12634488d2484701155a 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 a8a848b931d2327a6bccb57f618e8fb11edf646f..0dcff103f41739ab0fe0597f520a087295f4f3d0 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 ff56cc19308ef69e63ea6fee0e28136bb0d7761a..eb9315746426f1a83fbc838838147741f786b4ee 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 95e38e8810095d39d6f77d98d22e79925fc8e13b..863dc4fd4e11b9113bb1b03dbed0814e91e9ce8f 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 e7bb95cefbacdf18158ef522be96d3e9bd573f34..7202fe384aeeaa38284ddb9609e738845391f9d2 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 a566d939864f90517bfbabefeebc85bd71f2fa30..484e6222f4f0c029580292517a06c0140155f1a3 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 0484e5695054737a6f50b235a2382e7f2032e6c7..771d4fadad223a6172cf51bcedbd21d2061db273 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';" +