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 "SocketHandle.hh"
34 //#include "ClientSocketHandle.mpp"
35 ///////////////////////////////hh.p////////////////////////////////////////
39 /// \addtogroup handle_group
42 template <class Policy> class ServerSocketHandle;
44 /** \brief Generic SocketHandle with client interface
46 This class provides the client side policy interface of the socket
47 abstraction. ClientSocketHandle defines the complete policy interface. It does not implement
48 any functionality itself however. All calls are forward to the following policy classes:
51 <tr><th>ClientSocketHandle member</th> <th>Policy member</th></tr>
52 <tr><td>read()</td> <td>ReadPolicy::read (\ref senf::ReadPolicyBase)</td></tr>
53 <tr><td>readfrom()</td> <td>ReadPolicy::readfrom (\ref senf::ReadPolicyBase)</td></tr>
54 <tr><td>write()</td> <td>WritePolicy::write (\ref senf::WritePolicyBase)</td></tr>
55 <tr><td>writeto()</td> <td>WritePolicy::writeto (\ref senf::WritePolicyBase)</td></tr>
56 <tr><td>connect()</td> <td>AddressingPolicy::connect (\ref senf::AddressingPolicyBase)</td></tr>
57 <tr><td>bind()</td> <td>AddressingPolicy::bind (\ref senf::AddressingPolicyBase)</td></tr>
58 <tr><td>peer()</td> <td>AddressingPolicy::peer (\ref senf::AddressingPolicyBase)</td></tr>
59 <tr><td>local()</td> <td>AddressingPolicy::local (\ref senf::AddressingPolicyBase)</td></tr>
60 <tr><td>rcvbuf()</td> <td>BufferingPolicy::sndbuf (\ref senf::BufferingPolicyBase)</td></tr>
61 <tr><td>sndbuf()</td> <td>BufferingPolicy::rcvbuf (\ref senf::BufferingPolicyBase)</td></tr>
64 It is important to note, that not all members are always accessible. Which are depends on
65 the \c Policy template argument. If any of the policy axis is left unspecified the
66 corresponding members will not be callable (you will get a compile time error). Even if
67 every policy axis is defined, some members might (and will) not exist if they are
68 meaningless for the protocol of the socket. This depends on the exact policy.
70 To find out, which members are available, you have to check the documentation of the policy
71 classes. You can also find a summary of all members available in the leaf protocol class
74 \todo Move all not template-parameter dependent code into a non-template base class
76 \idea Give SocketHandle (and therefore ClientSocketHandle and ServerSocketHandle) a \c
77 protocol() template member and an additional template arg \c Policies. This arg should be a
78 typelist of Poclicy classes which can be accessed. You use protocol<ProtocolClass>() to
79 access a protocol class. \c Policies can of course be underspecified or even empty.
81 \idea add more flexible read/write members for a) boost::arrays and arrays of other types b)
82 std::vector (which uses contiguous memory ..) c) other random-access containers (we should
83 use some configurable trait class to identify containers with contiguous storage). Probably
84 we should just use a generic Boost.Range interface. Here we again come to the point: make
85 all except the most basic members be non-member algorithms ? this would make the
86 configuration of such extenden members more flexible.
88 \see \ref policy_group \n
91 template <class Policy>
92 class ClientSocketHandle
93 : public SocketHandle<Policy>
96 ///////////////////////////////////////////////////////////////////////////
99 /// Address type from the addressing policy
100 typedef typename Policy::AddressingPolicy::Address Address;
101 /// 'Best' type for passing address as parameter
102 /** Depending on the type of \c Address, this will be either <tt>Address</tt> or <tt>Address
103 const &</tt>. See <a href="http://www.boost.org/libs/utility/call_traits.htm"
104 class="ext">call_traits documentation in the Boost.Utility library\endlink.</a>
106 typedef typename boost::call_traits<Address>::param_type AddressParam;
107 /// Corresponding server socket handle with the same policy
108 /** This class will probably only be usable, if the \c CommunicationPolicy is \c
109 ConnectedCommunicationPolicy and the \c AddressingPolicy is not \c
110 NoAddressingPolicy. */
111 typedef ServerSocketHandle<Policy> ServerSocketHandle;
113 ///////////////////////////////////////////////////////////////////////////
114 ///\name Structors and default members
117 // no default constructor
118 // default copy constructor
119 // default copy assignment
120 // default destructor
122 // conversion constructors
123 template <class OtherPolicy>
124 ClientSocketHandle(ClientSocketHandle<OtherPolicy> other,
125 typename SocketHandle<Policy>::template IsCompatible<OtherPolicy>::type * = 0);
127 template <class OtherPolicy>
128 typename SocketHandle<Policy>::template IsCompatible<OtherPolicy>::type const &
129 operator=(ClientSocketHandle<OtherPolicy> other);
132 ///////////////////////////////////////////////////////////////////////////
134 ///////////////////////////////////////////////////////////////////////////
135 ///\name Reading and Writing
138 /** \brief Read data from socket
140 If the sockets \c FramingPolicy is \c DatagramFramingPolicy, every read() command will
141 return a single datagram. If the sockets FramingPolicy is StreamFraming, the operation will
142 return as much data as possible from the socket buffer. However it cannot be guaranteed,
143 that the socket buffer will be empty after read() returns.
145 \attention If the space available for the data read is limited, the read will return no
146 more than that amount of data. For a datagram socket, a full datagram is still dequed
147 from the socket buffer, the remainder of the datagram will be lost.
149 There are three variants of read which differ in how they return the read string.
151 \throws senf::SystemException
154 This variant will read up to \c limit bytes from the
155 socket and return them as a \c std::string object.
157 On a blocking socket, this member will \e always return some data (as long as the socket
158 has not been closed at the other end) and will block, if no data is available now. If
159 you do not want to block, you \e must make the socket non-blocking (using
160 FileHandle::blocking()).
162 \param[in] limit Maximum number of bytes to read or 0 if unlimited.
165 \implementation The read() family of members will use standard POSIX \c read calls, not
168 std::string read (unsigned limit=0);
169 void read (std::string & buffer, unsigned limit=0);
170 ///< Read data into string buffer
171 /**< On a blocking socket, this member will \e always return
172 some data (as long as the socket has not been closed at
173 the other end) and will block, if no data is available
174 now. If you do not want to block, you \e must make the
175 socket non-blocking (using FileHandle::blocking()).
176 \param[out] buffer data read
177 \param[in] limit Maximum number of buytes to read or 0
180 unsigned read (char * buffer, unsigned size);
181 ///< Read data into memory area
182 /**< This variant will read data into the memory area at \c
183 buffer of size \c size. This is the most performant
185 \param[in] buffer address of buffer to store data at
186 \param[in] size size of memory buffer
187 \returns Number of bytes read
190 /** \brief Read data from unconnected socket returning address
192 This member behaves like read() but should only be available, if the sockets \c
193 CommunicationPolicy is \c UnconnectedCommunicationPolicy and the \c AddressingPolicy is
194 not \c NoAddressingPolicy. The readfrom() family will in addition to the data return the
195 address of the sender.
197 \throws senf::SystemException
199 This variant will return the data read and the address as a std::pair.
201 \returns \c std::pair of data read (a string) and the peers address
203 \fixme Add \c limit argument
205 \implementation The readfrom() family of members will use \c recvfrom from the BSD
208 std::pair<std::string, Address>
210 void readfrom (std::string & buffer, Address & from);
211 ///< Read data into string buffer
212 /**< This variant will return the result in the locations
214 \param[out] buffer data read
215 \param[out] from peer address
216 \see \ref readfrom() */
217 unsigned readfrom (char * buffer, unsigned size, Address & from);
218 ///< Read data into memory byffer
219 /**< This variant will read data into the memory area at \c
220 buffer of size \c size. This is the most performant
221 version of readfrom().
222 \param[in] buffer address of buffer to store data at
223 \param[in] size size of bnuffer
224 \param[out] from peer address
225 \returns Number of bytes read
226 \see \ref readfrom() */
229 /** \brief Write data to socket
231 The write() family of members will write out the data to the socket. If the sockets \c
232 FramingPolicy is \c DatagramFramingPolicy, every write() call will result in one
235 A single write call might depending on the circumstances write only part of the data.
237 There are two variants of thie member
239 \throws senf::SystemException
242 This variant will write out the string \c data.
244 \param[in] data Data to write
245 \returns number of bytes written
246 \implementation The write() family of members will use POSIX \c write calls, not \c
249 unsigned write (std::string const & data);
250 unsigned write (char const * buffer, unsigned size);
251 ///< Write data to socket from memory buffer
252 /**< \param[in] buffer address of buffer to write
253 \param[in] size amount of data to write
254 \returns Number of bytes written
257 /** \brief Write data to unconnected socket
259 This member behaves like write() but should only be available, if the sockets \c
260 CommunicationPolicy is \c UnconnectedCommunicationPolicy and the \c AddressingPolicy is
261 not \c NoAddressingPolicy. The writeto() family of members takes the target address as
262 an additional argument.
264 There are two variants of this member.
266 \throw senf::SystemException
269 This variant will send the string \c data to the peer \c addr.
271 \param[in] addr Address of peer to send data to
272 \param[in] data data to send
273 \returns Number of bytes written
275 unsigned writeto (AddressParam addr, std::string const & data);
276 unsigned writeto (AddressParam addr, char const * buffer, unsigned size);
277 ///< Write data from memory buffer to unconnected socket
278 /**< \param[in] addr Address o fpeer to send data to
279 \param[in] buffer address of buffer to write
280 \param[in] size amount of data to write
281 \returns Number of bytes written
282 \see \ref writeto() */
284 ///////////////////////////////////////////////////////////////////////////
288 /** \brief Connect to remote peer
290 This member will establish a connection for addressable connection-oriented protocols
291 (that is, the CommunicationPolicy is ConnectedCommunicationPolicy and the
292 AddressingPolicy is not NoAddressingPolicy).
294 \param[in] addr Address to connect to
296 \throws senf::SystemException
298 void connect (AddressParam addr);
300 /** \brief Set local address
302 For addressable protocols (AddressingPolicy is not NoAddressingPolicy), bind() will set
303 the local address of the socket.
305 \param[in] addr Local socket address to asign
307 \throws senf::SystemException
309 void bind (AddressParam addr);
311 /** \brief Query remote address
313 This member will return the address of the communication partner in addressable
314 connection-oriented protocols (that is, the CommunicationPolicy is
315 ConnectedCommunicationPolicy and the AddressingPolicy is not NoAddressingPolicy).
317 There are two Variants of this member, one will return the address by value, the other
318 takes a reference argument to elide the copy operation.
320 \throws senf::SystemException
323 void peer (Address & addr);
324 ///< Query remote address
325 /**< \see \ref peer() */
327 /** \brief Query local address
329 This member will return the address of the local socket in addressable protocols
330 (AddressingPolicy is not NoAddressingPolicy).
332 There are two Variants of this member, one will return the address by value, the other
333 takes a reference argument to elide the copy operation.
335 \throws senf::SystemException
338 void local (Address & addr);
339 ///< Query local address
340 /**< \see \ref local() */
344 ///////////////////////////////////////////////////////////////////////////
348 unsigned rcvbuf (); ///< Check size of receive buffer
349 /**< \returns size of receive buffer in bytes */
350 void rcvbuf (unsigned size);
351 ///< Set size of receive buffer
352 /**< \param[in] size size of receive buffer in bytes */
354 unsigned sndbuf (); ///< Check size of send buffer
355 /**< \returns size of send buffer in bytes */
356 void sndbuf (unsigned size);
357 ///< Set size of send buffer
358 /**< \param[in] size size of send buffer in bytes */
362 static ClientSocketHandle cast_static(FileHandle handle);
363 static ClientSocketHandle cast_dynamic(FileHandle handle);
365 // we need to override both since SocketHandle is *not* polymorphic
366 void state(SocketStateMap & map, unsigned lod=0);
367 std::string dumpState(unsigned lod=0);
370 ClientSocketHandle(FileHandle other, bool isChecked);
371 explicit ClientSocketHandle(std::auto_ptr<SocketProtocol> protocol,
375 unsigned available();
377 friend class senf::ServerSocketHandle<Policy>;
383 ///////////////////////////////hh.e////////////////////////////////////////
384 //#include "ClientSocketHandle.cci"
385 #include "ClientSocketHandle.ct"
386 #include "ClientSocketHandle.cti"
393 // c-file-style: "senf"
394 // indent-tabs-mode: nil
395 // ispell-local-dictionary: "american"