From: g0dil Date: Tue, 3 Jun 2008 17:09:29 +0000 (+0000) Subject: Socket: Documentation for new addressing classes X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=8475937b6551f73a1cddd8fa830b7128d4c8ebf7;p=senf.git Socket: Documentation for new addressing classes git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@867 270642c3-0616-0410-b53a-bc976706d245 --- diff --git a/Socket/Mainpage.dox b/Socket/Mainpage.dox index 9a0c847..1776880 100644 --- a/Socket/Mainpage.dox +++ b/Socket/Mainpage.dox @@ -24,27 +24,79 @@ namespace senf { /** \mainpage The SENF Socket Library - The Socket library provides a high level and object oriented abstraction of the BSD socket - API. The abstraction is based on several concepts: + The Socket library provides a high level and object oriented abstraction based on the BSD socket + API (but not limited to it). + + \autotoc + + \section socket_intro Introduction - \li The basic visible interface is a \link handle_group handle object \endlink + The socket library abstraction is based on several concepts: + + \li The basic visible interface is a \link handle_group handle object\endlink \li The socket interface relies on a \link policy_group policy framework \endlink to configure it's functionality \li The rest of the socket API is accessible using a classic inheritance hierarchy of \link protocol_group protocol classes \endlink + \li There is a family of auxilliary \ref addr_group to supplement the socket library + + \see + \ref structure \n + \ref usage + + + \section socket_handle Socket Handles The handle/body architecture provides automatic reference counted management of socket - instances, the policy framework provides highly efficient access to the most important socket - functions (like reading and writing) and the inheritance hierarchy provides convenient access to - the multitude of special and protocol dependent options. + instances. This is the visible interface to the socket library. + + Each specific protocol is used primarily via a protocol specific handle (a typedef + symbol). However, more generic kinds of handles can be defined for more generic functionality. \see - \ref structure \n - \ref usage \n \ref handle_group \n - \ref policy_group \n - \ref protocol_group \n - \ref addr_group \n + \ref concrete_protocol_group + + + \section socket_policy The Policy interface + + The policy framework configures the exact features, a specific type of socket handle + provides. This offers highly efficient access to the most important socket functions (like + reading and writing). The policy interface however is a \e static, non-polymorphic interface. + + \see + \ref policy_group + + \section socket_protocol The Protocol interface + + The protocol interface provides further protocol dependent and (possibly) polymorphic access to + further socket funcitonality. On the other hand, this type of interface is not as flexible, + generic and fast as the policy interface. + + \see + \ref protocol_group + + \section socket_addr Auxilliary Addressing classes + + To supplement the socket library, there are a multitude of addressing classes. These come in two + basic groups: + \li Protocol specific addresses (e.g. INet4Address, MACAddress) + \li Socket addresses (\c sockaddr) (e.g. INet4SocketAddress, LLSocketAddress) + + Whereas the protocol specific addresses are custom value types which represent their + corresponding low-level address, the socket addresses are based on the corresponding \c sockaddr + structures. + + \see + \ref addr_group + + \section socket_further Going further + + The socket library is highly flexible and extensible. The implementation is not restricted to + plain BSD sockets: Any type of read/write communication can be wrapped into the socket library + (one Example is the TapSocketHandle which provides access to a Linux \c tap device). + + \see \ref extend \n \ref implementation */ diff --git a/Socket/Protocols/BSDSocketAddress.hh b/Socket/Protocols/BSDSocketAddress.hh index 6b2dfe2..61cb220 100644 --- a/Socket/Protocols/BSDSocketAddress.hh +++ b/Socket/Protocols/BSDSocketAddress.hh @@ -36,21 +36,49 @@ namespace senf { - /** \brief + /** \brief Socket addressing, BSD style + + BSDSocketAddress is the base class of all BSD \c sockaddr based addressing classes. The \c + sockaddr addressing interface is split into several parts + + \li The BSDSocketAddress provides a read-only and generic \c sockaddr interface + \li Address family specific derived classes implement addressing of a specific type. These + are INet4SocketAddress (\c AF_INET), INet6SocketAddress (\c AF_INET6), UNSocketAddress + (\c AF_UNIX) and LLSocketAddress (\c AF_PACKET) + \li GenericBSDSocketAddress provides writable support for generic addresses. + + It is \e not possible to create or store BSDSocketAddress instances: You must either store + an address in one of the specifically typed subclasses or using GenericBSDSocketAddress. + + All these classes provide a generic \c sockaddr API to interface with legacy \c sockaddr + based code (e.g. the BSD socket API). In this base-class, this interface is read-only, the + derived classes however provide a read-write interface. + + \ingroup addr_group */ class BSDSocketAddress : public senf::comparable_safe_bool { public: - - bool operator==(BSDSocketAddress const & other) const; - bool operator!=(BSDSocketAddress const & other) const; - - bool boolean_test() const; - short family() const; + bool operator==(BSDSocketAddress const & other) const; ///< Compare two arbitrary addresses + /**< For addresses to be considered equal, they must have + the same family, length and the data must be + identical. */ + bool operator!=(BSDSocketAddress const & other) const; ///< Inverse of operator== + + bool boolean_test() const; ///< Return \c true, if address is not empty + /**< An address is considered empty if + \li the family is AF_UNSPEC + \li or the size is 0 + \li or all data bytes are 0 */ + + short family() const; ///< Return the address family. + /**< This value is found in the \c addressFamily member of + each typed derived class + (e.g. INet4Address::addressFamily) */ /////////////////////////////////////////////////////////////////////////// - ///\name Generic \c sockaddr interface + ///\name Generic sockaddr interface ///\{ struct sockaddr const * sockaddr_p() const; @@ -74,15 +102,43 @@ namespace senf { socklen_t len_; }; + /** \brief Safe socket address down-cast + + sockaddr_cast allows to safely cast a socket address to it's derived type. Only the family + specific derived addressing classes are permissible for \a Target. + + This cast is especially useful to cast a GenericBSDSocketAddress to it's concrete type. + + \related BSDSocketAddress + */ template Target & sockaddr_cast(BSDSocketAddress & source); + /** \brief Safe socket address down-cast (const) + \see sockaddr_cast() + \related BSDSocketAddress + */ template Target const & sockaddr_cast(BSDSocketAddress const & source); + /** \brief Output generic socket address + + This stream operator will output a generic BSDSocketAddress in a family depending format. + + \related BSDSocketAddress + */ std::ostream & operator<<(std::ostream & os, BSDSocketAddress const & addr); - /** \brief + /** \brief Generic BSD \c sockaddr storage + + While BSDSocketAddress provides read-only generic \c sockaddr access, + GenericBSDSocketAddress allows to store (write) arbitrary socket addresses. (It is + internally based on \c sockaddr_storage). + + To access the stored address, use sockaddr_cast to cast the GenericBSDSocketAddress to the + correct family specific address class. + + \ingroup addr_group */ class GenericBSDSocketAddress : public BSDSocketAddress @@ -101,7 +157,7 @@ namespace senf { ///@} /////////////////////////////////////////////////////////////////////////// - ///\name Generic \c sockaddr interface + ///\name Generic sockaddr interface ///\{ struct sockaddr const * sockaddr_p() const; diff --git a/Socket/Protocols/UN/ConnectedUNDatagramSocketHandle.hh b/Socket/Protocols/UN/ConnectedUNDatagramSocketHandle.hh index ba5db71..b259925 100644 --- a/Socket/Protocols/UN/ConnectedUNDatagramSocketHandle.hh +++ b/Socket/Protocols/UN/ConnectedUNDatagramSocketHandle.hh @@ -40,9 +40,6 @@ namespace senf { - /// \addtogroup concrete_protocol_group - /// @{ - typedef MakeSocketPolicy< UNAddressingPolicy, DatagramFramingPolicy, @@ -51,6 +48,9 @@ namespace senf { WriteablePolicy >::policy ConnectedUNDatagramSocket_Policy; ///< Socket Policy of the Unix Domain Datagram Protocol (connected) + /// \ingroup concrete_protocol_group + /// \{ + /** \brief Unix Domain Datagram Socket Protocol (connected) \par Socket Handle typedefs: @@ -101,6 +101,8 @@ namespace senf { typedef ProtocolClientSocketHandle ConnectedUNDatagramClientSocketHandle; + ///\} + } ///////////////////////////////hh.e////////////////////////////////////////