diff --git a/Socket/BSDSocketProtocol.cc b/Socket/BSDSocketProtocol.cc
index d8f5163f8d0cdf2704cd42ebc7c18857887d20da..fe9fd1d766dcacda118cb813710d0bcf5b2c159e 100644
--- a/Socket/BSDSocketProtocol.cc
+++ b/Socket/BSDSocketProtocol.cc
@@ -20,7 +20,8 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-// Definition of non-inline non-template functions
+/** \file
+ \brief BSDSocketProtocol non-inline non-template implementation */
#include "BSDSocketProtocol.hh"
//#include "BSDSocketProtocol.ih"
@@ -60,7 +61,10 @@ prefix_ struct timeval senf::BSDSocketProtocol::timestamp()
const
{
/** \bug Check, why this fails with ENOFILE (!!!!) at least when
- called from a tcp socket. Further investigation necessary ... */
+ called from a tcp socket.Maybe this is only available for
+ datagram sockets ? That could make sense from the description
+ (what is the last packet passed to the user on a stream
+ socket?) Further investigation necessary ... */
struct timeval tv;
if (::ioctl(body().fd(), SIOCGSTAMP, &tv) < 0)
throw SystemException(errno);
diff --git a/Socket/BSDSocketProtocol.hh b/Socket/BSDSocketProtocol.hh
index 39d19d8554556826807160e7ad12273c93b535c5..e924ef9b1918cffb382b583d3b23eca89e2ab1d9 100644
--- a/Socket/BSDSocketProtocol.hh
+++ b/Socket/BSDSocketProtocol.hh
@@ -20,6 +20,9 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+/** \file
+ \brief BSDSocketProtocol public header */
+
#ifndef HH_BSDSocketProtocol_
#define HH_BSDSocketProtocol_ 1
@@ -32,25 +35,59 @@
namespace senf {
+ /// \addtogroup protocol_facets_group
+ /// @{
+ /** \brief Protocol facet providing basic BSD socket functionality
+
+ BSDSocketProtocol provides the basic BSD socket API as shared by all BSD sockets.
+ */
class BSDSocketProtocol
: public virtual SocketProtocol
{
public:
- std::pair<bool,unsigned> linger() const;
- void linger(bool enable, unsigned timeout) const;
+ std::pair<bool,unsigned> linger() const; ///< Return current linger status
+ /**< The value is returned in an std:pair. the first element
+ is \c true, if linger is active. The second value is
+ the linger timeout in seconds.
+ \returns linger state (enable disabled) and linger
+ timeout */
+ void linger(bool enable, unsigned timeout=0) const; ///< Change linger status
+ /**< If linger is enabled, the timeout value specifies, how
+ long to wait before returning while data is unsent in
+ seconds. If this value is 0, a close() might wait
+ forvever.
+ \param[in] enable \c true to activate linger
+ \param[in] timeout linger timeout in seconds */
- struct timeval timestamp() const;
+ struct timeval timestamp() const; ///< Return packet timestamp of last packet
+ /**< The returned timestamp represents the time, at which
+ the last network packet passed to the user has been
+ received from the network. This allows precise network
+ timing.
+ \returns timestamp when packet was received */
};
+ /** \brief Protocol facat providing basic connection oriented BSD socket functions
+
+ AddressableBSDSocketProtocol provides the BSD socket API as it generically applies to
+ addressable (connection oriented) sockets.
+ */
class AddressableBSDSocketProtocol
: public virtual SocketProtocol
{
public:
- bool reuseaddr() const;
- void reuseaddr(bool value) const;
+ bool reuseaddr() const; ///< Return current reuseaddr state
+ /**< \returns \c true if \c SO_REUSEADDR is currently
+ enabled, \c false otherwise*/
+ void reuseaddr(bool value) const; ///< Set reuseraddr state
+ /**< A \c true value enables \c SO_REUSEADDR, \c false will
+ disable it.
+ \param[in] value new \c SO_REUSEADDR state */
};
+ /// @}
+
}
@@ -65,4 +102,5 @@ namespace senf {
// Local Variables:
// mode: c++
// c-file-style: "senf"
+// fill-column: 100
// End:
diff --git a/Socket/BufferingPolicy.cc b/Socket/BufferingPolicy.cc
index 8fdf27b54d3c12aabf3254f3dce60930962d1f6b..d35e99368e548bafd31c226a17f2aaf8a699bb68 100644
--- a/Socket/BufferingPolicy.cc
+++ b/Socket/BufferingPolicy.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 BufferingPolicy non-inline non-template implementation
+ */
#include "BufferingPolicy.hh"
//#include "BufferingPolicy.ih"
diff --git a/Socket/BufferingPolicy.hh b/Socket/BufferingPolicy.hh
index 0260dbb4ad2938e3c15cf00b9e49bd4fde2c56bc..1c63523f4a3df97e603f9961a6b15b02b965757b 100644
--- a/Socket/BufferingPolicy.hh
+++ b/Socket/BufferingPolicy.hh
@@ -20,6 +20,10 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+/** \file
+ \brief BufferingPolicy public header
+ */
+
#ifndef HH_BufferingPolicy_
#define HH_BufferingPolicy_ 1
@@ -32,20 +36,38 @@
namespace senf {
+ /// \addtogroup policy_impl_group
+ /// @{
+
+ /** \brief BufferingPolicy implementing standard socket buffering
- /** \brief
+ This policy class implements standard BSD socket buffering.
\todo Shouldn't this be dependent on Read / WritePolicy ?
*/
struct SocketBufferingPolicy : public BufferingPolicyBase
{
static unsigned rcvbuf(FileHandle handle);
+ ///< Check receive buffer size
+ /**< \param[in] handle socket handle to check
+ \returns size of receive buffer in bytes */
static void rcvbuf(FileHandle handle, unsigned size);
+ ///< Change receive buffer size
+ /**< \param[in] handle socket handle
+ \param[in] size new receive buffer size */
static unsigned sndbuf(FileHandle handle);
+ ///< Check send buffer size
+ /**< \param[in] handle socket handle to check
+ \returns size of send buffer in bytes */
static void sndbuf(FileHandle handle, unsigned size);
+ ///< Change size of send buffer
+ /**< \param[in] handle socket handle
+ \param[in] size new send buffer size */
};
+ /// @}
+
}
///////////////////////////////hh.e////////////////////////////////////////
@@ -59,4 +81,5 @@ namespace senf {
// Local Variables:
// mode: c++
// c-file-style: "senf"
+// fill-column: 100
// End:
diff --git a/Socket/GenericAddressingPolicy.hh b/Socket/GenericAddressingPolicy.hh
index f4e82162b404634937cec97a01b28876da32ffd4..cc5c527110750cd6aa776d922d0f264dc117c5a3 100644
--- a/Socket/GenericAddressingPolicy.hh
+++ b/Socket/GenericAddressingPolicy.hh
@@ -66,6 +66,10 @@ namespace senf {
address. <em>The underlying socket address stored at that pointer might be
modified</em>.
+ This template class is inherited into addressing policy classes via private
+ inheritance. Then the members supported by the respective addressing policy are made
+ available via \c using declarations (See INet4AddressingPolicy for an Example).
+
\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
diff --git a/Socket/GenericSockAddr.hh b/Socket/GenericSockAddr.hh
index 7e1b43724baf319127abfb24902b6dc9a4312d52..6c1072df4e1184ab644a3c131a1fa5b4a3a4e3be 100644
--- a/Socket/GenericSockAddr.hh
+++ b/Socket/GenericSockAddr.hh
@@ -1,6 +1,43 @@
// $Id$
//
// Copyright (C) 2006
+// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
+// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
+// Stefan Bund <stefan.bund@fokus.fraunhofer.de>
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the
+// Free Software Foundation, Inc.,
+// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+
+/** \file
+ \brief GenericSockAddr public header */
+
+/** \defgroup addr_group Socket Addressing
+
+ To support the core socket functionality we need a collection of classing providing addressing
+ for the different protocols.
+
+ Every Address Implementation used with the standard policy classes Has to have a set of minimum
+ members. These members are documented in GenericSockAddr. However, these members are \e neither
+ abstract \e nor virtual and other address classes do \e not inherit from GenericSockAddr. The
+ address classes are not usable polymorphically for performance reasons.
+
+ The interface defined above forces the implementation to be directly based on the corresponding
+ sockaddr data structures provided by the BSD socket API. These structures however are wrapped
+ into more flexible and more easy to use classes. Using the sockaddr representation increases the
+ performance since any intermediarre conversions are skipped.
+ */
#ifndef HH_GenericSockAddr_
#define HH_GenericSockAddr_ 1
@@ -13,20 +50,45 @@
namespace senf {
+ /// \addtogroup addr_group
+ /// @{
+ /** \brief Generic protocol-independant socket address
+
+ This address type does not depend on the protocol of the socket. It does nowever not support
+ any protocol specific API, so access to the address is very limited.
+ */
class GenericSockAddr
{
public:
GenericSockAddr();
-
- struct sockaddr * sockaddr_p();
- struct sockaddr const * sockaddr_p() const;
- unsigned sockaddr_len() const;
+
+ /// \name Generic Address Interface
+ /// @{
+
+ struct sockaddr * sockaddr_p(); ///< Return a pointer to sockaddr structure
+ /**< The exact structure pointed to depends on the address
+ family. The data pointed to must be \e mutable. The
+ value must be changeable and any change of the value
+ through this pointer must be reflected in the visible
+ address interface.
+ \returns non-const (!) pointer to sockaddr structure */
+ struct sockaddr const * sockaddr_p() const; ///< Return a pointer to sockaddr structure
+ /**< This member is like sockaddr_p(), hoewever it does not
+ allow changing the address.
+ \returns const pointer to sockaddr structure */
+ unsigned sockaddr_len() const; ///< Return size of address
+ /**< This meember return the size of the socket address
+ structure as returned by sockaddr_p() in bytes.
+ \returns size of respective sockaddr structure in bytes
+ */
+ /// @}
private:
struct ::sockaddr_storage addr_;
};
+ /// @}
}
///////////////////////////////hh.e////////////////////////////////////////
@@ -39,4 +101,6 @@ namespace senf {
// Local Variables:
// mode: c++
+// c-file-style: "senf"
+// fill-column: 100
// End:
diff --git a/Socket/INetAddressing.cc b/Socket/INetAddressing.cc
index 3081cc59e34256f22c4206a98e991321409f9f39..d96bd9302bf02d9c94a43aa4a97a6cfefb1e7d14 100644
--- a/Socket/INetAddressing.cc
+++ b/Socket/INetAddressing.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 INet[46]Address and INet[46]AddressingPolicy non-inline non-template implementation
+ */
#include "INetAddressing.hh"
//#include "INetAddressing.ih"
@@ -61,17 +63,18 @@ prefix_ void senf::INet4Address::clear()
prefix_ void senf::INet4Address::assignString(std::string address)
{
clear();
- /** \todo gethostbyname support */
unsigned i = address.find(':');
if (i == std::string::npos)
throw InvalidINetAddressException();
+ // The temporary string in the next expr is guaranteed to live
+ // until end-of-statement
if (::inet_aton(std::string(address,0,i).c_str(), &addr_.sin_addr) == 0)
throw InvalidINetAddressException();
try {
// Replace lexical_cast with strtoul ?
addr_.sin_port = htons(boost::lexical_cast< ::u_int16_t >(std::string(address,i+1)));
}
- catch (boost::bad_lexical_cast const & ex) {
+ catch (boost::bad_lexical_cast const &) {
throw InvalidINetAddressException();
}
}
diff --git a/Socket/INetAddressing.cci b/Socket/INetAddressing.cci
index 81ac9f1fc356b43b4651dc1d32847437d0160253..688cbb58586b197413e804502cc2cf9cc68bc7cf 100644
--- a/Socket/INetAddressing.cci
+++ b/Socket/INetAddressing.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 INet[46]Address and INet[46]AddressingPolicy inline non-template implementation
+ */
// Custom includes
#include <arpa/inet.h>
diff --git a/Socket/INetAddressing.hh b/Socket/INetAddressing.hh
index 9b8b160aaae7f1d067a2d6ee63ac7e36ac80adac..d87f71f43e6b33efb11aeffdab34eaca3bce9276 100644
--- a/Socket/INetAddressing.hh
+++ b/Socket/INetAddressing.hh
@@ -20,6 +20,10 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+/** \file
+ \brief INet[46]Address and INet[46]AddressingPolicy public header
+ */
+
#ifndef HH_INetAddressing_
#define HH_INetAddressing_ 1
@@ -37,50 +41,103 @@
namespace senf {
+ /// \addtogroup addr_group
+ /// @{
- /** \brief
-
- \todo Implement real INet4Address datatype and
- rename this one to INet4SockAddress ...
+ /** \brief IPv4 socket address
+ INet4Address wrapps the standard sockaddr_in datatype. It provides simple accessor methods
+ to accss the host and port. It does \e not integrate \c gethostbyname or DNS lookup.
+
+ \todo Implement real INet4Address datatype and rename this one to INet4SockAddress ...
\todo Implement more complete interface
+ \todo gethostbyname support ?
*/
class INet4Address
{
public:
INet4Address();
- INet4Address(char const * address);
- INet4Address(std::string address);
- INet4Address(std::string host, unsigned port);
+ INet4Address(char const * address); ///< Set address and port
+ /**< See INet4Address(std::string)
+ \throws InvalidINetAddressException
+ \fixme Why do I need this version? Shouldn't the
+ std::string version be enough ? */
+ INet4Address(std::string address); ///< Set address and port
+ /**< This constructor expects a string of the form
+ 'xxx.xxx.xxx.xxx:pppp'. The constructor will use this
+ value to initialize the host and port members. This
+ constructor does \e only support numeric ip addresses
+ not hostnames
+ \param[in] address Address and port
+ \throws InvalidINetAddressException */
+ INet4Address(std::string host, unsigned port); ///< Set address and port explicitly
+ /**< \param[in] host ip address in dotted-quad notation
+ \param[in] port port number
+ \throws InvalidINetAddressException */
+
- bool operator==(INet4Address const & other) const;
+ bool operator==(INet4Address const & other) const; ///< Check INet4Address for equality
- std::string str() const;
- std::string host() const;
- unsigned port() const;
+ std::string str() const; ///< Return "address:port" string
+ std::string host() const; ///< Return address in doted quad notation
+ unsigned port() const; ///< Return portnumber
- void clear();
+ void clear(); ///< Clear address/port to 0.0.0.0:0
+
+ /// \name Generic Address Interface
+ /// @{
struct sockaddr * sockaddr_p();
struct sockaddr const * sockaddr_p() const;
unsigned sockaddr_len() const;
+ /// @}
+
private:
void assignString(std::string addr);
struct ::sockaddr_in addr_;
};
+ /** \brief Write address and port to os
+
+ \related INet4Address
+ */
std::ostream & operator<<(std::ostream & os, INet4Address const & addr);
- /** \brief
+ /** \brief IPv6 socket address
\todo Implement
*/
class INet6Address
{
};
-
+
+ /** \brief Signal invalid INet address syntax
+
+ \related INet4Address
+ \relatesalso INet6Address
+ */
+ struct InvalidINetAddressException : public std::exception
+ { char const * what() const throw() { return "invalid inet address"; } };
+
+ /// @}
+
+ /// \addtogroup policy_impl_group
+ /// @{
+
+ /** \brief Addressing policy supporting IPv4 addressing
+
+ \par Address Type:
+ INet4Address
+
+ This addressing policy implements addressing using Internet V4
+ addresses.
+
+ The various members are directly importet from
+ GenericAddressingPolicy which see for a detailed
+ documentation.
+ */
struct INet4AddressingPolicy
: public AddressingPolicyBase,
private GenericAddressingPolicy<INet4Address>
@@ -93,17 +150,26 @@ namespace senf {
using GenericAddressingPolicy<INet4Address>::bind;
};
- /** \brief
+ /** \brief Addressing policy supporting IPv6 addressing
+
+ \par Address Type:
+ INet6Address
+
+ This addressing policy implements addressing using Internet V6
+ addresses.
- \todo Implement
+ The various members are directly importet from
+ GenericAddressingPolicy which see for a detailed
+ documentation.
+
+ \todo implement
*/
struct INet6AddressingPolicy : public AddressingPolicyBase
{
typedef INet6Address Address;
};
- struct InvalidINetAddressException : public std::exception
- { char const * what() const throw() { return "invalid inet address"; } };
+ /// @}
}
@@ -118,4 +184,5 @@ namespace senf {
// Local Variables:
// mode: c++
// c-file-style: "senf"
+// fill-column: 100
// End:
diff --git a/Socket/INetProtocol.cc b/Socket/INetProtocol.cc
index 4fb2ff0ebd26a23f4fa9476afccb684187e69b40..40063693d31a954396984a5cc005aa3b7aa55faa 100644
--- a/Socket/INetProtocol.cc
+++ b/Socket/INetProtocol.cc
@@ -20,7 +20,8 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-// Definition of non-inline non-template functions
+/** \file
+ \brief INet[46]Protocol non-inline non-template implementation */
#include "INetProtocol.hh"
//#include "INetProtocol.ih"
diff --git a/Socket/INetProtocol.hh b/Socket/INetProtocol.hh
index 79a514c55669e00bbabc02c74df86abdbfc2bc54..482f88ed76ed2af49bbb13415fa5a2b0ad32f03e 100644
--- a/Socket/INetProtocol.hh
+++ b/Socket/INetProtocol.hh
@@ -21,11 +21,12 @@
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
/** \file
+ \brief IPv[46]Protocol public header
\todo what about OOB data?
\todo Implement IP_RECVERR / MSG_ERRQUEUE. This should be placed
- into an additional protocol class since IP_RECVERR is only valid
+ into an additional protocol facet since IP_RECVERR is only valid
for SOCK_DGRAM (UDP) and not SOCK_STREAM (TCP) sockets
*/
@@ -43,42 +44,98 @@
namespace senf {
+ /// \addtogroup protocol_facets_group
+ /// @{
- /** \brief
+ /** \brief Protocol facet providing IPv4 Addressing related API
+
+ This protocol facet introduces all the socket api protocol members which are related to IPv4
+ addressing.
- \todo Is it safe, not to allow setting the interface index on
- add/drop? what does it do (especially if the local addres is
- given ?). What have I been thinking here ???
+ \todo Is it safe, not to allow setting the interface index on add/drop? what does it do
+ (especially if the local addres is given ?). What have I been thinking here ???
- \todo move all multicast-methods into an extra
- IPv4MulticastProtocol class
+ \todo move all multicast-methods into an extra IPv4MulticastProtocol class (it's only
+ available on datagram sockets)
+
+ \todo the multicast add/remove/iface semantics are quite unclear ...
+
+ \todo connect() is only available on stream sockets. We want to access bind() and connet()
+ via the ClientSocketHandle -> see SocketProtocol todo point
*/
class IPv4Protocol
: public virtual SocketProtocol
{
public:
- void connect(INet4Address const & address) const;
- void bind(INet4Address const & address) const;
+ void connect(INet4Address const & address) const; ///< Connect to remote address
+ /**< \todo make this obsolete by allowing access to the
+ ClientSocketHandle from ConcreateSocketProtocol
+ \param[in] address Address to connect to */
+ void bind(INet4Address const & address) const; ///< Set local socket address
+ /**< \todo make this obsolete by allowing access to the
+ ClientSocketHandle from ConcreateSocketProtocol
+ \param[in] address Address to set */
- unsigned mcTTL() const;
- void mcTTL(unsigned value) const;
+ unsigned mcTTL() const; ///< Return current multicast TTL
+ void mcTTL(unsigned value) const; ///< Set multicast TTL
- bool mcLoop() const;
- void mcLoop(bool value) const;
+ bool mcLoop() const; ///< Return current multicast loopback state
+ void mcLoop(bool value) const; ///< Set multicast loopback state
void mcAddMembership(INet4Address const & mcAddr) const;
+ ///< Join multicast group
+ /**< This member will add \a mcAddr to the list of multicast
+ groups received. The group is joined on the default
+ interface.
+ \param[in] mcAddr address of group to join
+ \todo fix this as soon as we have a real address class
+ (differend from the sockaddress class */
void mcAddMembership(INet4Address const & mcAddr, INet4Address const & localAddr) const;
+ ///< join multicast group on a specific address/interface
+ /**< This member will add \a mcAddr to the list of multicast
+ groups received. The group is joined on the interface
+ with the given local address.
+ \param[in] mcAddr address of group to join
+ \param[in] localAddr address of interface to join on
+ \todo fix this as soon as we have a real address class
+ (differend from the sockaddress class */
void mcDropMembership(INet4Address const & mcAddr) const;
+ ///< Leave multicast group
+ /**< This member will remove \a mcAddr from the list of
+ multicast groups received. The group is left from the
+ default interface.
+ \param[in] mcAddr address of group to leave
+ \todo fix this as soon as we have a real address class
+ (differend from the sockaddress class */
void mcDropMembership(INet4Address const & mcAddr, INet4Address const & localAddr) const;
+ ///< leave multicast group on a specific address/interface
+ /**< This member will remove \a mcAddr from the list of
+ multicast groups received. The group is left from the
+ interface with the given local address.
+ \param[in] mcAddr address of group to leave
+ \param[in] localAddr address of interface to leave from
+ \todo fix this as soon as we have a real address class
+ (differend from the sockaddress class */
void mcIface(std::string iface = std::string()) const;
+ ///< set default multicast interface of the socket
+ /**< \param[in] iface name of interface */
};
+ /** \brief Protocol facet providing IPv6 Addressing related API
+
+ This protocol facet introduces all the socket api protocol members which are related to IPv6
+ addressing.
+
+ \todo implement
+ */
class IPv6Protocol
: public virtual SocketProtocol
{};
+ /// @}
+
}
///////////////////////////////hh.e////////////////////////////////////////
@@ -91,4 +148,5 @@ namespace senf {
// Local Variables:
// mode: c++
// c-file-style: "senf"
+// fill-column: 100
// End:
diff --git a/Socket/LLAddressing.cc b/Socket/LLAddressing.cc
index 262500d685fec9c88625a2b9efaa78b6f3e473ea..5616cae319701efd461d97ccc3f89bb80b2a22d8 100644
--- a/Socket/LLAddressing.cc
+++ b/Socket/LLAddressing.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 LLSocketAddress and LLAddressingPolicy non-inline non-template implementation
+ */
#include "LLAddressing.hh"
#include "LLAddressing.ih"
diff --git a/Socket/LLAddressing.cci b/Socket/LLAddressing.cci
index 228b474b7b9af12df421c486dee05745ada30646..00ed1a87ea07d99ec3c1cbfffb6433f95c4b6afb 100644
--- a/Socket/LLAddressing.cci
+++ b/Socket/LLAddressing.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 LLSocketAddress and LLAddressingPolicy inline non-template implementation
+ */
// Custom includes
#include <sys/socket.h>
diff --git a/Socket/LLAddressing.ct b/Socket/LLAddressing.ct
index c9b2086c4c811c71d804c8e33e5d5f86ae5589e5..4a9fbba719507682350106380a5fd09d15970a93 100644
--- a/Socket/LLAddressing.ct
+++ b/Socket/LLAddressing.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 LLSocketAddress and LLAddressingPolicy non-inline template implementation
+ */
#include "LLAddressing.ih"
diff --git a/Socket/LLAddressing.cti b/Socket/LLAddressing.cti
index e8ffd94c9b79b65e79b7a1facc100cca98c692c9..865a84a9e2e4235fabad3ef6094c7bb047ea6dc1 100644
--- a/Socket/LLAddressing.cti
+++ b/Socket/LLAddressing.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 LLSocketAddress and LLAddressingPolicy inline template implementation
+ */
#include "LLAddressing.ih"
diff --git a/Socket/LLAddressing.hh b/Socket/LLAddressing.hh
index e27ecff5d4c8866ad9a68b6a869087478fedb3b8..5a114a5b061c961e11c48dac79c6125f504d394d 100644
--- a/Socket/LLAddressing.hh
+++ b/Socket/LLAddressing.hh
@@ -20,6 +20,10 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+/** \file
+ \brief LLSocketAddress and LLAddressingPolicy public header
+ */
+
#ifndef HH_LLAddressing_
#define HH_LLAddressing_ 1
@@ -41,7 +45,27 @@
namespace senf {
+ /// \addtogroup addr_group
+ /// @{
+
+ /** \brief Link local address
+
+ LLSocketAddress wrapps the standard sockaddr_ll datatype.
+
+ \todo I don't think the current implementation is
+ sensible. I'll have to reimplement this class probably
+ from scratch.
+ \implementation The class relies uses a very flexible
+ 'ForwardRange' representation for a raw ll
+ address (See <a
+ href="http://www.boost.org/libs/range/index.html">Boost.Range</a>).
+ This representation allows zero-copy imlementations of
+ many operations, however it is probably not worth the
+ effort since the ll address is restricted to a max of 8
+ bytes. Therefore this will be changed and the concrete
+ implementation is not documented very well ...
+ */
class LLSocketAddress
{
public:
@@ -100,28 +124,58 @@ namespace senf {
struct ::sockaddr_ll addr_;
};
+ /** \brief
+ \related LLSocketAddress
+ */
detail::LLAddressFromStringRange llAddress(std::string address);
+
// The enable_if condition here allows only for classes as range.
// However, excluding zero-terminated strings (which we want to
// pass to above) I cannot think of a non-class ForwardRange
// except for academic cases
+ // STOP: ... how about std::vector<...>::iterator ?? isn't that a ..pointer ?
+ /** \brief Convert raw link-local address into printable form
+ \related LLSocketAddress
+ */
template <class ForwardRange>
std::string llAddress(ForwardRange const & address,
typename boost::enable_if< boost::is_class<ForwardRange> >::type * = 0);
- class LLAddressingPolicy
+ /** \brief Signal invalid link local address syntax
+ \related LLSocketAddress
+ */
+ struct InvalidLLSocketAddressException : public std::exception
+ { char const * what() const throw() { return "invalid ll address"; } };
+
+ /// @}
+
+ /// \addtogroup policy_impl_group
+ /// @{
+
+ /** \brief Addressing policy supporting link-local addressing
+
+ \par Address Type:
+ LLSocketAddress
+
+ This addressing policy implements generic link local
+ addressing. The predominant type of link local addressing is
+ Ethernet addressing.
+
+ Since the link layer does not support the notion of
+ connections, link local addresses do not support the connect()
+ or peer() members.
+ */
+ struct LLAddressingPolicy
: public AddressingPolicyBase,
private GenericAddressingPolicy<LLSocketAddress>
{
- public:
typedef LLSocketAddress Address;
using GenericAddressingPolicy<LLSocketAddress>::local;
using GenericAddressingPolicy<LLSocketAddress>::bind;
};
- struct InvalidLLSocketAddressException : public std::exception
- { char const * what() const throw() { return "invalid ll address"; } };
+ /// @}
}
///////////////////////////////hh.e////////////////////////////////////////
diff --git a/Socket/LLAddressing.ih b/Socket/LLAddressing.ih
index 004b293999b660a9e46be892422e02f1c26a1acb..6ab4f14e2fc4fb118a1358d4d26af33054d5278f 100644
--- a/Socket/LLAddressing.ih
+++ b/Socket/LLAddressing.ih
@@ -20,6 +20,9 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+/** \file
+ \brief LLSocketAddress and LLAddressingPolicy internal header
+ */
#ifndef IH_LLAddressing_
#define IH_LLAddressing_ 1
@@ -32,6 +35,9 @@ namespace senf {
namespace detail {
+ /** \brief Convert two-char hexbyte representation to numeric value
+ \internal
+ */
struct HexConverter {
typedef unsigned char result_type;
template <class ForwardRange>
@@ -42,6 +48,9 @@ namespace detail {
typedef boost::transform_iterator< HexConverter, StringSplitIterator > HexSplitIterator;
typedef boost::iterator_range<HexSplitIterator> LLAddressFromStringRange;
+ /** \brief convert single hex digit to numeric value
+ \internal
+ */
unsigned char hexnibble(char c);
}}
diff --git a/Socket/PacketSocketHandle.ih b/Socket/PacketSocketHandle.ih
index 62ead40354880718f0cec476705d967ceb48e23d..87fd4e195fb90772e4e2d410ddb7352e87e5ba87 100644
--- a/Socket/PacketSocketHandle.ih
+++ b/Socket/PacketSocketHandle.ih
@@ -35,12 +35,28 @@ namespace senf {
namespace detail {
+ /** \brief Abstract address copier
+ \internal
+
+ This class provides the abstract interface to copy a
+ link-local address to a destination address.
+ */
struct LLAddressCopier
{
virtual ~LLAddressCopier() {}
virtual unsigned operator()(unsigned char * target) const = 0;
};
+ /** \brief Implementation of LLAddressCopier to copy arbitrary Range
+ \internal
+
+ This implementation of the LLAddressCopier interface will copy
+ an arbitrary range to the target address. This class is used,
+ to convert the compile-time polymorphism of templates
+ (provided by the \c ForwardRange template argument) into
+ runtime polymorphism (provided by the abstract LLAddressCopier
+ interface).
+ */
template <class ForwardRange>
struct Range_LLAddressCopier
: public LLAddressCopier
diff --git a/Socket/ProtocolClientSocketHandle.mpp b/Socket/ProtocolClientSocketHandle.mpp
index 74231e6eaa9be5c070a7738bf66d7fa61052f903..8d2e6aafba1b0a3864631508bfba8a23c8427e23 100644
--- a/Socket/ProtocolClientSocketHandle.mpp
+++ b/Socket/ProtocolClientSocketHandle.mpp
@@ -33,7 +33,7 @@
#include <boost/preprocessor/cat.hpp>
// ///////////////////////////mpp.p////////////////////////////////////////
-#endif // /////////////////////////////////////////////////////////////////
+#elif BOOST_PP_IS_ITERATING // ////////////////////////////////////////////
// ////////////////////////////////////////////////////////////////////////
// Local Macros
@@ -43,7 +43,6 @@
#define mpp_CallParameters() BOOST_PP_ENUM_PARAMS(BOOST_PP_ITERATION(), a )
// ////////////////////////////////////////////////////////////////////////
-#if BOOST_PP_IS_ITERATING // //////////////////////////////////////////////
#if BOOST_PP_ITERATION_FLAGS()==1 // //////////////////////////////////////
// ////////////////////////////////////////////////////////////////////////
// senf::ProtocolClientSocketHandle<SocketProtocol>::
@@ -70,7 +69,6 @@ ProtocolClientSocketHandle( mpp_MethodParameters() )
// ////////////////////////////////////////////////////////////////////////
#endif // /////////////////////////////////////////////////////////////////
-#endif // /////////////////////////////////////////////////////////////////
// ////////////////////////////////////////////////////////////////////////
// Undefine local Macros
@@ -80,6 +78,7 @@ ProtocolClientSocketHandle( mpp_MethodParameters() )
#undef mpp_CallParameters
// ////////////////////////////////////////////////////////////////////////
+#endif // /////////////////////////////////////////////////////////////////
// ///////////////////////////mpp.e////////////////////////////////////////
diff --git a/Socket/SocketProtocol.hh b/Socket/SocketProtocol.hh
index 863dc4fd4e11b9113bb1b03dbed0814e91e9ce8f..ba2b5ed28371f8148bef57f7ef4b83ba23ddf4db 100644
--- a/Socket/SocketProtocol.hh
+++ b/Socket/SocketProtocol.hh
@@ -57,6 +57,9 @@
\see
\ref handle_group \n
\ref policy_group
+
+ \todo Complete the protocol interface implementations. Better distribution of members to
+ protocol facets and more precise distribution of functionality among the facets.
*/
/** \defgroup concrete_protocol_group Protocol Implementations (Concrete Protocol Classes)
@@ -73,6 +76,15 @@
of the protocol class to find the complete policy interface.
*/
+/** \defgroup protocol_facets_group Protocol Facets
+ \ingroup protocol_group
+
+ The protocol facets are classes used as building blocks to build concrete protocol classes. Each
+ protocol facet will implement some functional part of the protocol interface. The protocol
+ facets all inherit from SocketProtocol by public \e virtual inheritance. This ensures the
+ accessibility of the socket body from all facets.
+ */
+
#ifndef HH_SocketProtocol_
#define HH_SocketProtocol_ 1
diff --git a/Socket/TCPProtocol.cc b/Socket/TCPProtocol.cc
index 246eacd17cc6485a6dd277c8445ec6fb3ce3b9ab..4fe5678ee16c0c0557695622e5488b67453e5e51 100644
--- a/Socket/TCPProtocol.cc
+++ b/Socket/TCPProtocol.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 TCPProtocol non-inline non-template implementation
+ */
#include "TCPProtocol.hh"
//#include "TCPProtocol.ih"
diff --git a/Socket/TCPProtocol.hh b/Socket/TCPProtocol.hh
index 3dba9e291b34dbf1a26253ed6ca59cc74ce02f01..721a6d771403266704f198f014b316a04b938689 100644
--- a/Socket/TCPProtocol.hh
+++ b/Socket/TCPProtocol.hh
@@ -20,6 +20,10 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+/** \file
+ \brief TCPProtocol public header
+ */
+
#ifndef HH_TCPProtocol_
#define HH_TCPProtocol_ 1
@@ -31,20 +35,40 @@
namespace senf {
+ /// \addtogroup protocol_facets_group
+ /// @{
+ /** \brief Protocol facat to support TCP operations
+
+ This protocol facet provides all those protocol functions,
+ which are available on any TCP socket.
+ */
class TCPProtocol
: public virtual SocketProtocol
{
public:
- bool nodelay() const;
- void nodelay(bool value) const;
+ bool nodelay() const; ///< Check current \c SO_NODELAY status
+ void nodelay(bool value) const; ///< Set \c SO_NODELAY status
+ /**< Enabling \c SO_NODELAY will disable the NAGLE
+ algorithm (which aggregates multiple writes into a
+ single network packet). Enabling nodelay() optimizes
+ the repsonse time at the expense of the bandwidth
+ efficiency.
+ \param[in] value \c SO_NODELAY state */
+
+ unsigned siocinq() const; ///< Return current size of the input queue
+ unsigned siocoutq() const; ///< Return current size of the output queue
+
+ ///\name Abstract Interface Implementation
+ ///@{
- unsigned siocinq() const;
- unsigned siocoutq() const;
unsigned available() const;
bool eof() const;
+
+ ///@}
};
+ /// @}
}
///////////////////////////////hh.e////////////////////////////////////////
@@ -57,4 +81,5 @@ namespace senf {
// Local Variables:
// mode: c++
// c-file-style: "senf"
+// fill-column: 100
// End:
diff --git a/doclib/html-munge.xsl b/doclib/html-munge.xsl
index 2b81ca3b061b73b8167e0ec776249c6d92483d5d..644c5463ee14587f9119aac6960fa58c063447f7 100644
--- a/doclib/html-munge.xsl
+++ b/doclib/html-munge.xsl
@@ -51,4 +51,10 @@
</xsl:call-template>
</xsl:template>
+ <xsl:template match="table[descendant::td[@class='memItemLeft']]">
+ <xsl:call-template name="add-class">
+ <xsl:with-param name="class">members</xsl:with-param>
+ </xsl:call-template>
+ </xsl:template>
+
</xsl:stylesheet>
diff --git a/doclib/senf.css b/doclib/senf.css
index fc59ad809456135182c2ed99818dc6464b1cf423..740d06b00ae78c357337073e06647b26ec106f79 100644
--- a/doclib/senf.css
+++ b/doclib/senf.css
@@ -284,4 +284,8 @@ table.glossary tr td:first-child {
font-weight: bold;
white-space: nowrap;
padding-right: 10px;
+}
+
+table.members td:first-child {
+ width: 35%;
}
\ No newline at end of file