4 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
5 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
6 // Stefan Bund <stefan.bund@fokus.fraunhofer.de>
8 // This program is free software; you can redistribute it and/or modify
9 // it under the terms of the GNU General Public License as published by
10 // the Free Software Foundation; either version 2 of the License, or
11 // (at your option) any later version.
13 // This program is distributed in the hope that it will be useful,
14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 // GNU General Public License for more details.
18 // You should have received a copy of the GNU General Public License
19 // along with this program; if not, write to the
20 // Free Software Foundation, Inc.,
21 // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
24 \brief SocketProtocol and ConcreteSocketProtocol public header
26 \idea We should optimize the protocol handling. Allocating a protocol instance for every socket
27 body seems quite wasteful. We could derive SocketPolicy from SocketBody (probably privately,
28 since private inheritance models more of 'has a' than 'is a'). This would allow to reduce
29 the number of heap-allocations per socket to one which is good.
32 // The private inheritance idea should indeed work very well: We just need to chnage the
33 // implementations of body() and protocol() and that of the ProtocolClient/ServerSocketHandle
34 // constructors and the SocketBody constructor. The body and the protocol would still be visible
35 // like several instances because of the private inheritance but we would save the backwards
38 /** \defgroup protocol_group The Protocol Classes
40 \image html Protocols.png
42 The socket handle classes and templates only implement the most important socket API methods
43 using the policy framework. To access the complete API, the protocol interface is
44 provided. Access to the protocol interface is only possible via senf::ProtocolClientSocketHandle
45 and senf::ProtocolServerSocketHandle which have the necessary \c protocol() member. This member
46 returns a reference to the protocol class instance which contains members covering all the API
47 functions (mostly setsockopt/getsockopt related calls but there may be more, this is completely
48 up to the implementor of the protocol class) not found in the SocketHandle interface. The
49 protocol interface is specific to the protocol. It's implementation is quite free. The standard
50 protocols are implemented using a simple multiple-inheritance hierarchy as shown above.
52 Since the protocol class is protocol specific (how intelligent ...), the protocol class also
53 defines the complete socket policy to be used with it's protocol. Complete meaning, that every
54 policy axis must be assigned it's the most specific (that is derived) policy class to be used
62 /** \defgroup concrete_protocol_group Protocol Implementations (Concrete Protocol Classes)
63 \ingroup protocol_group
65 Theese protocol classes define concrete and complete protocol implementations. They inherit from
66 ConcreteSocketProtocol and are used with the ProtocolClientSocketHandle and
67 ProtocolServerSocketHandle templates to instantiate socket handles. Appropriate typedefs are
70 Every protocol defines both the protocol and the policy interface provided by that protocol. See
71 the documentation of the protocol classes listed below for more information on the supported
72 protocols. Every protocol class documents it's policy interface. Use the 'list all members' link
73 of the protocol class to find the complete policy interface.
76 #ifndef HH_SocketProtocol_
77 #define HH_SocketProtocol_ 1
80 #include <boost/utility.hpp>
81 /** \fixme this is not nice. The includes and predefs should be restructured */
82 #include "SocketHandle.ih"
84 //#include "SocketProtocol.mpp"
85 ///////////////////////////////hh.p////////////////////////////////////////
89 /// \addtogroup protocol_group
92 class SocketPolicyBase;
94 /** \brief Socket protocol base class
96 This is the base class of all socket protocol classes. Every protocol class must directly or
97 indirectly inherit from SocketProtocol
99 \attention SocketProtocol must \e always be inherited using public \e virtual inheritance.
101 class SocketProtocol : boost::noncopyable
104 ///////////////////////////////////////////////////////////////////////////
107 ///////////////////////////////////////////////////////////////////////////
108 ///\name Structors and default members
112 virtual ~SocketProtocol() = 0;
114 // default default constructor
116 // no conversion constructors
119 ///////////////////////////////////////////////////////////////////////////
121 SocketBody & body() const; ///< Access the socket body
122 /**< \todo we don't need body(), we should better provide a
123 handle() member which will return a simple FIleHandle
124 object (we cannot return some other derived class since
125 we don't know the Protocol or Policy at this point) */
126 virtual SocketPolicyBase const & policy() const = 0;
127 ///< Access the policy instance
129 ///////////////////////////////////////////////////////////////////////////
132 virtual std::auto_ptr<SocketProtocol> clone() const = 0;
133 ///< Polymorphically return a copy of this protocol class
134 /**< This member will create a new copy of the protocol
136 \attention This member must be implemented in every \e
137 leaf protocol class to return a new instance of the
139 virtual unsigned available() const = 0;
140 ///< Return number of bytes available for reading without
142 /**< This member will check in a (very, sigh) protocol
143 deqpendent way, how many bytes are guarateed to be
144 readable from the socket without blocking even if the
145 socket is blocking. */
147 virtual bool eof() const = 0; ///< Check for end-of-file condition
148 /**< This is another check which (like available()) is
149 extremely protocol dependent. This member will return
150 \c true only, if at end-of-file. If the protocol does
151 not support the notion of EOF, this member should
152 always return \c false. */
153 virtual void state(SocketStateMap & map, unsigned lod) const;
154 ///< Return socket state information
155 /**< This member is called to add state information to the
156 status \a map. The protocol map should provide as
157 detailed information as possible. The amount of
158 information to be added to the map is selected by the
159 \a lod value with a default value of 0. The
160 interpretation of the \a lod value is completely
161 implementation defined.
163 Every class derived from SocketProtocol should
164 reimplement state(). The reimplemented method should
165 call (all) baseclass-implementations of this
168 The \a map Argument is a map which associates
169 std:string keys with std:string-like values. The map
170 keys are interpreted as hierarchical strings with '.'
171 as a separator (like hostnames or struct or class
172 members). They are automatically sorted correctly.
174 The values are std:string with one additional feature:
175 they allow assignment or conversion from *any* type as
176 long as that type is streamable. This simplifies
177 assigning non-string values to the map:
180 map["socket.protocol.ip.address"] = peer();
181 map["socket.protocol.tcp.backlog"] = backlog();
184 This will work even if peer() returns an ip-address
185 object or backlog() returns an integer. The values are
186 automatically converted to their string representation.
188 The operator "+=" also has been reimplemented to
189 simplify adding multiple values to a single entry: It
190 will automatically add a ", " separator if the string
196 // backpointer to owning SocketBody instance
198 friend class SocketBody;
202 /** \brief Concrete socket protocol implementation base class
204 ConcreteSocketProtocol is the base class of a concrete socket protocol implementation. The
205 final protocol class must inherit from ConcreteSocketProtocol. The template argument \a
206 SocketPolicy must be set to the complete socket policy of the protocol.
208 A protocol implementation may define the protocol interface directly. It can also
209 (additnally) make use of multiple inheritance to combine a set of protocol facets into a
210 specific protocol implementation (i.e. TCPv4SocketProtocol inherits from
211 ConcreteSocketProtocol and from the protocol facets IPv4Protocol, TCPProtocol,
212 BSDSocketProtocol and AddressableBSDSocketProtocol). The protocol facets are not concrete
213 protocols themselves, they are combined to build concrete protocols. This structure will
214 remove a lot of code duplication. It is important to ensure, that the protocol facets do not
215 overlap, since otherwise there will be problems resolving overlapping members.
217 template <class SocketPolicy>
218 class ConcreteSocketProtocol
219 : public virtual SocketProtocol
222 ///////////////////////////////////////////////////////////////////////////
225 typedef SocketPolicy Policy; ///< The protocols policy
227 ///////////////////////////////////////////////////////////////////////////
228 ///\name Structors and default members
231 ~ConcreteSocketProtocol() = 0;
233 // no default constructor
235 // no conversion constructors
238 ///////////////////////////////////////////////////////////////////////////
240 Policy const & policy() const;
252 ///////////////////////////////hh.e////////////////////////////////////////
253 #include "SocketProtocol.cci"
254 //#include "SocketProtocol.ct"
255 #include "SocketProtocol.cti"
261 // c-file-style: "senf"