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 change 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
41 <map name="protocols">
42 <area shape="rect" alt="SocketPolicy" href="structsenf_1_1SocketPolicy.html" title="SocketPolicy" coords="416,50,536,68" />
43 <area shape="rect" alt="ConcreteSocketProtocol" href="classsenf_1_1ConcreteSocketProtocol.html" title="ConcreteSocketProtocol" coords="268,65,456,88" />
44 <area shape="rect" alt="SocketProtocol" href="classsenf_1_1SocketProtocol.html" title="SocketProtocol" coords="1,2,120,26" />
45 <area shape="rect" alt="BSDSocketProtocol" href="classsenf_1_1BSDSocketProtocol.html" title="BSDSocketProtocol" coords="124,118,276,143" />
46 <area shape="rect" alt="AddressableBSDSocketProtocol" href="classsenf_1_1AddressableBSDSocketProtocol.html" title="AddressableBSDSocketProtocol" coords="82,200,314,224" />
47 <area shape="rect" alt="IPv4Protocol" href="classsenf_1_1IPv4Protocol.html" title="IPv4Protocol" coords="149,272,252,296" />
48 <area shape="rect" alt="IPv6Protocol" href="classsenf_1_1IPv6Protocol.html" title="IPv6Protocol" coords="149,335,251,359" />
49 <area shape="rect" alt="TCPProtocol" href="classsenf_1_1TCPProtocol.html" title="TCPProtocol" coords="151,398,248,420" />
50 <area shape="rect" alt="TCPv4SocketProtocol" href="classsenf_1_1TCPv4SocketProtocol.html" title="TCPv4SocketProtocol" coords="288,471,405,494" />
51 <area shape="rect" alt="TCPv6SocketProtocol" href="classsenf_1_1TCPv6SocketProtocol.html" title="TCPv6SocketProtocol" coords="424,470,540,494" />
52 <area shape="rect" alt="PacketProtocol" href="classsenf_1_1PacketProtocol.html" title="PacketProtocol" coords="560,469,680,495" />
54 <img src="Protocols.png" border="0" alt="Protocols" usemap="#protocols">
57 The socket handle classes and templates only implement the most important socket API methods
58 using the policy framework. To access the complete API, the protocol interface is
59 provided. Access to the protocol interface is only possible via senf::ProtocolClientSocketHandle
60 and senf::ProtocolServerSocketHandle which have the necessary \c protocol() member. This member
61 returns a reference to the protocol class instance which contains members covering all the API
62 functions (mostly setsockopt/getsockopt related calls but there may be more, this is completely
63 up to the implementor of the protocol class) not found in the SocketHandle interface. The
64 protocol interface is specific to the protocol. It's implementation is quite free. The standard
65 protocols are implemented using a simple multiple-inheritance hierarchy as shown above.
67 Since the protocol class is protocol specific (how intelligent ...), the protocol class also
68 defines the \e complete socket policy to be used with it's protocol. Complete meaning, that
69 every policy axis must be assigned it's the most specific (that is derived) policy class to be
70 used with the protocol and that no policy axis is allowed to be left unspecified.
76 \todo Complete the protocol interface implementations. Better distribution of members to
77 protocol facets and more precise distribution of functionality among the facets.
80 /** \defgroup concrete_protocol_group Protocol Implementations (Concrete Protocol Classes)
81 \ingroup protocol_group
83 Theese protocol classes define concrete and complete protocol implementations. They inherit from
84 ConcreteSocketProtocol and are used with the ProtocolClientSocketHandle and
85 ProtocolServerSocketHandle templates to instantiate socket handles. Appropriate typedefs are
88 Every protocol defines both the protocol and the policy interface provided by that protocol. See
89 the documentation of the protocol classes listed below for more information on the supported
90 protocols. Every protocol class documents it's policy interface. Use the 'list all members' link
91 of the protocol class to find the complete policy interface.
94 /** \defgroup protocol_facets_group Protocol Facets
95 \ingroup protocol_group
97 The protocol facets are classes used as building blocks to build concrete protocol classes. Each
98 protocol facet will implement some functional part of the protocol interface. The protocol
99 facets all inherit from SocketProtocol by public \e virtual inheritance. This ensures the
100 accessibility of the socket body from all facets.
103 #ifndef HH_SocketProtocol_
104 #define HH_SocketProtocol_ 1
107 #include <boost/utility.hpp>
108 // Hrmpf ... I have tried very hard, but I just can't find a nice, generic way to clean
110 #include "SocketHandle.ih"
112 //#include "SocketProtocol.mpp"
113 ///////////////////////////////hh.p////////////////////////////////////////
117 /// \addtogroup protocol_group
120 class SocketPolicyBase;
122 /** \brief Socket Protocol base class
124 This is the base class of all socket protocol classes. Every protocol class must directly or
125 indirectly inherit from SocketProtocol
127 \attention SocketProtocol must \e always be inherited using public \e virtual inheritance.
133 ///////////////////////////////////////////////////////////////////////////
136 ///////////////////////////////////////////////////////////////////////////
137 ///\name Structors and default members
141 virtual ~SocketProtocol() = 0;
143 // default default constructor
145 // no conversion constructors
148 ///////////////////////////////////////////////////////////////////////////
150 virtual SocketPolicyBase const & policy() const = 0;
151 ///< Access the policy instance
153 ///////////////////////////////////////////////////////////////////////////
156 virtual std::auto_ptr<SocketProtocol> clone() const = 0;
157 ///< Polymorphically return a copy of this protocol class
158 /**< This member will create a new copy of the protocol
160 \attention This member must be implemented in every \e
161 leaf protocol class to return a new instance of the
164 virtual unsigned available() const = 0;
165 ///< Return number of bytes available for reading without
167 /**< This member will check in a (very, sigh) protocol
168 dependent way, how many bytes may be read from a socket
169 in a single (non-blocking) read operation. If the
170 socket does not support reading (viz. NotReadablePolicy
171 is set), this member should always return \c 0.
173 Depending on the protocol, it may not be possible to
174 return a good value. In this case, an upper bound may
175 be returned (e.g.: When reading from a socket which
176 returns ethernet frames, returning 1500 from
177 available() is ok). However, this should only be done
178 as a last resort. Also beware, that this number should
179 not be to large since the socket layer will always need
180 to allocate that number of bytes for the data to be
183 virtual bool eof() const = 0; ///< Check for end-of-file condition
184 /**< This is another check which (like available()) is
185 extremely protocol dependent. This member will return
186 \c true only, if at end-of-file. If the protocol does
187 not support the notion of EOF, this member should
188 always return \c false. */
190 virtual void close() const; ///< Close socket
191 /**< This override will automatically \c shutdown() the
192 socket whenever it is closed.
193 \throws senf::SystemException */
195 virtual void terminate() const; ///< Forcibly close socket
196 /**< This override will automatically \c shutdown() the
197 socket whenever it is called. Additionally it will
198 disable SO_LINGER to ensure, that v_terminate will not
199 block. Like the overriden method, this member will ignore
200 failures and will never throw. It is therefore safe to be
201 called from a destructor. */
203 virtual void state(SocketStateMap & map, unsigned lod) const;
204 ///< Return socket state information
205 /**< This member is called to add state information to the
206 status \a map. The protocol map should provide as
207 detailed information as possible. The amount of
208 information to be added to the map is selected by the
209 \a lod value with a default value of 0. The
210 interpretation of the \a lod value is completely
211 implementation defined.
213 Every class derived from SocketProtocol should
214 reimplement state(). The reimplemented method should
215 call (all) baseclass-implementations of this
218 The \a map Argument is a map which associates
219 std:string keys with std:string-like values. The map
220 keys are interpreted as hierarchical strings with '.'
221 as a separator (like hostnames or struct or class
222 members). They are automatically sorted correctly.
224 The values are std:string with one additional feature:
225 they allow assignment or conversion from *any* type as
226 long as that type is streamable. This simplifies
227 assigning non-string values to the map:
230 map["socket.protocol.ip.address"] << peer();
231 map["socket.protocol.tcp.backlog"] << backlog();
234 This will work even if peer() returns an ip-address
235 object or backlog() returns an integer. The values are
236 automatically converted to their string representation.
238 Additionally, if the slot the date is written to is not
239 empty, the <tt>\<\<</tt> operator will add add a comma
243 FileHandle fh() const; ///< Get a FileHandle for this instance
244 /**< This member will re turn a FileHandle instance for this
245 protocol instance. You may cast this FileHandle
246 instance to a ClientSocketHandle / ServerSocketHandle
247 as long as you know some of the socket policy using
248 static_socket_cast or dynamic_socket_cast */
250 int fd() const; ///< Get file descriptor
251 /**< Returns the file descriptor this protocol instance
252 references. This is the same as <tt>fh().fd()</tt> but
253 is implemented here since it is needed so often. */
255 void fd(int) const; ///< Initialize file descriptor
256 /**< Assigns the file descriptor to the file handle, this
257 protocol instance references. Only valid, if the file
258 handle has not yet been assigned any descriptor (To
259 change the file descriptor association later, use \c
263 // backpointer to owning SocketBody instance
265 SocketBody & body() const;
268 friend class SocketBody;
272 /** \brief Concrete Socket Protocol implementation base class
274 ConcreteSocketProtocol is the base class of a concrete socket protocol implementation. The
275 final protocol class must inherit from ConcreteSocketProtocol. The template argument \a
276 SocketPolicy must be set to the complete socket policy of the protocol.
278 A protocol implementation may define the protocol interface directly. It can also
279 (additionally) make use of multiple inheritance to combine a set of protocol facets into a
280 specific protocol implementation (i.e. TCPv4SocketProtocol inherits from
281 ConcreteSocketProtocol and from the protocol facets IPv4Protocol, TCPProtocol,
282 BSDSocketProtocol and AddressableBSDSocketProtocol). The protocol facets are not concrete
283 protocols themselves, they are combined to build concrete protocols. This structure will
284 remove a lot of code duplication. It is important to ensure, that the protocol facets do not
285 overlap, since otherwise there will be problems resolving overlapping members.
287 \doc init_client init_server
289 template <class SocketPolicy>
290 class ConcreteSocketProtocol
291 : public virtual SocketProtocol
294 ///////////////////////////////////////////////////////////////////////////
297 typedef SocketPolicy Policy; ///< The protocols policy
299 ///////////////////////////////////////////////////////////////////////////
300 ///\name Structors and default members
303 ~ConcreteSocketProtocol() = 0;
305 // no default constructor
307 // no conversion constructors
310 ///////////////////////////////////////////////////////////////////////////
312 Policy const & policy() const;
324 ///////////////////////////////hh.e////////////////////////////////////////
325 #include "SocketProtocol.cci"
326 //#include "SocketProtocol.ct"
327 #include "SocketProtocol.cti"
334 // c-file-style: "senf"
335 // indent-tabs-mode: nil
336 // ispell-local-dictionary: "american"
337 // compile-command: "scons -u test"
338 // comment-column: 40