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 ClientSocketHandle public header
27 #ifndef HH_ClientSocketHandle_
28 #define HH_ClientSocketHandle_ 1
31 #include <boost/call_traits.hpp>
32 #include <boost/range.hpp>
33 #include "SocketHandle.hh"
35 //#include "ClientSocketHandle.mpp"
36 ///////////////////////////////hh.p////////////////////////////////////////
40 /// \addtogroup handle_group
43 template <class Policy> class ServerSocketHandle;
45 /** \brief Generic SocketHandle with client interface
47 This class provides the client side policy interface of the socket
48 abstraction. ClientSocketHandle defines the complete policy interface. It does not implement
49 any functionality itself however. All calls are forward to the following policy classes:
52 <tr><th>ClientSocketHandle member</th> <th>Policy member</th></tr>
53 <tr><td>read()</td> <td>ReadPolicy::read (\ref senf::ReadPolicyBase)</td></tr>
54 <tr><td>readfrom()</td> <td>ReadPolicy::readfrom (\ref senf::ReadPolicyBase)</td></tr>
55 <tr><td>write()</td> <td>WritePolicy::write (\ref senf::WritePolicyBase)</td></tr>
56 <tr><td>writeto()</td> <td>WritePolicy::writeto (\ref senf::WritePolicyBase)</td></tr>
57 <tr><td>connect()</td> <td>AddressingPolicy::connect (\ref senf::AddressingPolicyBase)</td></tr>
58 <tr><td>bind()</td> <td>AddressingPolicy::bind (\ref senf::AddressingPolicyBase)</td></tr>
59 <tr><td>peer()</td> <td>AddressingPolicy::peer (\ref senf::AddressingPolicyBase)</td></tr>
60 <tr><td>local()</td> <td>AddressingPolicy::local (\ref senf::AddressingPolicyBase)</td></tr>
61 <tr><td>rcvbuf()</td> <td>BufferingPolicy::sndbuf (\ref senf::BufferingPolicyBase)</td></tr>
62 <tr><td>sndbuf()</td> <td>BufferingPolicy::rcvbuf (\ref senf::BufferingPolicyBase)</td></tr>
65 It is important to note, that not all members are always accessible. Which are depends on
66 the \c Policy template argument. If any of the policy axis is left unspecified the
67 corresponding members will not be callable (you will get a compile time error). Even if
68 every policy axis is defined, some members might (and will) not exist if they are
69 meaningless for the protocol of the socket. This depends on the exact policy.
71 To find out, which members are available, you have to check the documentation of the policy
72 classes. You can also find a summary of all members available in the leaf protocol class
75 \todo Move all not template-parameter dependent code into a non-template base class
77 \idea Give SocketHandle (and therefore ClientSocketHandle and ServerSocketHandle) a \c
78 protocol() template member and an additional template arg \c Policies. This arg should be a
79 typelist of Poclicy classes which can be accessed. You use protocol<ProtocolClass>() to
80 access a protocol class. \c Policies can of course be underspecified or even empty.
82 \see \ref policy_group \n
85 \fixme Add enable_if conditions so anything convertible to unsigned will not be interpreted
86 as a Range template argument but will use the unsigned variant of
87 read/readfrom/write/writeto.
89 template <class Policy>
90 class ClientSocketHandle
91 : public SocketHandle<Policy>
94 ///////////////////////////////////////////////////////////////////////////
97 /// Address type from the addressing policy
98 typedef typename Policy::AddressingPolicy::Address Address;
99 /// 'Best' type for passing address as parameter
100 /** Depending on the type of \c Address, this will be either <tt>Address</tt> or <tt>Address
102 href="http://www.boost.org/libs/utility/call_traits.htm">call_traits documentation in
103 the Boost.Utility library.</a>
105 typedef typename boost::call_traits<Address>::param_type AddressParam;
106 /// Corresponding server socket handle with the same policy
107 /** This class will probably only be usable, if the \c CommunicationPolicy is \c
108 ConnectedCommunicationPolicy and the \c AddressingPolicy is not \c
109 NoAddressingPolicy. */
110 typedef ServerSocketHandle<Policy> ServerSocketHandle;
112 ///////////////////////////////////////////////////////////////////////////
113 ///\name Structors and default members
116 // default default constructor
117 // default copy constructor
118 // default copy assignment
119 // default destructor
122 ClientSocketHandle();
124 // conversion constructors
125 template <class OtherPolicy>
126 ClientSocketHandle(ClientSocketHandle<OtherPolicy> other,
127 typename SocketHandle<Policy>::template IsCompatible<OtherPolicy>::type * = 0);
129 template <class OtherPolicy>
130 typename SocketHandle<Policy>::template IsCompatible<OtherPolicy>::type const &
131 operator=(ClientSocketHandle<OtherPolicy> other);
134 ///////////////////////////////////////////////////////////////////////////
136 ///////////////////////////////////////////////////////////////////////////
137 ///\name Reading and Writing
140 /** \brief Read data from socket
142 If the sockets \c FramingPolicy is \c DatagramFramingPolicy, every read() command will
143 return a single datagram. If the sockets FramingPolicy is StreamFraming, the operation
144 will return as much data as possible from the socket buffer. However it cannot be
145 guaranteed, that the socket buffer will be empty after read() returns.
147 \attention If the space available for the data read is limited, the read will return no
148 more than that amount of data. For a datagram socket, a full datagram is still dequeued
149 from the socket buffer, the remainder of the datagram will be lost.
151 There are several variants of read which differ in how they return the read string.
153 If the further document doesn't tell something differently, on a blocking socket the
154 members will \e always return some data (as long as the socket has not been closed at
155 the other end) and will block, if no data is available now. If you do not want to block,
156 you \e must make the socket non-blocking (using FileHandle::blocking()).
158 \throws senf::SystemException
161 This variant will read up to \c limit bytes from the
162 socket and return them as a \c std::string object.
164 \param[in] limit Maximum number of bytes to read or 0 if unlimited.
167 \implementation The read() family of members will use standard POSIX \c read calls, not
170 std::string read (unsigned limit=0);
171 template <class ForwardWritableRange>
172 typename boost::range_iterator<ForwardWritableRange>::type
173 read (ForwardWritableRange const & range);
174 ///< Read data into range
175 /**< Read data into the given range. At most
176 <tt>boost::size(range)</tt> characters are read. The
177 data read will start at the beginning of the
178 range. read returns a past-the-end iterator after the
179 last character read. This iterator will point to
180 somewhere within the input range.
181 \param[in,out] range Range to store data in
182 \returns past-the-end iterator pointer to after the
185 <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a> */
186 template <class ForwardWritableRange>
187 typename boost::range_iterator<ForwardWritableRange>::type
188 read (ForwardWritableRange & range);
189 ///< Read data into range
190 /**< \see read(ForwardWritableRange const &) \n
192 <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a> */
193 template <class Sequence>
194 void read (Sequence & container, unsigned limit);
195 ///< Read data into container
196 /**< The data read is written into the given container. Old
197 data in the container will be removed. For this to
198 work, the container must be a model of 'Sequence' as
199 defined in the STL documentation
200 \param[out] container Container to write data to
201 \param[in] limit Maximum number of characters to read
203 char * read (char * start, char * end);
204 ///< Read data into memory area
205 /**< This variant will read data into the memory area from
206 \a start to before \a end. This is guaranteed to be the
207 most efficient version of read().
208 \param[in] start address of buffer to store data at
209 \param[in] end address one past the end of the buffer
210 \returns pointer past the end of the data read
213 /** \brief Read data from unconnected socket returning address
215 The readfrom() group of member behaves like \ref read() but should only be available, if
216 the sockets \c CommunicationPolicy is \c UnconnectedCommunicationPolicy and the \c
217 AddressingPolicy is not \c NoAddressingPolicy. readfrom() will in addition to the data
218 return the address of the sender.
220 \throws senf::SystemException
223 This variant will return the data read and the address as a std::pair.
225 \returns \c std::pair of data read (a string) and the peers address
227 \implementation The readfrom() family of members will use \c recvfrom from the BSD
230 std::pair<std::string, Address>
231 readfrom (unsigned limit=0);
232 template <class ForwardWritableRange>
233 typename boost::range_iterator<ForwardWritableRange const>::type
234 readfrom (ForwardWritableRange const & range, Address & from);
235 ///< Read data into range
236 /**< Read data into the given range. At most
237 <tt>boost::size(range)</tt> characters are read. The
238 data read will start at the beginning of the
239 range. read returns a past-the-end iterator after the
240 last character read. This iterator will point to
241 somewhere within the input range.
242 \param[in,out] range Range to store data in
243 \param[out] from peers address from which the data was
245 \returns past-the-end iterator pointer to after the
247 \see \ref readfrom() \n
248 <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a> */
249 template <class ForwardWritableRange>
250 typename boost::range_iterator<ForwardWritableRange>::type
251 readfrom (ForwardWritableRange & range, Address & from);
252 ///< Read data into range
253 /**< \see readfrom(ForwardWritableRange const&,Address&) \n
255 <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a> */
256 template <class Sequence>
257 void readfrom (Sequence & container, Address & from, unsigned limit);
258 ///< Read data into container
259 /**< The data read is written into the given container. Old
260 data in the container will be removed. For this to
261 work, the container must be a model of 'Sequence' as
262 defined in the STL documentation
263 \param[out] container Container to write data to
264 \param[in] limit Maximum number of characters to read
265 \param[out] from peers address from which the data was
267 \see \ref readfrom() */
268 char * readfrom (char * start, char * end, Address & from);
269 ///< Read data into memory buffer
270 /**< This variant will read data into the memory area from
271 \a start to before \a end. This is guaranteed to be the
272 most efficient version of readfrom().
273 \param[in] start address of buffer to store data at
274 \param[in] end address one past the end of the buffer
275 \param[out] from peers address from which the data was
277 \returns pointer past the end of the data read
281 /** \brief Write data to socket
283 The write() family of members will write out the data to the socket. If the sockets \c
284 FramingPolicy is \c DatagramFramingPolicy, every write() call will result in one
287 A single write call might depending on the circumstances write only part of the data.
289 There are two variants of this member
291 \throws senf::SystemException
294 This variant will write out the range \c data.
296 \param[in] range Data to write
297 \returns past-the-end iterator after last element written
298 \implementation The write() family of members will use POSIX \c write calls, not \c
301 template <class ForwardReadableRange>
302 typename boost::range_const_iterator<ForwardReadableRange const>::type
303 write (ForwardReadableRange const & range);
304 char const * write (char const * start, char const * end);
305 ///< Write data to socket from memory buffer
306 /**< \param[in] start beginning of area to write
307 \param[in] end past-the-end pointer to area to write
308 \returns past-the-end pointer after last byte written
310 <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a> */
312 /** \brief Write data to unconnected socket
314 This member behaves like write() but should only be available, if the sockets \c
315 CommunicationPolicy is \c UnconnectedCommunicationPolicy and the \c AddressingPolicy is
316 not \c NoAddressingPolicy. The writeto() family of members takes the target address as
317 an additional argument.
319 There are two variants of this member.
321 \throw senf::SystemException
324 This variant will send the range \c range to peer \c addr.
326 \param[in] addr Address of peer to send data to
327 \param[in] range data to send
328 \returns Number of bytes written
330 template <class ForwardReadableRange>
331 typename boost::range_const_iterator<ForwardReadableRange const>::type
332 writeto (AddressParam addr, ForwardReadableRange const & range);
333 char const * writeto (AddressParam addr, char const * start, char const * end);
334 ///< Write data from memory buffer to unconnected socket
335 /**< \param[in] addr Address of peer to send data to
336 \param[in] start address of buffer to write
337 \param[in] end past-the-end pointer after data to write
338 \returns past-the-end iterator after last byte written
339 \see \ref writeto() \n
340 <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a> */
342 ///////////////////////////////////////////////////////////////////////////
346 /** \brief Connect to remote peer
348 This member will establish a connection for addressable connection-oriented protocols
349 (that is, the CommunicationPolicy is ConnectedCommunicationPolicy and the
350 AddressingPolicy is not NoAddressingPolicy).
352 \param[in] addr Address to connect to
354 \throws senf::SystemException
356 void connect (AddressParam addr);
358 /** \brief Set local address
360 For addressable protocols (AddressingPolicy is not NoAddressingPolicy), bind() will set
361 the local address of the socket.
363 \param[in] addr Local socket address to asign
365 \throws senf::SystemException
367 void bind (AddressParam addr);
369 /** \brief Query remote address
371 This member will return the address of the communication partner in addressable
372 connection-oriented protocols (that is, the CommunicationPolicy is
373 ConnectedCommunicationPolicy and the AddressingPolicy is not NoAddressingPolicy).
375 There are two Variants of this member, one will return the address by value, the other
376 takes a reference argument to elide the copy operation.
378 \throws senf::SystemException
381 void peer (Address & addr);
382 ///< Query remote address
383 /**< \see \ref peer() */
385 /** \brief Query local address
387 This member will return the address of the local socket in addressable protocols
388 (AddressingPolicy is not NoAddressingPolicy).
390 There are two Variants of this member, one will return the address by value, the other
391 takes a reference argument to elide the copy operation.
393 \throws senf::SystemException
396 void local (Address & addr);
397 ///< Query local address
398 /**< \see \ref local() */
402 ///////////////////////////////////////////////////////////////////////////
406 unsigned rcvbuf (); ///< Check size of receive buffer
407 /**< \returns size of receive buffer in bytes */
408 void rcvbuf (unsigned size);
409 ///< Set size of receive buffer
410 /**< \param[in] size size of receive buffer in bytes */
412 unsigned sndbuf (); ///< Check size of send buffer
413 /**< \returns size of send buffer in bytes */
414 void sndbuf (unsigned size);
415 ///< Set size of send buffer
416 /**< \param[in] size size of send buffer in bytes */
420 static ClientSocketHandle cast_static(FileHandle handle);
421 static ClientSocketHandle cast_dynamic(FileHandle handle);
423 // we need to override both since SocketHandle is *not* polymorphic
424 void state(SocketStateMap & map, unsigned lod=0);
425 std::string dumpState(unsigned lod=0);
428 ClientSocketHandle(FileHandle other, bool isChecked);
429 explicit ClientSocketHandle(std::auto_ptr<SocketProtocol> protocol,
433 unsigned available();
435 friend class senf::ServerSocketHandle<Policy>;
441 ///////////////////////////////hh.e////////////////////////////////////////
442 //#include "ClientSocketHandle.cci"
443 #include "ClientSocketHandle.ct"
444 #include "ClientSocketHandle.cti"
451 // c-file-style: "senf"
452 // indent-tabs-mode: nil
453 // ispell-local-dictionary: "american"
454 // compile-command: "scons -u test"
455 // comment-column: 40