4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
6 // The contents of this file are subject to the Fraunhofer FOKUS Public License
7 // Version 1.0 (the "License"); you may not use this file except in compliance
8 // with the License. You may obtain a copy of the License at
9 // http://senf.berlios.de/license.html
11 // The Fraunhofer FOKUS Public License Version 1.0 is based on,
12 // but modifies the Mozilla Public License Version 1.1.
13 // See the full license text for the amendments.
15 // Software distributed under the License is distributed on an "AS IS" basis,
16 // WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
17 // for the specific language governing rights and limitations under the License.
19 // The Original Code is Fraunhofer FOKUS code.
21 // The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V.
22 // (registered association), Hansastraße 27 c, 80686 Munich, Germany.
23 // All Rights Reserved.
26 // Stefan Bund <g0dil@berlios.de>
29 \brief ClientSocketHandle public header
32 #ifndef HH_SENF_Socket_ClientSocketHandle_
33 #define HH_SENF_Socket_ClientSocketHandle_ 1
36 #include <boost/call_traits.hpp>
37 #include <boost/range.hpp>
38 #include <boost/utility.hpp>
39 #include <boost/type_traits.hpp>
40 #include "SocketHandle.hh"
42 //#include "ClientSocketHandle.mpp"
43 //-/////////////////////////////////////////////////////////////////////////////////////////////////
47 /// \addtogroup handle_group
50 template <class SPolicy> class ServerSocketHandle;
52 /** \brief Generic SocketHandle with client interface
54 This class provides the client side policy interface of the socket
55 abstraction. ClientSocketHandle defines the complete policy interface. It does not implement
56 any functionality itself however. The following table shows, to which policy members each
57 group of ClientSocketHandle members is forwarded. The last column shows, on which other
58 policies this member-group depends <em>in the default policy classes</em>. If you define
59 your own policy classes, the dependencies are up to you.
62 <tr><th>ClientSocketHandle member</th> <th>Policy member</th> <th>Other policies</th></tr>
63 <tr><td>read()</td> <td>ReadPolicy::read (\ref senf::ReadPolicyBase)</td> <td></td></tr>
64 <tr><td>readfrom()</td> <td>ReadPolicy::readfrom (\ref senf::ReadPolicyBase)</td> <td>UnconnectedCommunicationPolicy</td></tr>
65 <tr><td>write()</td> <td>WritePolicy::write (\ref senf::WritePolicyBase)</td> <td>ConnectedCommunicationPolicy</td></tr>
66 <tr><td>writeto()</td> <td>WritePolicy::writeto (\ref senf::WritePolicyBase)</td> <td>UnconnectedCommunicationPolicy</td></tr>
67 <tr><td>connect()</td> <td>AddressingPolicy::connect (\ref senf::AddressingPolicyBase)</td> <td></td></tr>
68 <tr><td>bind()</td> <td>AddressingPolicy::bind (\ref senf::AddressingPolicyBase)</td> <td></td></tr>
69 <tr><td>peer()</td> <td>AddressingPolicy::peer (\ref senf::AddressingPolicyBase)</td> <td></td></tr>
70 <tr><td>local()</td> <td>AddressingPolicy::local (\ref senf::AddressingPolicyBase)</td> <td></td></tr>
73 It is important to note, that not all members are always accessible. Which are depends on
74 the \c Policy template argument. If any of the policy axis is left unspecified the
75 corresponding members will not be callable (you will get a compile time error). Even if
76 every policy axis is defined, some members might (and will) not exist if they are
77 meaningless for the protocol of the socket. This depends on the exact policy.
79 To find out, which members are available, you have to check the documentation of the policy
80 classes. You can also find a summary of all members available in the leaf protocol class
83 \todo Move all not template-parameter dependent code into a non-template base class
85 \idea Give SocketHandle (and therefore ClientSocketHandle and ServerSocketHandle) a \c
86 protocol() template member and an additional template arg \c Policies. This arg should be a
87 typelist of policy classes which can be accessed. You use protocol<ProtocolClass>() to
88 access a protocol class. \c Policies can of course be underspecified or even empty.
90 \see \ref policy_group \n
93 template <class SPolicy>
94 class ClientSocketHandle
95 : public SocketHandle<SPolicy>
98 //-////////////////////////////////////////////////////////////////////////
101 /// Address type from the addressing policy
102 typedef typename SPolicy::AddressingPolicy::Address Address;
103 /// 'Best' type for passing address as parameter
104 /** Depending on the type of \c Address, this will be either <tt>Address</tt> or <tt>Address
106 href="http://www.boost.org/doc/libs/release/libs/utility/call_traits.htm">call_traits documentation in
107 the Boost.Utility library.</a>
109 typedef typename boost::call_traits<Address>::param_type AddressParam;
110 /// Corresponding server socket handle with the same policy
111 /** This class will probably only be usable, if the \c CommunicationPolicy is \c
112 ConnectedCommunicationPolicy and the \c AddressingPolicy is not \c
113 NoAddressingPolicy. */
114 typedef ServerSocketHandle<SPolicy> ServerHandle;
116 //-////////////////////////////////////////////////////////////////////////
117 ///\name Structors and default members
120 // default default constructor
121 // default copy constructor
122 // default copy assignment
123 // default destructor
126 ClientSocketHandle();
128 // conversion constructors
130 template <class OtherPolicy>
131 ClientSocketHandle(ClientSocketHandle<OtherPolicy> other,
132 typename SocketHandle<SPolicy>::template IsCompatible<OtherPolicy>::type * = 0);
134 ClientSocketHandle(ClientSocketHandle<OtherPolicy> other);
138 template <class OtherPolicy>
139 typename SocketHandle<SPolicy>::template IsCompatible<OtherPolicy>::type const &
140 operator=(ClientSocketHandle<OtherPolicy> other);
142 template <class OtherPolicy>
143 ClientSocketHandle<OtherPolicy> const & operator=(ClientSocketHandle<OtherPolicy> other);
147 //-////////////////////////////////////////////////////////////////////////
149 //-////////////////////////////////////////////////////////////////////////
150 ///\name Reading and Writing
153 /** \brief Read data from socket
155 If the sockets \c FramingPolicy is \c DatagramFramingPolicy, every read() command will
156 return a single datagram. If the sockets FramingPolicy is StreamFraming, the operation
157 will return as much data as possible from the socket buffer. However it cannot be
158 guaranteed, that the socket buffer will be empty after read() returns.
160 \attention If the space available for the data read is limited, the read will return no
161 more than that amount of data. For a datagram socket, a full datagram is still dequeued
162 from the socket buffer, the remainder of the datagram will be lost.
164 There are several variants of read which differ in how they return the read string.
166 If the further document doesn't tell something differently, on a blocking socket the
167 members will \e always return some data (as long as the socket has not been closed at
168 the other end) and will block, if no data is available now. If you do not want to block,
169 you \e must make the socket non-blocking (using FileHandle::blocking()).
171 \throws senf::SystemException
174 This variant will read up to \c limit bytes from the
175 socket and return them as a \c std::string object.
177 \param[in] limit Maximum number of bytes to read or 0 if unlimited.
180 \implementation The read() family of members will use standard POSIX \c read calls, not
183 std::string read (unsigned limit=0);
184 template <class ForwardWritableRange>
186 typename boost::range_iterator<ForwardWritableRange>::type
187 read (ForwardWritableRange const & range,
188 typename boost::disable_if< boost::is_convertible<ForwardWritableRange,unsigned> >::type * = 0);
190 typename boost::range_iterator<ForwardWritableRange>::type
191 read (ForwardWritableRange const & range);
192 ///< Read data into range
193 /**< Read data into the given range. At most
194 <tt>boost::size(range)</tt> characters are read. The
195 data read will start at the beginning of the
196 range. read returns a past-the-end iterator after the
197 last character read. This iterator will point to
198 somewhere within the input range.
199 \param[in,out] range Range to store data in
200 \returns past-the-end iterator pointer to after the
203 <a href="http://www.boost.org/doc/libs/release/libs/range/index.html">Boost.Range</a> */
206 template <class ForwardWritableRange>
207 typename boost::range_iterator<ForwardWritableRange>::type
208 read (ForwardWritableRange & range,
209 typename boost::disable_if< boost::is_convertible<ForwardWritableRange,unsigned> >::type * = 0);
211 template <class ForwardWritableRange>
212 typename boost::range_iterator<ForwardWritableRange>::type
213 read (ForwardWritableRange & range);
214 ///< Read data into range
215 /**< \see read(ForwardWritableRange const &) \n
217 <a href="http://www.boost.org/doc/libs/release/libs/range/index.html">Boost.Range</a> */
219 template <class Sequence>
220 void read (Sequence & container, unsigned limit);
221 ///< Read data into container
222 /**< The data read is written into the given container. Old
223 data in the container will be removed. For this to
224 work, the container must be a model of 'Sequence' as
225 defined in the STL documentation
226 \param[out] container Container to write data to
227 \param[in] limit Maximum number of characters to read
229 char * read (char * start, char * end);
230 ///< Read data into memory area
231 /**< This variant will read data into the memory area from
232 \a start to before \a end. This is guaranteed to be the
233 most efficient version of read().
234 \param[in] start address of buffer to store data at
235 \param[in] end address one past the end of the buffer
236 \returns pointer past the end of the data read
239 /** \brief Read data from unconnected socket returning address
241 The readfrom() group of member behaves like \ref read() but should only be available, if
242 the sockets \c CommunicationPolicy is \c UnconnectedCommunicationPolicy and the \c
243 AddressingPolicy is not \c NoAddressingPolicy. readfrom() will in addition to the data
244 return the address of the sender.
246 \throws senf::SystemException
249 This variant will return the data read and the address as a std::pair.
251 \returns \c std::pair of data read (a string) and the peers address
253 \implementation The readfrom() family of members will use \c recvfrom from the BSD
256 std::pair<std::string, Address>
257 readfrom (unsigned limit=0);
258 template <class ForwardWritableRange>
259 typename boost::range_iterator<ForwardWritableRange const>::type
260 readfrom (ForwardWritableRange const & range, Address & from);
261 ///< Read data into range
262 /**< Read data into the given range. At most
263 <tt>boost::size(range)</tt> characters are read. The
264 data read will start at the beginning of the
265 range. read returns a past-the-end iterator after the
266 last character read. This iterator will point to
267 somewhere within the input range.
268 \param[in,out] range Range to store data in
269 \param[out] from peers address from which the data was
271 \returns past-the-end iterator pointer to after the
273 \see \ref readfrom() \n
274 <a href="http://www.boost.org/doc/libs/release/libs/range/index.html">Boost.Range</a> */
275 template <class ForwardWritableRange>
276 typename boost::range_iterator<ForwardWritableRange>::type
277 readfrom (ForwardWritableRange & range, Address & from);
278 ///< Read data into range
279 /**< \see readfrom(ForwardWritableRange const&,Address&) \n
281 <a href="http://www.boost.org/doc/libs/release/libs/range/index.html">Boost.Range</a> */
282 template <class Sequence>
283 void readfrom (Sequence & container, Address & from, unsigned limit);
284 ///< Read data into container
285 /**< The data read is written into the given container. Old
286 data in the container will be removed. For this to
287 work, the container must be a model of 'Sequence' as
288 defined in the STL documentation
289 \param[out] container Container to write data to
290 \param[in] limit Maximum number of characters to read
291 \param[out] from peers address from which the data was
293 \see \ref readfrom() */
294 char * readfrom (char * start, char * end, Address & from);
295 ///< Read data into memory buffer
296 /**< This variant will read data into the memory area from
297 \a start to before \a end. This is guaranteed to be the
298 most efficient version of readfrom().
299 \param[in] start address of buffer to store data at
300 \param[in] end address one past the end of the buffer
301 \param[out] from peers address from which the data was
303 \returns pointer past the end of the data read
307 /** \brief Write data to socket
309 The write() family of members will write out the data to the socket. If the sockets \c
310 FramingPolicy is \c DatagramFramingPolicy, every write() call will result in one
313 A single write call might depending on the circumstances write only part of the data.
315 There are two variants of this member
317 \throws senf::SystemException
320 This variant will write out the range \c data.
322 \param[in] range Data to write
323 \returns past-the-end iterator after last element written
324 \implementation The write() family of members will use POSIX \c write calls, not \c
327 template <class ForwardReadableRange>
328 typename boost::range_const_iterator<ForwardReadableRange const>::type
329 write (ForwardReadableRange const & range);
330 char const * write (char const * start, char const * end);
331 ///< Write data to socket from memory buffer
332 /**< \param[in] start beginning of area to write
333 \param[in] end past-the-end pointer to area to write
334 \returns past-the-end pointer after last byte written
336 <a href="http://www.boost.org/doc/libs/release/libs/range/index.html">Boost.Range</a> */
338 /** \brief Write data to unconnected socket
340 This member behaves like write() but should only be available, if the sockets \c
341 CommunicationPolicy is \c UnconnectedCommunicationPolicy and the \c AddressingPolicy is
342 not \c NoAddressingPolicy. The writeto() family of members takes the target address as
343 an additional argument.
345 There are two variants of this member.
347 \throw senf::SystemException
350 This variant will send the range \c range to peer \c addr.
352 \param[in] addr Address of peer to send data to
353 \param[in] range data to send
354 \returns Number of bytes written
356 template <class ForwardReadableRange>
357 typename boost::range_const_iterator<ForwardReadableRange const>::type
358 writeto (AddressParam addr, ForwardReadableRange const & range);
359 char const * writeto (AddressParam addr, char const * start, char const * end);
360 ///< Write data from memory buffer to unconnected socket
361 /**< \param[in] addr Address of peer to send data to
362 \param[in] start address of buffer to write
363 \param[in] end past-the-end pointer after data to write
364 \returns past-the-end iterator after last byte written
365 \see \ref writeto() \n
366 <a href="http://www.boost.org/doc/libs/release/libs/range/index.html">Boost.Range</a> */
368 //-////////////////////////////////////////////////////////////////////////
372 /** \brief Connect to remote peer
374 This member will establish a connection for addressable connection-oriented protocols
375 (that is, the CommunicationPolicy is ConnectedCommunicationPolicy and the
376 AddressingPolicy is not NoAddressingPolicy).
378 \param[in] addr Address to connect to
380 \throws senf::SystemException
382 void connect (AddressParam addr) const;
384 /** \brief Set local address
386 For addressable protocols (AddressingPolicy is not NoAddressingPolicy), bind() will set
387 the local address of the socket.
389 \param[in] addr Local socket address to assign
391 \throws senf::SystemException
393 void bind (AddressParam addr) const;
395 /** \brief Query remote address
397 This member will return the address of the communication partner in addressable
398 connection-oriented protocols (that is, the CommunicationPolicy is
399 ConnectedCommunicationPolicy and the AddressingPolicy is not NoAddressingPolicy).
401 There are two Variants of this member, one will return the address by value, the other
402 takes a reference argument to elide the copy operation.
404 \throws senf::SystemException
406 Address peer () const;
407 void peer (Address & addr) const;
408 ///< Query remote address
409 /**< \see \ref peer() */
411 /** \brief Query local address
413 This member will return the address of the local socket in addressable protocols
414 (AddressingPolicy is not NoAddressingPolicy).
416 There are two Variants of this member, one will return the address by value, the other
417 takes a reference argument to elide the copy operation.
419 \throws senf::SystemException
421 Address local () const;
422 void local (Address & addr) const;
423 ///< Query local address
424 /**< \see \ref local() */
428 static ClientSocketHandle cast_static(FileHandle handle);
429 static ClientSocketHandle cast_dynamic(FileHandle handle);
431 // we need to override both since SocketHandle is *not* polymorphic
432 void state(SocketStateMap & map, unsigned lod=0);
433 std::string dumpState(unsigned lod=0);
435 unsigned available();
438 ClientSocketHandle(FileHandle other, bool isChecked);
439 explicit ClientSocketHandle(std::auto_ptr<SocketBody> body);
442 friend class senf::ServerSocketHandle<SPolicy>;
448 //-/////////////////////////////////////////////////////////////////////////////////////////////////
449 //#include "ClientSocketHandle.cci"
450 #include "ClientSocketHandle.ct"
451 #include "ClientSocketHandle.cti"
458 // c-file-style: "senf"
459 // indent-tabs-mode: nil
460 // ispell-local-dictionary: "american"
461 // compile-command: "scons -u test"
462 // comment-column: 40