From: g0dil Date: Tue, 6 Feb 2007 16:19:56 +0000 (+0000) Subject: Finished documentation of non protocol specific socket library classes X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=d0006132bfcb3ab442cf66b600ed3fad36f1ac2c;p=senf.git Finished documentation of non protocol specific socket library classes git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@193 270642c3-0616-0410-b53a-bc976706d245 --- diff --git a/Socket/AddressingPolicy.hh b/Socket/AddressingPolicy.hh index 238dfcb..b932456 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 9379c7c..33ef74b 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 669aa38..21aea1c 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 3c836a4..64e7372 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 816da3a..9fef12b 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 98711da..50e4f7f 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 4d8cdce..097a8bf 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 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 static int accept(ServerSocketHandle handle, typename ServerSocketHandle::Address & address, typename IfAddressingPolicyIsNot::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 c482e6d..3e6b023 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 0fc5f3e..f66a348 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 5f82eaf..a0b2de5 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 24c0528..f79466f 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 97a440c..a873239 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 a59d174..c9d1b63 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 33e6120..c9a050f 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 fa7f5d1..f4e8216 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 + struct sockaddr * 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. The underlying socket address stored at that pointer might be + modified. + + \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 struct GenericAddressingPolicy : private GenericAddressingPolicy_Base @@ -50,14 +80,35 @@ namespace senf { template static void peer(SocketHandle handle, Address & addr, typename IfCommunicationPolicyIs::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 static void connect(SocketHandle handle, Address const & addr, typename IfCommunicationPolicyIs::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 29496dc..2296b5d 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 b995959..88b8410 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 bc2ac29..ca002ab 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 c162b8e..f7bdd05 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 b8748ff..48e31d8 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, @@ -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 9ae920e..62ead40 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 1b20fdb..2fbc077 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 43e8134..c81dae4 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 a7b463a..74231e6 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 2fd0720..e96fd2c 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 a60c6c1..a928f06 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 c441f19..b1f280c 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 84a378f..d9c065d 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 644ad87..73edd34 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 static unsigned readfrom(ClientSocketHandle handle, char * buffer, unsigned size, typename Policy::AddressingPolicy::Address & address, typename IfCommunicationPolicyIs::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 static unsigned write(ClientSocketHandle handle, char const * buffer, unsigned size, typename IfCommunicationPolicyIs::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 static unsigned writeto(ClientSocketHandle handle, typename boost::call_traits::param_type addr, char const * buffer, unsigned size, typename IfCommunicationPolicyIs::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 643e477..35299c6 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 0c58c00..9875737 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 7d92815..807639b 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 e138ec2..c62ccb4 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 eac4a09..c90c6be 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 08a3e4d..4d03d67 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 d8f71de..9699591 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 4c52c65..a7ddf61 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 c0723b0..db8cee5 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 d5afd75..354a221 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 a8a848b..0dcff10 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 ff56cc1..eb93157 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 95e38e8..863dc4f 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 e7bb95c..7202fe3 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 a566d93..484e622 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, @@ -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, public IPv6Protocol, @@ -101,7 +170,6 @@ namespace senf { public BSDSocketProtocol, public AddressableBSDSocketProtocol { - /** \todo Implement */ }; typedef ProtocolClientSocketHandle 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 0484e56..771d4fa 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';" +