/** \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
*/
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<BSDSocketAddress>
{
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;
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 <class Target>
Target & sockaddr_cast(BSDSocketAddress & source);
+ /** \brief Safe socket address down-cast (const)
+ \see sockaddr_cast()
+ \related BSDSocketAddress
+ */
template <class Target>
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
///@}
///////////////////////////////////////////////////////////////////////////
- ///\name Generic \c sockaddr interface
+ ///\name Generic sockaddr interface
///\{
struct sockaddr const * sockaddr_p() const;
projects / senf.git / commitdiff