From: g0dil Date: Thu, 8 Feb 2007 12:50:27 +0000 (+0000) Subject: Complete Socket library documentation X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=a4911c1fd3f53dc2a7bda6c1d2b00bdc4b864cff;p=senf.git Complete Socket library documentation Set fixed column width in member docs git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@195 270642c3-0616-0410-b53a-bc976706d245 --- diff --git a/Socket/BSDSocketProtocol.cc b/Socket/BSDSocketProtocol.cc index d8f5163..fe9fd1d 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 39d19d8..e924ef9 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 linger() const; - void linger(bool enable, unsigned timeout) const; + std::pair 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 8fdf27b..d35e993 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 0260dbb..1c63523 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 f4e8216..cc5c527 100644 --- a/Socket/GenericAddressingPolicy.hh +++ b/Socket/GenericAddressingPolicy.hh @@ -66,6 +66,10 @@ namespace senf { address. The underlying socket address stored at that pointer might be modified. + 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 7e1b437..6c1072d 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 +// +// 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 3081cc5..d96bd93 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 81ac9f1..688cbb5 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 diff --git a/Socket/INetAddressing.hh b/Socket/INetAddressing.hh index 9b8b160..d87f71f 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 @@ -93,17 +150,26 @@ namespace senf { using GenericAddressingPolicy::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 4fb2ff0..4006369 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 79a514c..482f88e 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 262500d..5616cae 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 228b474..00ed1a8 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 diff --git a/Socket/LLAddressing.ct b/Socket/LLAddressing.ct index c9b2086..4a9fbba 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 e8ffd94..865a84a 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 e27ecff..5a114a5 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 Boost.Range). + 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 std::string llAddress(ForwardRange const & address, typename boost::enable_if< boost::is_class >::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 { - public: typedef LLSocketAddress Address; using GenericAddressingPolicy::local; using GenericAddressingPolicy::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 004b293..6ab4f14 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 @@ -42,6 +48,9 @@ namespace detail { typedef boost::transform_iterator< HexConverter, StringSplitIterator > HexSplitIterator; typedef boost::iterator_range 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 62ead40..87fd4e1 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 struct Range_LLAddressCopier : public LLAddressCopier diff --git a/Socket/ProtocolClientSocketHandle.mpp b/Socket/ProtocolClientSocketHandle.mpp index 74231e6..8d2e6aa 100644 --- a/Socket/ProtocolClientSocketHandle.mpp +++ b/Socket/ProtocolClientSocketHandle.mpp @@ -33,7 +33,7 @@ #include // ///////////////////////////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:: @@ -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 863dc4f..ba2b5ed 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 246eacd..4fe5678 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 3dba9e2..721a6d7 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 2b81ca3..644c546 100644 --- a/doclib/html-munge.xsl +++ b/doclib/html-munge.xsl @@ -51,4 +51,10 @@ + + + members + + + diff --git a/doclib/senf.css b/doclib/senf.css index fc59ad8..740d06b 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