4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
6 // Stefan Bund <g0dil@berlios.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_SENF_Socket_ClientSocketHandle_
28 #define HH_SENF_Socket_ClientSocketHandle_ 1
31 #include <boost/call_traits.hpp>
32 #include <boost/range.hpp>
33 #include <boost/utility.hpp>
34 #include <boost/type_traits.hpp>
35 #include "SocketHandle.hh"
37 //#include "ClientSocketHandle.mpp"
38 ///////////////////////////////hh.p////////////////////////////////////////
42 /// \addtogroup handle_group
45 template <class SPolicy> class ServerSocketHandle;
47 /** \brief Generic SocketHandle with client interface
49 This class provides the client side policy interface of the socket
50 abstraction. ClientSocketHandle defines the complete policy interface. It does not implement
51 any functionality itself however. The following table shows, to which policy members each
52 group of ClientSocketHandle members is forwardd. The last collumn shows, on which other
53 policies this member-group depends <em>in the default policy classes</em>. If you define
54 your own policy classes, the dependencies are up to you.
57 <tr><th>ClientSocketHandle member</th> <th>Policy member</th> <th>Other policies</th></tr>
58 <tr><td>read()</td> <td>ReadPolicy::read (\ref senf::ReadPolicyBase)</td> <td></td></tr>
59 <tr><td>readfrom()</td> <td>ReadPolicy::readfrom (\ref senf::ReadPolicyBase)</td> <td>UnconnectedCommunicationPolicy</td></tr>
60 <tr><td>write()</td> <td>WritePolicy::write (\ref senf::WritePolicyBase)</td> <td>ConnectedCommunicationPolicy</td></tr>
61 <tr><td>writeto()</td> <td>WritePolicy::writeto (\ref senf::WritePolicyBase)</td> <td>UnconnectedCommunicationPolicy</td></tr>
62 <tr><td>connect()</td> <td>AddressingPolicy::connect (\ref senf::AddressingPolicyBase)</td> <td></td></tr>
63 <tr><td>bind()</td> <td>AddressingPolicy::bind (\ref senf::AddressingPolicyBase)</td> <td></td></tr>
64 <tr><td>peer()</td> <td>AddressingPolicy::peer (\ref senf::AddressingPolicyBase)</td> <td></td></tr>
65 <tr><td>local()</td> <td>AddressingPolicy::local (\ref senf::AddressingPolicyBase)</td> <td></td></tr>
68 It is important to note, that not all members are always accessible. Which are depends on
69 the \c Policy template argument. If any of the policy axis is left unspecified the
70 corresponding members will not be callable (you will get a compile time error). Even if
71 every policy axis is defined, some members might (and will) not exist if they are
72 meaningless for the protocol of the socket. This depends on the exact policy.
74 To find out, which members are available, you have to check the documentation of the policy
75 classes. You can also find a summary of all members available in the leaf protocol class
78 \todo Move all not template-parameter dependent code into a non-template base class
80 \idea Give SocketHandle (and therefore ClientSocketHandle and ServerSocketHandle) a \c
81 protocol() template member and an additional template arg \c Policies. This arg should be a
82 typelist of Poclicy classes which can be accessed. You use protocol<ProtocolClass>() to
83 access a protocol class. \c Policies can of course be underspecified or even empty.
85 \see \ref policy_group \n
88 template <class SPolicy>
89 class ClientSocketHandle
90 : public SocketHandle<SPolicy>
93 ///////////////////////////////////////////////////////////////////////////
96 /// Address type from the addressing policy
97 typedef typename SPolicy::AddressingPolicy::Address Address;
98 /// 'Best' type for passing address as parameter
99 /** Depending on the type of \c Address, this will be either <tt>Address</tt> or <tt>Address
101 href="http://www.boost.org/libs/utility/call_traits.htm">call_traits documentation in
102 the Boost.Utility library.</a>
104 typedef typename boost::call_traits<Address>::param_type AddressParam;
105 /// Corresponding server socket handle with the same policy
106 /** This class will probably only be usable, if the \c CommunicationPolicy is \c
107 ConnectedCommunicationPolicy and the \c AddressingPolicy is not \c
108 NoAddressingPolicy. */
109 typedef ServerSocketHandle<SPolicy> ServerHandle;
111 ///////////////////////////////////////////////////////////////////////////
112 ///\name Structors and default members
115 // default default constructor
116 // default copy constructor
117 // default copy assignment
118 // default destructor
121 ClientSocketHandle();
123 // conversion constructors
125 template <class OtherPolicy>
126 ClientSocketHandle(ClientSocketHandle<OtherPolicy> other,
127 typename SocketHandle<SPolicy>::template IsCompatible<OtherPolicy>::type * = 0);
129 ClientSocketHandle(ClientSocketHandle<OtherPolicy> other);
133 template <class OtherPolicy>
134 typename SocketHandle<SPolicy>::template IsCompatible<OtherPolicy>::type const &
135 operator=(ClientSocketHandle<OtherPolicy> other);
137 template <class OtherPolicy>
138 ClientSocketHandle<OtherPolicy> const & operator=(ClientSocketHandle<OtherPolicy> other);
142 ///////////////////////////////////////////////////////////////////////////
144 ///////////////////////////////////////////////////////////////////////////
145 ///\name Reading and Writing
148 /** \brief Read data from socket
150 If the sockets \c FramingPolicy is \c DatagramFramingPolicy, every read() command will
151 return a single datagram. If the sockets FramingPolicy is StreamFraming, the operation
152 will return as much data as possible from the socket buffer. However it cannot be
153 guaranteed, that the socket buffer will be empty after read() returns.
155 \attention If the space available for the data read is limited, the read will return no
156 more than that amount of data. For a datagram socket, a full datagram is still dequeued
157 from the socket buffer, the remainder of the datagram will be lost.
159 There are several variants of read which differ in how they return the read string.
161 If the further document doesn't tell something differently, on a blocking socket the
162 members will \e always return some data (as long as the socket has not been closed at
163 the other end) and will block, if no data is available now. If you do not want to block,
164 you \e must make the socket non-blocking (using FileHandle::blocking()).
166 \throws senf::SystemException
169 This variant will read up to \c limit bytes from the
170 socket and return them as a \c std::string object.
172 \param[in] limit Maximum number of bytes to read or 0 if unlimited.
175 \implementation The read() family of members will use standard POSIX \c read calls, not
178 std::string read (unsigned limit=0);
179 template <class ForwardWritableRange>
181 typename boost::range_iterator<ForwardWritableRange>::type
182 read (ForwardWritableRange const & range,
183 typename boost::disable_if< boost::is_convertible<ForwardWritableRange,unsigned> >::type * = 0);
185 typename boost::range_iterator<ForwardWritableRange>::type
186 read (ForwardWritableRange const & range);
187 ///< Read data into range
188 /**< Read data into the given range. At most
189 <tt>boost::size(range)</tt> characters are read. The
190 data read will start at the beginning of the
191 range. read returns a past-the-end iterator after the
192 last character read. This iterator will point to
193 somewhere within the input range.
194 \param[in,out] range Range to store data in
195 \returns past-the-end iterator pointer to after the
198 <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a> */
201 template <class ForwardWritableRange>
202 typename boost::range_iterator<ForwardWritableRange>::type
203 read (ForwardWritableRange & range,
204 typename boost::disable_if< boost::is_convertible<ForwardWritableRange,unsigned> >::type * = 0);
206 template <class ForwardWritableRange>
207 typename boost::range_iterator<ForwardWritableRange>::type
208 read (ForwardWritableRange & range);
209 ///< Read data into range
210 /**< \see read(ForwardWritableRange const &) \n
212 <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a> */
214 template <class Sequence>
215 void read (Sequence & container, unsigned limit);
216 ///< Read data into container
217 /**< The data read is written into the given container. Old
218 data in the container will be removed. For this to
219 work, the container must be a model of 'Sequence' as
220 defined in the STL documentation
221 \param[out] container Container to write data to
222 \param[in] limit Maximum number of characters to read
224 char * read (char * start, char * end);
225 ///< Read data into memory area
226 /**< This variant will read data into the memory area from
227 \a start to before \a end. This is guaranteed to be the
228 most efficient version of read().
229 \param[in] start address of buffer to store data at
230 \param[in] end address one past the end of the buffer
231 \returns pointer past the end of the data read
234 /** \brief Read data from unconnected socket returning address
236 The readfrom() group of member behaves like \ref read() but should only be available, if
237 the sockets \c CommunicationPolicy is \c UnconnectedCommunicationPolicy and the \c
238 AddressingPolicy is not \c NoAddressingPolicy. readfrom() will in addition to the data
239 return the address of the sender.
241 \throws senf::SystemException
244 This variant will return the data read and the address as a std::pair.
246 \returns \c std::pair of data read (a string) and the peers address
248 \implementation The readfrom() family of members will use \c recvfrom from the BSD
251 std::pair<std::string, Address>
252 readfrom (unsigned limit=0);
253 template <class ForwardWritableRange>
254 typename boost::range_iterator<ForwardWritableRange const>::type
255 readfrom (ForwardWritableRange const & range, Address & from);
256 ///< Read data into range
257 /**< Read data into the given range. At most
258 <tt>boost::size(range)</tt> characters are read. The
259 data read will start at the beginning of the
260 range. read returns a past-the-end iterator after the
261 last character read. This iterator will point to
262 somewhere within the input range.
263 \param[in,out] range Range to store data in
264 \param[out] from peers address from which the data was
266 \returns past-the-end iterator pointer to after the
268 \see \ref readfrom() \n
269 <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a> */
270 template <class ForwardWritableRange>
271 typename boost::range_iterator<ForwardWritableRange>::type
272 readfrom (ForwardWritableRange & range, Address & from);
273 ///< Read data into range
274 /**< \see readfrom(ForwardWritableRange const&,Address&) \n
276 <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a> */
277 template <class Sequence>
278 void readfrom (Sequence & container, Address & from, unsigned limit);
279 ///< Read data into container
280 /**< The data read is written into the given container. Old
281 data in the container will be removed. For this to
282 work, the container must be a model of 'Sequence' as
283 defined in the STL documentation
284 \param[out] container Container to write data to
285 \param[in] limit Maximum number of characters to read
286 \param[out] from peers address from which the data was
288 \see \ref readfrom() */
289 char * readfrom (char * start, char * end, Address & from);
290 ///< Read data into memory buffer
291 /**< This variant will read data into the memory area from
292 \a start to before \a end. This is guaranteed to be the
293 most efficient version of readfrom().
294 \param[in] start address of buffer to store data at
295 \param[in] end address one past the end of the buffer
296 \param[out] from peers address from which the data was
298 \returns pointer past the end of the data read
302 /** \brief Write data to socket
304 The write() family of members will write out the data to the socket. If the sockets \c
305 FramingPolicy is \c DatagramFramingPolicy, every write() call will result in one
308 A single write call might depending on the circumstances write only part of the data.
310 There are two variants of this member
312 \throws senf::SystemException
315 This variant will write out the range \c data.
317 \param[in] range Data to write
318 \returns past-the-end iterator after last element written
319 \implementation The write() family of members will use POSIX \c write calls, not \c
322 template <class ForwardReadableRange>
323 typename boost::range_const_iterator<ForwardReadableRange const>::type
324 write (ForwardReadableRange const & range);
325 char const * write (char const * start, char const * end);
326 ///< Write data to socket from memory buffer
327 /**< \param[in] start beginning of area to write
328 \param[in] end past-the-end pointer to area to write
329 \returns past-the-end pointer after last byte written
331 <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a> */
333 /** \brief Write data to unconnected socket
335 This member behaves like write() but should only be available, if the sockets \c
336 CommunicationPolicy is \c UnconnectedCommunicationPolicy and the \c AddressingPolicy is
337 not \c NoAddressingPolicy. The writeto() family of members takes the target address as
338 an additional argument.
340 There are two variants of this member.
342 \throw senf::SystemException
345 This variant will send the range \c range to peer \c addr.
347 \param[in] addr Address of peer to send data to
348 \param[in] range data to send
349 \returns Number of bytes written
351 template <class ForwardReadableRange>
352 typename boost::range_const_iterator<ForwardReadableRange const>::type
353 writeto (AddressParam addr, ForwardReadableRange const & range);
354 char const * writeto (AddressParam addr, char const * start, char const * end);
355 ///< Write data from memory buffer to unconnected socket
356 /**< \param[in] addr Address of peer to send data to
357 \param[in] start address of buffer to write
358 \param[in] end past-the-end pointer after data to write
359 \returns past-the-end iterator after last byte written
360 \see \ref writeto() \n
361 <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a> */
363 ///////////////////////////////////////////////////////////////////////////
367 /** \brief Connect to remote peer
369 This member will establish a connection for addressable connection-oriented protocols
370 (that is, the CommunicationPolicy is ConnectedCommunicationPolicy and the
371 AddressingPolicy is not NoAddressingPolicy).
373 \param[in] addr Address to connect to
375 \throws senf::SystemException
377 void connect (AddressParam addr) const;
379 /** \brief Set local address
381 For addressable protocols (AddressingPolicy is not NoAddressingPolicy), bind() will set
382 the local address of the socket.
384 \param[in] addr Local socket address to assign
386 \throws senf::SystemException
388 void bind (AddressParam addr) const;
390 /** \brief Query remote address
392 This member will return the address of the communication partner in addressable
393 connection-oriented protocols (that is, the CommunicationPolicy is
394 ConnectedCommunicationPolicy and the AddressingPolicy is not NoAddressingPolicy).
396 There are two Variants of this member, one will return the address by value, the other
397 takes a reference argument to elide the copy operation.
399 \throws senf::SystemException
401 Address peer () const;
402 void peer (Address & addr) const;
403 ///< Query remote address
404 /**< \see \ref peer() */
406 /** \brief Query local address
408 This member will return the address of the local socket in addressable protocols
409 (AddressingPolicy is not NoAddressingPolicy).
411 There are two Variants of this member, one will return the address by value, the other
412 takes a reference argument to elide the copy operation.
414 \throws senf::SystemException
416 Address local () const;
417 void local (Address & addr) const;
418 ///< Query local address
419 /**< \see \ref local() */
423 static ClientSocketHandle cast_static(FileHandle handle);
424 static ClientSocketHandle cast_dynamic(FileHandle handle);
426 // we need to override both since SocketHandle is *not* polymorphic
427 void state(SocketStateMap & map, unsigned lod=0);
428 std::string dumpState(unsigned lod=0);
430 unsigned available();
433 ClientSocketHandle(FileHandle other, bool isChecked);
434 explicit ClientSocketHandle(std::auto_ptr<SocketBody> body);
437 friend class senf::ServerSocketHandle<SPolicy>;
443 ///////////////////////////////hh.e////////////////////////////////////////
444 //#include "ClientSocketHandle.cci"
445 #include "ClientSocketHandle.ct"
446 #include "ClientSocketHandle.cti"
453 // c-file-style: "senf"
454 // indent-tabs-mode: nil
455 // ispell-local-dictionary: "american"
456 // compile-command: "scons -u test"
457 // comment-column: 40