From: g0dil Date: Tue, 6 Feb 2007 09:57:08 +0000 (+0000) Subject: Add INPUT_FILTER support do Doxygen builder X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=5a5c6d7f0fae7ad6c0af49d7742955cb6cf618cf;p=senf.git Add INPUT_FILTER support do Doxygen builder Add HTML tidy postprocessing and error filtering to SENFScons doxygen method Add doclib/filter.pl INPUT_FILTER to fix example code indentation in the documentation Add a glossary to the Socket documentation Furthher Socket library docs (Protocol classes) git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@192 270642c3-0616-0410-b53a-bc976706d245 --- diff --git a/Mainpage.dox b/Mainpage.dox index 02fc964..5d0dbeb 100644 --- a/Mainpage.dox +++ b/Mainpage.dox @@ -37,7 +37,7 @@ /** \page usage Using the SENF framework - The SENF Framework is a collection of lossly coupled + The SENF Framework is a collection of loosely coupled modules. The libraries are heavily object oriented and template based. For compatibility reasons, the libraries are therefore built together with every project making use of the framework. @@ -65,7 +65,8 @@ \li Doxygen (http://www.doxygen.org) \li The \c dia diagram editor (http://www.gnome.org/projects/dia/) - \li \The c xsltproc XSLT processor (http://xmlsoft.org/XSLT/xsltproc2.html) + \li HTML \c tidy (http://tidy.sourceforge.net/) + \li \The \c xsltproc XSLT processor (http://xmlsoft.org/XSLT/xsltproc2.html) The library is only tested with gcc-3.4 and 4.0 on Linux. On other @@ -343,8 +344,8 @@ library. This library will provide efficient and convenient access to all protocol fields. It supports parsing as well as modifying and creating packets. It has default support - for the most important TCP protocols and is highly extensible - with new protocols. + for the most important internet protocols and is highly + extensible with new protocols. \li Go over the Utils library. It contains small helpers to simplify tasks like daemonization, exception handling, diff --git a/Socket/Mainpage.dox b/Socket/Mainpage.dox index 643cee8..29496dc 100644 --- a/Socket/Mainpage.dox +++ b/Socket/Mainpage.dox @@ -1,3 +1,5 @@ +namespace senf { + /** \mainpage The SENF Socket Library The Socket library provides a high level and object oriented @@ -30,7 +32,7 @@ /** \page usage Using the Socket Library Whenever you use the socket library, what you will be dealing with - are senf::FileHandle derived instances. The socket library relies + are FileHandle derived instances. The socket library relies on reference counting to automatically manage the underlying socket representation. This frees you of having to manage the socket lifetime explicitly. @@ -38,20 +40,20 @@ \section usage_create Creating a Socket Handle To create a new socket handle (opening a socket), you will need to - use senf::ProtocolClientSocketHandle or - senf::ProtocolServerSocketHandle. You will probably not use these + use ProtocolClientSocketHandle or + ProtocolServerSocketHandle. You will probably not use these templates as is but use proper typedefs (for example - senf::TCPv4ClientSocketHandle or senf::PacketSocketHandle). The + TCPv4ClientSocketHandle or PacketSocketHandle). The documentation for these socket handles are found in the protocol - class (for example senf::TCPv4SocketProtocol or - senf::PacketProtocol). + class (for example TCPv4SocketProtocol or + PacketProtocol). \section usage_reusable Writing Reusable Components To make your code more flexible, you should not pass around your socket in this form. Most of your code will be using only a small - subset of the senf::ProtocolClientSocketHandle or - senf::ProtocolServerSocketHandle API. If instead of using the + subset of the ProtocolClientSocketHandle or + ProtocolServerSocketHandle API. If instead of using the fully specified handle type you use a more incomplete type, you allow your code to be used with all socket which fulfill the minimal requirements of your code. @@ -60,21 +62,21 @@ your code: \code - typedef senf::ClientSocketHandle< - senf::MakeSocketPolicy< - senf::ReadablePolicy, - senf::StreamFramingPolicy, - senf::ConnectedCommunicationPolicy > > MyReadableHandle; + typedef ClientSocketHandle< + MakeSocketPolicy< + ReadablePolicy, + StreamFramingPolicy, + ConnectedCommunicationPolicy > > MyReadableHandle; \endcode - This defines \c MyReadableHandle as a senf::ClientSocketHandle + This defines \c MyReadableHandle as a ClientSocketHandle which will have only read functionality. Your code expects a stream interface (in contrast to a packet or datagram based interface). You will not have \c write or \c readfrom members. \c write will be disabled since the WritePolicy is unknown, \c readfrom will be disabled since a socket with the - senf::ConnectedCommunicationPolicy does not have a \c readfrom + ConnectedCommunicationPolicy does not have a \c readfrom member. */ @@ -98,24 +100,23 @@ Most protocols can be implemented by just implementing a new protocol class. The protocol class must be derived from - senf::ConcreteSocketProtocol and takes the socket policy (as - created by senf::MakeSocketPolicy) as a template argument. See the + ConcreteSocketProtocol and takes the socket policy (as + created by MakeSocketPolicy) as a template argument. See the documentation of this class for the interface. - \attention - You may want to use multiple inheritance as it is used in the - implementation of the standard protocols (See \ref - protocol_interface). You must however be extra careful to ensure, - that every class ultimately has senf::SocketPolicy as a public - \e virtual base. + \attention You may want to use multiple inheritance as it is used + in the implementation of the standard protocols (See \ref + protocol_group). You must however be extra careful to ensure, that + every class ultimately has SocketPolicy as a public \e + virtual base. After the protocol class has been defined, you will probably want to provide typedefs for the new protocol sockets. If the new protocol is connection oriented, this will be like - - typedef senf::ProtocolClientSocketHandle MyProtocolClientSocketHandle; - typedef senf::ProtocolServerSocketHandle MyProtocolServerSocketHandle; - + \code + typedef ProtocolClientSocketHandle MyProtocolClientSocketHandle; + typedef ProtocolServerSocketHandle MyProtocolServerSocketHandle; + \endcode \section extend_policy Extending the policy framework @@ -135,15 +136,15 @@ on the policy axis which is extended. Example: If you write a new write policy because your protocol does not use ordinary write() system calls but some protocol specific API, Then any - generic function relying on senf::WritablePolicy will \e not + generic function relying on WritablePolicy will \e not work with the new socket, since the socket does \e not have this policy, it has some other kind of write policy. Therefore you need to be careful of what you are doing. The first step is to find out, which policy you will have to implement. For - this, find the senf::ClientSocketHandle and/or - senf::ServerSocketHandle members you want to change (see \ref - senf::ClientSocketHandle and \ref senf::ServerSocketHandle). Not + this, find the ClientSocketHandle and/or + ServerSocketHandle members you want to change (see \ref + ClientSocketHandle and \ref ServerSocketHandle). Not all policy axis directly contribute to the SocketHandle interface. However, some policy members additionally depend on other policy axis (example: AddressingPolicy::connect is only @@ -153,11 +154,51 @@ \see policy_group */ +/** \page glossary Glossary + + + + + + + + + + + + + + + + + + + + + +
policy collection of policy classes, one for each + policy axis, instantiation of the SocketPolicy template
policy axis one aspect defined in the socket + policy, typedef and member of the SocketPolicy template
policy class implementation of a single policy + axis, class derived from the axis base class
complete policy socket policy where each + axis is specified completely
incomplete policy socket policy, where at + least one axis is not fully specified
protocol class definition of a protocol as a + class, class inheriting from ConcreteSocketProtocol.
protocol facet a class providing some subset of + the protocol interface, class derived from SocketProtocol but not + from ConcreteSocketProtocol
policy interface interface directly provided by + ClientSocketHandle/ServerSocketHandle and defined through the + policy
protocol interface interface provided by the + protocol class and accessible via the + ProtocolClientSocketHandle::protocol()/ProtocolServerSocketHandle::protocol() + member
+ */ + /** \page implementation Implementation notes \image html SocketLibrary-classes.png */ +} + // Local Variables: // mode: c++ diff --git a/Socket/PacketSocketHandle.hh b/Socket/PacketSocketHandle.hh index 1ab5e67..b8748ff 100644 --- a/Socket/PacketSocketHandle.hh +++ b/Socket/PacketSocketHandle.hh @@ -40,6 +40,8 @@ namespace senf { + /// \addtogroup concrete_protocol_group + /// @{ typedef MakeSocketPolicy< LLAddressingPolicy, @@ -48,32 +50,110 @@ namespace senf { ReadablePolicy, WriteablePolicy, SocketBufferingPolicy - >::policy Packet_Policy; + >::policy Packet_Policy; ///< Policy of PacketProtocol + /** \brief Raw Packet-Socket access (Linux) + + \par Socket Handle typedefs: + \ref PacketSocketHandle + + \par Protocol Interface: + ClientSocketHandle::read(), ClientSocketHandle::readfrom(), ClientSocketHandle::writeto(), + ClientSocketHandle::bind(), ClientSocketHandle::local(), ClientSocketHandle::rcvbuf(), + ClientSocketHandle::sndbuf() + + \par Address Type: + LLSocketAddress + + The PacketProtocol provides access to the linux packet socket API. This API gives access to + 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 + */ class PacketProtocol : public ConcreteSocketProtocol, public BSDSocketProtocol { public: enum SocketType { RawSocket, DatagramSocket }; - - void init_client(SocketType type = RawSocket, int protocol = -1) const; - - std::auto_ptr clone() const; - + ///< Socket types enum PromiscMode { Promiscuous, AllMulticast, None }; + ///< Interface modes - void promisc(std::string interface, PromiscMode mode) const; - // See LLSocketAddress for a discussion/rationale for - // ForwardRange here + ///\name Constructors + ///@{ + void init_client(SocketType type = RawSocket, int protocol = -1) const; + ///< Create packet socket + /**< The new socket will receive all packets of the given + IEEE 802.3 \a protocol. The socket will receive all + packets, if \a protocol is -1. + + If \a type is \c RawSocket, the packet will include the + link-level header (the Ethernet header). Sent packets + must already include a well formed ll header. + + If \a type is \c DatagramSocket, the link level header + will not be part of the packet data. The ll header will + be removed from received packets and a correct ll + header will be created on sent packets. + + \param[in] type socket type + \param[in] protocol IEEE 802.3 protocol number */ + ///@} + + ///\name Protocol Interface + ///@{ + void promisc(std::string interface, PromiscMode mode) const; + ///< Change interface mode + /**< This member will change the reception on the given + interface. The modes available are + +
+
\e None
No special mode set. Only receive + packets addressed to the interface or of joined + multicast groups
+
\e AllMulticast
Additionally receive all + multicast traffic
+
\e Promiscuous
Receive all packets on the + wire
+
+ + \param[in] interface interface to modify + \param[in] mode new interface mode */ + + // See LLSocketAddress for a discussion/rationale for ForwardRange here template void mcAdd(std::string interface, ForwardRange const & address) const; - template + ///< Enable reception of a multicast group + /**< mcAdd will join a new multicast group. The address + parameter is specified as an arbitrary forward range + (see Boost.Range) + of up to 8 bytes. This allows to initialize the + address from an arbitrary sources without excessive + copying. + + \param[in] interface interface with which to join + \param[in] address multicast address to join + + \see \ref LLSocketAddress */ + template void mcDrop(std::string interface, ForwardRange const & address) const; + ///< Disable reception of a multicast group + /**< \see \ref mcAdd() */ + ///@} + + ///\name Abstract Interface Implementation + ///@{ + std::auto_ptr clone() const; unsigned available() const; bool eof() const; + ///@} + private: template void do_mc(std::string interface, ForwardRange const & address, bool add) const; @@ -81,7 +161,10 @@ namespace senf { }; typedef ProtocolClientSocketHandle PacketSocketHandle; - + ///< SocketHandle of the PacketProtocol + /**< \related PacketPrototol */ + + /// @} } ///////////////////////////////hh.e//////////////////////////////////////// @@ -95,4 +178,5 @@ namespace senf { // Local Variables: // mode: c++ // c-file-style: "senf" +// fill-column: 100 // End: diff --git a/Socket/SocketHandle.hh b/Socket/SocketHandle.hh index 3bce2a3..d8f71de 100644 --- a/Socket/SocketHandle.hh +++ b/Socket/SocketHandle.hh @@ -112,64 +112,67 @@ namespace senf { void state(SocketStateMap & map, unsigned lod=0); ///< Inquire state information of socket handle /**< The map argument (a string to string mapping) will be - filled with information coverning the current state of - the socket. The information provided depends on the - socket protocol. The amount of information returned can - be controlled using the \p lod value. - - See senf::SocketProtocol::state() for more information, - how the Information is generated. - - \param map string to string mapping to be filled with - state information - \param lod level of detail requesten. The interpretation - of this value is protocol specific - - \implementation This member will be re-implemented in - every derived class. This is very important since state() - is \e not a virtual function (which we don't want since - we don't want to add a vtable pointer to every handle - instance). */ + filled with information coverning the current state of + the socket. The information provided depends on the + socket protocol. The amount of information returned can + be controlled using the \p lod value. + + See senf::SocketProtocol::state() for more information, + how the Information is generated. + + \param map string to string mapping to be filled with + state information + \param lod level of detail requesten. The interpretation + of this value is protocol specific + + \implementation This member will be re-implemented in + every derived class. This is very important since + state() is \e not a virtual function (which we + don't want since we don't want to add a vtable + pointer to every handle instance). */ std::string dumpState(unsigned lod=0); ///< Format complete state information as string /**< Formats the complete state map value and returns it as - a single multi-line string. + a single multi-line string. - \implementation This member will be re-implemented in - every derived class. See the state() documentation. */ + \implementation This member will be re-implemented in + every derived class. See the state() + documentation. */ protected: explicit SocketHandle(std::auto_ptr protocol, bool isServer); ///< Initialize SocketHandle providing the protocol /**< \param protocol Protocol class of the protocol implemented by this socket handle - \param isServer \c true, if this SocketHandle instance + \param isServer \c true, if this SobcketHandle instance implements a server handle, \c false otherwise */ SocketHandle(FileHandle other, bool isChecked); ///< Initialize SocketHandle from arbitrary checked ///< FileHandle /**< This constructor is used to support up- and downcasting - of SocketHandle instances. + of SocketHandle instances. - \warning It is absolutely necessary to ensure, that the - FileHandle passed in is \e really a SocketHandle holding - a SocketBody (and not a simple FileBody) - instance. Additionally. the SocketPolicy absolutely must - be compatible. + \warning It is absolutely necessary to ensure, that the + FileHandle passed in is \e really a SocketHandle + holding a SocketBody (and not a simple FileBody) + instance. Additionally. the SocketPolicy absolutely + must be compatible. - \param other FileHandle to assign - \param isChecked has to be \c true + \param other FileHandle to assign + \param isChecked has to be \c true - \todo Answer, why the heck I need the \c isChecked - parameter ?? + \todo Answer, why the heck I need the \c isChecked + parameter ?? */ SocketBody & body(); ///< Access socket body /**< This member replaces the corresponding FileHandle - member and returns an appropriately cast body reference */ + member and returns an appropriately cast body + reference */ SocketBody const & body() const; ///< Access socket body in const context /**< This member replaces the corresponding FileHandle - member and returns an appropriately cast body reference */ + member and returns an appropriately cast body + reference */ SocketProtocol const & protocol() const; ///< Access protocol class diff --git a/Socket/SocketPolicy.hh b/Socket/SocketPolicy.hh index 8dba18b..c0723b0 100644 --- a/Socket/SocketPolicy.hh +++ b/Socket/SocketPolicy.hh @@ -79,7 +79,7 @@ Every Policy value is identified by a class type. The policy classes themselves built an inheritance hierarchy for each policy axis. For each policy axis, the root of this tree is the class - named \i Policy \c Base (e.g. \p AddressingPolicyBase). + named \e Policy \c Base (e.g. \p AddressingPolicyBase). The senf::SocketPolicy defines the complete policy of a socket. It combines a set of policy classes, one for each policy @@ -143,7 +143,9 @@ checking, that it derives from SocketPolicyBase. This is simpler than chacking the template directly). -
\c template \c SocketPolicy < \e addressingPolicy, \e framingPolicy, \e communicationPolicy, \e readPolicy, \e writePolicy, \e bufferingPolicy >
+
\c template \c SocketPolicy < \e addressingPolicy, \e + framingPolicy, \e communicationPolicy, \e readPolicy, \e + writePolicy, \e bufferingPolicy >
This is the central SocketPolicy template. It combines a complete set of policy classes, one for each axis.
@@ -467,18 +469,34 @@ namespace senf { \internal - This class is used to + This class provides the baseclass of all socket policies + (bundles). It serves two purposes: + \li It allows us to easily identify a socket policy bundle by + checking a classes baseclass. + \li It provides an abstract (virtual) interface to access the + policy axes \see policy_group */ struct SocketPolicyBase - {}; + { + /** \brief Polymorphic access to policy axes + + This is an example of a policy axes accessor. It returns a + reference to the policy axes used by the conrecte protocol + bundle. This reference can then be checked using RTTI + information. + */ + AddressingPolicyBase const & theAddressingPolicy() const = 0; + }; /** \brief Collection of policy classes The SocketPolicy template defines the complete Policy used by the socket library. It contains one policy class for each - policy axis. + policy axis. This template takes one policy from each axis as + it's template arguments (this example implementation only has + AddressingPolicy as an argument). A SocketPolicy can be complete or incomplete. An incomplete SocketPolicy will have at least one axis set to \c Undefined @@ -490,15 +508,24 @@ namespace senf { \see policy_group */ - template < - class AddressingPolicy, - class FramingPolicy, - class CommunicationPolicy, - class ReadPolicy, - class WritePolicy, - class BufferingPolicy > + template < class AddressingPolicy > struct SocketPolicy - {}; + { + /** \brief Check dynamic policy compatibility + + This method will check the socket policy \a other against + this policy. It will check, wether \a other is a base + policy (or the same) of this policy. This check is done + against the \e dynamic type of \a other using RTTI. It + will throw \c std::bad_cast, if the policy is not + compatible. + + \param[in] other SocketPolicy to check + \throws std::bad_cast if \a other is not a compatible + policy + */ + static void checkBaseOf(SocketPolicyBase const & other); + }; /** \brief Metafunction to create SocketPolicy diff --git a/Socket/SocketProtocol.hh b/Socket/SocketProtocol.hh index 7b4b487..95e38e8 100644 --- a/Socket/SocketProtocol.hh +++ b/Socket/SocketProtocol.hh @@ -21,45 +21,55 @@ // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. /** \file - - \idea We should optimize the protocol handling. Allocating a - protocol instance for every socket body seems quite - wasteful. However I have no idea, how to access the socket - handle from within the protocol interface if the protocol - class is a singleton. Maybe, we'll have some other idea to - reduce the number of heap allocations (like deriving the - SocketProtocol class (private? protected?) from the - SocketBody. (private inheritance is a form of 'has-a' instead - of 'is-a' which would fit very well here). This would allow to - reduce the number of heap-allocations per socket to one which - is good. + + \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, + since private inheritance models more of 'has a' than 'is a'). This would allow to reduce + the number of heap-allocations per socket to one which is good. */ +// The private inheritance idea should indeed work very well: We just need to chnage the +// implementations of body() and protocol() and that of the ProtocolClient/ServerSocketHandle +// constructors and the SocketBody constructor. The body and the protocol would still be visible +// like several instances because of the private inheritance but we would save the backwards +// pointer. + /** \defgroup protocol_group The Protocol Classes \image html Protocols.png - The socket handle classes and templates only implement the most - important socket API methods using the policy framework. To access - the complete API, the protocol interface is provided. Access to - the protocol interface is only possible via - senf::ProtocolClientSocketHandle and - senf::ProtocolServerSocketHandle which have the necessary \c - protocol() member. This member returns a reference to the protocol - class instance which contains members covering all the API - functions (mostly setsockopt/getsockopt related calls but there - may be more, this is completely up to the implementor of the - protocol class) not found in the SocketHandle interface. The - protocol interface is specific to the protocol. It's - implementation is quite free. The standard protocols are - implemented using a simple multiple-inheritance hierarchy as shown - above. - - Since the protocol class is protocol specific (how intelligent - ...), the protocol class also defines the complete socket policy - to be used with it's protocol. Complete meaning, that every policy - axis must be assigned it's the most specific (that is derived) - policy class to be used with the protocol. + The socket handle classes and templates only implement the most important socket API methods + using the policy framework. To access the complete API, the protocol interface is + provided. Access to the protocol interface is only possible via senf::ProtocolClientSocketHandle + and senf::ProtocolServerSocketHandle which have the necessary \c protocol() member. This member + returns a reference to the protocol class instance which contains members covering all the API + functions (mostly setsockopt/getsockopt related calls but there may be more, this is completely + up to the implementor of the protocol class) not found in the SocketHandle interface. The + protocol interface is specific to the protocol. It's implementation is quite free. The standard + protocols are implemented using a simple multiple-inheritance hierarchy as shown above. + + Since the protocol class is protocol specific (how intelligent ...), the protocol class also + defines the complete socket policy to be used with it's protocol. Complete meaning, that every + policy axis must be assigned it's the most specific (that is derived) policy class to be used + with the protocol. + + \see + \ref handle_group \n + \ref policy_group + */ + +/** \defgroup concrete_protocol_group Protocol Implementations (Concrete Protocol Classes) + \ingroup protocol_group + + Theese protocol classes define concrete and complete protocol implementations. They inherit from + ConcreteSocketProtocol and are used with the ProtocolClientSocketHandle and + ProtocolServerSocketHandle templates to instantiate socket handles. Appropriate typedefs are + always provided. + + Every protocol defines both the protocol and the policy interface provided by that protocol. See + the documentation of the protocol classes listed below for more information on the supported + protocols. Every protocol class documents it's policy interface. Use the 'list all members' link + of the protocol class to find the complete policy interface. */ #ifndef HH_SocketProtocol_ @@ -80,6 +90,13 @@ namespace senf { class SocketPolicyBase; + /** \brief Socket protocol base class + + This is the base class of all socket protocol classes. Every protocol class must directly or + indirectly inherit from SocketProtocol + + \attention SocketProtocol must \e always be inherited using public \e virtual inheritance. + */ class SocketProtocol : boost::noncopyable { public: @@ -100,16 +117,77 @@ namespace senf { ///@} /////////////////////////////////////////////////////////////////////////// - SocketBody & body() const; + SocketBody & body() const; ///< Access the socket body + /**< \todo we don't need body(), we should better provide a + handle() member which will return a simple FIleHandle + object (we cannot return some other derived class since + we don't know the Protocol or Policy at this point) */ virtual SocketPolicyBase const & policy() const = 0; + ///< Access the policy instance /////////////////////////////////////////////////////////////////////////// // Virtual interface virtual std::auto_ptr clone() const = 0; + ///< Polymorphically return a copy of this protocol class + /**< This member will create a new copy of the protocol + class on the heap. + \attention This member must be implemented in every \e + leaf protocol class to return a new instance of the + appropriate type. */ virtual unsigned available() const = 0; - virtual bool eof() const = 0; + ///< Return number of bytes available for reading without + ///< blocking + /**< This member will check in a (very, sigh) protocol + deqpendent way, how many bytes are guarateed to be + readable from the socket without blocking even if the + socket is blocking. */ + + virtual bool eof() const = 0; ///< Check for end-of-file condition + /**< This is another check which (like available()) is + extremely protocol dependent. This member will return + \c true only, if at end-of-file. If the protocol does + not support the notion of EOF, this member should + always return \c false. */ virtual void state(SocketStateMap & map, unsigned lod) const; + ///< Return socket state information + /**< This member is called to add state information to the + status \a map. The protocol map should provide as + detailed information as possible. The amount of + information to be added to the map is selected by the + \a lod value with a default value of 0. The + interpretation of the \a lod value is completely + implementation defined. + + Every class derived from SocketProtocol should + reimplement state(). The reimplemented method should + call (all) baseclass-implementations of this + member. + + The \a map Argument is a map which associates + std:string keys with std:string-like values. The map + keys are interpreted as hierarchical strings with '.' + as a separator (like hostnames or struct or class + members). They are automatically sorted correctly. + + The values are std:string with one additional feature: + they allow assignment or conversion from *any* type as + long as that type is streamable. This simplifies + assigning non-string values to the map: + + \code + map["socket.protocol.ip.address"] = peer(); + map["socket.protocol.tcp.backlog"] = backlog(); + \endcode + + This will work even if peer() returns an ip-address + object or backlog() returns an integer. The values are + automatically converted to their string representation. + + The operator "+=" also has been reimplemented to + simplify adding multiple values to a single entry: It + will automatically add a ", " separator if the string + is non-empty. */ protected: @@ -119,6 +197,22 @@ namespace senf { friend class SocketBody; }; + + /** \brief Concrete socket protocol implementation base class + + ConcreteSocketProtocol is the base class of a concrete socket protocol implementation. The + final protocol class must inherit from ConcreteSocketProtocol. The template argument \a + SocketPolicy must be set to the complete socket policy of the protocol. + + A protocol implementation may define the protocol interface directly. It can also + (additnally) make use of multiple inheritance to combine a set of protocol facets into a + specific protocol implementation (i.e. TCPv4SocketProtocol inherits from + ConcreteSocketProtocol and from the protocol facets IPv4Protocol, TCPProtocol, + BSDSocketProtocol and AddressableBSDSocketProtocol). The protocol facets are not concrete + protocols themselves, they are combined to build concrete protocols. This structure will + remove a lot of code duplication. It is important to ensure, that the protocol facets do not + overlap, since otherwise there will be problems resolving overlapping members. + */ template class ConcreteSocketProtocol : public virtual SocketProtocol @@ -127,7 +221,7 @@ namespace senf { /////////////////////////////////////////////////////////////////////////// // Types - typedef SocketPolicy Policy; + typedef SocketPolicy Policy; ///< The protocols policy /////////////////////////////////////////////////////////////////////////// ///\name Structors and default members @@ -164,4 +258,5 @@ namespace senf { // Local Variables: // mode: c++ // c-file-style: "senf" +// fill-column: 100 // End: diff --git a/Socket/TCPSocketHandle.hh b/Socket/TCPSocketHandle.hh index b8354ca..a566d93 100644 --- a/Socket/TCPSocketHandle.hh +++ b/Socket/TCPSocketHandle.hh @@ -45,6 +45,8 @@ namespace senf { + /// \addtogroup concrete_protocol_group + /// @{ typedef MakeSocketPolicy< INet4AddressingPolicy, @@ -53,8 +55,10 @@ namespace senf { ReadablePolicy, WriteablePolicy, SocketBufferingPolicy - >::policy TCPv4Socket_Policy; + >::policy TCPv4Socket_Policy; ///< Socket Policy of the TCPv4 Protocol + /** \brief + */ class TCPv4SocketProtocol : public ConcreteSocketProtocol, public IPv4Protocol, @@ -66,12 +70,20 @@ namespace senf { /////////////////////////////////////////////////////////////////////////// // internal interface + ///\name Constructors + ///@{ + void init_client() const; void init_client(INet4Address const & address) const; void init_server() const; void init_server(INet4Address const & address, unsigned backlog=1) const; + ///@} + ///\name Abstract Interface Implementation + std::auto_ptr clone() const; + + ///@} }; typedef ProtocolClientSocketHandle TCPv4ClientSocketHandle; @@ -95,6 +107,8 @@ namespace senf { typedef ProtocolClientSocketHandle TCPv6ClientSocketHandle; typedef ProtocolServerSocketHandle TCPv6ServerSocketHandle; + /// @} + } ///////////////////////////////hh.e//////////////////////////////////////// diff --git a/doclib/Doxyfile.global b/doclib/Doxyfile.global index 900f6f0..c6dc176 100644 --- a/doclib/Doxyfile.global +++ b/doclib/Doxyfile.global @@ -3,6 +3,7 @@ INPUT = . FILE_PATTERNS = *.c *.cc *.cci *.ct *.cti *.h *.hh *.ih *.mpp *.dox EXCLUDE_PATTERNS = *.test.cc *.test.hh .* *~ "#*#" IMAGE_PATH = . +INPUT_FILTER = "$(TOPDIR)/doclib/filter.pl" ALIASES = "fixme=\xrefitem fixme \"Fix\" \"Fixmes\"" \ "idea=\xrefitem idea \"Idea\" \"Ideas\"" \ diff --git a/doclib/filter.pl b/doclib/filter.pl new file mode 100755 index 0000000..0fd65d3 --- /dev/null +++ b/doclib/filter.pl @@ -0,0 +1,8 @@ +#!/usr/bin/perl -n + +if (/^\s*\\code\s*$/ .. /\\endcode/) { + $i=length((/^(\s*)/)[0]) if /^\s*\\code\s*$/; + print substr($_,$i); +} else { + print; +} diff --git a/doclib/html-munge.xsl b/doclib/html-munge.xsl index ce977f4..2b81ca3 100644 --- a/doclib/html-munge.xsl +++ b/doclib/html-munge.xsl @@ -1,9 +1,17 @@ - + + + + + + + + + + @@ -43,11 +51,4 @@ - - - - - - - diff --git a/doclib/senf.css b/doclib/senf.css index 95d434d..fc59ad8 100644 --- a/doclib/senf.css +++ b/doclib/senf.css @@ -100,7 +100,17 @@ div.tabs ul li a:visited, div.tabs ul li a:active { text-decoration: none; } -div.tabs ul li a:hover, div.tabs ul li#current a { +div.tabs li.current a { + background-position: 100% -150px; + border-width : 0px; +} + +div.tabs li.current span { + background-position: 0% -150px; + padding-bottom : 6px; +} + +div.tabs ul li a:hover, div.tabs ul li.current a { color: #726921; text-decoration: none; background-color: #EDE497; @@ -255,4 +265,23 @@ div.qindex { dl.parameters dd table { width: auto; +} + +table.glossary { + border: none; + border-spacing: 0; +} + +table.glossary tr td { + border: none; + border-bottom: 4px solid white; + vertical-align: top; + padding: 2px 4px; + background-color: #F0F0F0; +} + +table.glossary tr td:first-child { + font-weight: bold; + white-space: nowrap; + padding-right: 10px; } \ No newline at end of file diff --git a/senfscons/Doxygen.py b/senfscons/Doxygen.py index f422aac..a853545 100644 --- a/senfscons/Doxygen.py +++ b/senfscons/Doxygen.py @@ -130,7 +130,7 @@ def DoxySourceScan(node, env, path): any files used to generate docs to the list of source files. """ dep_add_keys = ( - '@INCLUDE', 'HTML_HEADER', 'HTML_FOOTER', 'TAGFILES' + '@INCLUDE', 'HTML_HEADER', 'HTML_FOOTER', 'TAGFILES', 'INPUT_FILTER' ) default_file_patterns = ( diff --git a/senfscons/SENFSCons.py b/senfscons/SENFSCons.py index a9961d6..0484e56 100644 --- a/senfscons/SENFSCons.py +++ b/senfscons/SENFSCons.py @@ -175,7 +175,13 @@ def Doxygen(env, doxyfile = "Doxyfile", extra_sources = []): env.AddPostAction( docs, env.Action(("for html in %s/*.html; do " + - "xsltproc --nonet --html -o $${html}.new %s $${html} && mv $${html}.new $${html}; " + + " echo $$html;" + + " sed -e 's/id=\"current\"/class=\"current\"/' $${html}" + + " | tidy -ascii -q --show-warnings no" + + " | xsltproc --nonet --html -o $${html}.new %s - 2>&1" + + " | grep '^-'" + + " | grep -v 'ID .* already defined';" + + " mv $${html}.new $${html}; " + "done") % (htmlnode.dir.abspath, xslfile.abspath))) for doc in docs: