// $Id$
//
// Copyright (C) 2006
-// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
-// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
-// Stefan Bund <stefan.bund@fokus.fraunhofer.de>
+// Fraunhofer Institute for Open Communication Systems (FOKUS)
+// Competence Center NETwork research (NET), St. Augustin, GERMANY
+// Stefan Bund <g0dil@berlios.de>
//
// This program is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// Custom includes
#include <boost/call_traits.hpp>
+#include <boost/range.hpp>
+#include <boost/utility.hpp>
+#include <boost/type_traits.hpp>
#include "SocketHandle.hh"
//#include "ClientSocketHandle.mpp"
This class provides the client side policy interface of the socket
abstraction. ClientSocketHandle defines the complete policy interface. It does not implement
- any functionality itself however. All calls are forward to the following policy classes:
+ any functionality itself however. The following table shows, to which policy members each
+ group of ClientSocketHandle members is forwardd. The last collumn shows, on which other
+ policies this member-group depends <em>in the default policy classes</em>. If you define
+ your own policy classes, the dependencies are up to you.
<table class="senf">
- <tr><th>ClientSocketHandle member</th> <th>Policy member</th></tr>
- <tr><td>read()</td> <td>ReadPolicy::read (\ref senf::ReadPolicyBase)</td></tr>
- <tr><td>readfrom()</td> <td>ReadPolicy::readfrom (\ref senf::ReadPolicyBase)</td></tr>
- <tr><td>write()</td> <td>WritePolicy::write (\ref senf::WritePolicyBase)</td></tr>
- <tr><td>writeto()</td> <td>WritePolicy::writeto (\ref senf::WritePolicyBase)</td></tr>
- <tr><td>connect()</td> <td>AddressingPolicy::connect (\ref senf::AddressingPolicyBase)</td></tr>
- <tr><td>bind()</td> <td>AddressingPolicy::bind (\ref senf::AddressingPolicyBase)</td></tr>
- <tr><td>peer()</td> <td>AddressingPolicy::peer (\ref senf::AddressingPolicyBase)</td></tr>
- <tr><td>local()</td> <td>AddressingPolicy::local (\ref senf::AddressingPolicyBase)</td></tr>
- <tr><td>rcvbuf()</td> <td>BufferingPolicy::sndbuf (\ref senf::BufferingPolicyBase)</td></tr>
- <tr><td>sndbuf()</td> <td>BufferingPolicy::rcvbuf (\ref senf::BufferingPolicyBase)</td></tr>
+ <tr><th>ClientSocketHandle member</th> <th>Policy member</th> <th>Other policies</th></tr>
+ <tr><td>read()</td> <td>ReadPolicy::read (\ref senf::ReadPolicyBase)</td> <td></td></tr>
+ <tr><td>readfrom()</td> <td>ReadPolicy::readfrom (\ref senf::ReadPolicyBase)</td> <td>UnconnectedCommunicationPolicy</td></tr>
+ <tr><td>write()</td> <td>WritePolicy::write (\ref senf::WritePolicyBase)</td> <td>ConnectedCommunicationPolicy</td></tr>
+ <tr><td>writeto()</td> <td>WritePolicy::writeto (\ref senf::WritePolicyBase)</td> <td>UnconnectedCommunicationPolicy</td></tr>
+ <tr><td>connect()</td> <td>AddressingPolicy::connect (\ref senf::AddressingPolicyBase)</td> <td></td></tr>
+ <tr><td>bind()</td> <td>AddressingPolicy::bind (\ref senf::AddressingPolicyBase)</td> <td></td></tr>
+ <tr><td>peer()</td> <td>AddressingPolicy::peer (\ref senf::AddressingPolicyBase)</td> <td></td></tr>
+ <tr><td>local()</td> <td>AddressingPolicy::local (\ref senf::AddressingPolicyBase)</td> <td></td></tr>
+ <tr><td>rcvbuf()</td> <td>BufferingPolicy::sndbuf (\ref senf::BufferingPolicyBase)</td> <td></td></tr>
+ <tr><td>sndbuf()</td> <td>BufferingPolicy::rcvbuf (\ref senf::BufferingPolicyBase)</td> <td></td></tr>
</table>
It is important to note, that not all members are always accessible. Which are depends on
typelist of Poclicy classes which can be accessed. You use protocol<ProtocolClass>() to
access a protocol class. \c Policies can of course be underspecified or even empty.
- \idea add more flexible read/write members for a) boost::arrays and arrays of other types b)
- std::vector (which uses contiguous memory ..) c) other random-access containers (we should
- use some configurable trait class to identify containers with contiguous storage). Probably
- we should just use a generic Boost.Range interface. Here we again come to the point: make
- all except the most basic members be non-member algorithms ? this would make the
- configuration of such extenden members more flexible.
-
\see \ref policy_group \n
\ref protocol_group
*/
///\name Structors and default members
///@{
- // no default constructor
+ // default default constructor
// default copy constructor
// default copy assignment
// default destructor
+ // here to implement
+ ClientSocketHandle();
+
// conversion constructors
+# ifndef DOXYGEN
template <class OtherPolicy>
ClientSocketHandle(ClientSocketHandle<OtherPolicy> other,
typename SocketHandle<Policy>::template IsCompatible<OtherPolicy>::type * = 0);
+# else
+ ClientSocketHandle(ClientSocketHandle<OtherPolicy> other);
+# endif
+# ifndef DOXYGEN
template <class OtherPolicy>
typename SocketHandle<Policy>::template IsCompatible<OtherPolicy>::type const &
operator=(ClientSocketHandle<OtherPolicy> other);
+# else
+ template <class OtherPolicy>
+ OtherPolicy const & operator=(ClientSocketHandle<OtherPolicy> other);
+# endif
///@}
///////////////////////////////////////////////////////////////////////////
/** \brief Read data from socket
If the sockets \c FramingPolicy is \c DatagramFramingPolicy, every read() command will
- return a single datagram. If the sockets FramingPolicy is StreamFraming, the operation will
- return as much data as possible from the socket buffer. However it cannot be guaranteed,
- that the socket buffer will be empty after read() returns.
+ return a single datagram. If the sockets FramingPolicy is StreamFraming, the operation
+ will return as much data as possible from the socket buffer. However it cannot be
+ guaranteed, that the socket buffer will be empty after read() returns.
\attention If the space available for the data read is limited, the read will return no
more than that amount of data. For a datagram socket, a full datagram is still dequeued
from the socket buffer, the remainder of the datagram will be lost.
- There are three variants of read which differ in how they return the read string.
+ There are several variants of read which differ in how they return the read string.
- \throws senf::SystemException
+ If the further document doesn't tell something differently, on a blocking socket the
+ members will \e always return some data (as long as the socket has not been closed at
+ the other end) and will block, if no data is available now. If you do not want to block,
+ you \e must make the socket non-blocking (using FileHandle::blocking()).
+
+ \throws senf::SystemException
This variant will read up to \c limit bytes from the
socket and return them as a \c std::string object.
- On a blocking socket, this member will \e always return some data (as long as the socket
- has not been closed at the other end) and will block, if no data is available now. If
- you do not want to block, you \e must make the socket non-blocking (using
- FileHandle::blocking()).
-
\param[in] limit Maximum number of bytes to read or 0 if unlimited.
\returns data read
\c recv.
*/
std::string read (unsigned limit=0);
- void read (std::string & buffer, unsigned limit=0);
- ///< Read data into string buffer
- /**< On a blocking socket, this member will \e always return
- some data (as long as the socket has not been closed at
- the other end) and will block, if no data is available
- now. If you do not want to block, you \e must make the
- socket non-blocking (using FileHandle::blocking()).
- \param[out] buffer data read
- \param[in] limit Maximum number of bytes to read or 0
- if unlimited
- \see \ref read() */
- unsigned read (char * buffer, unsigned size);
+ template <class ForwardWritableRange>
+# ifndef DOXYGEN
+ typename boost::range_iterator<ForwardWritableRange>::type
+ read (ForwardWritableRange const & range,
+ typename boost::disable_if< boost::is_convertible<ForwardWritableRange,unsigned> >::type * = 0);
+# else
+ typename boost::range_iterator<ForwardWritableRange>::type
+ read (ForwardWritableRange const & range);
+ ///< Read data into range
+ /**< Read data into the given range. At most
+ <tt>boost::size(range)</tt> characters are read. The
+ data read will start at the beginning of the
+ range. read returns a past-the-end iterator after the
+ last character read. This iterator will point to
+ somewhere within the input range.
+ \param[in,out] range Range to store data in
+ \returns past-the-end iterator pointer to after the
+ last read character
+ \see \ref read() \n
+ <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a> */
+# endif
+# ifndef DOXYGEN
+ template <class ForwardWritableRange>
+ typename boost::range_iterator<ForwardWritableRange>::type
+ read (ForwardWritableRange & range,
+ typename boost::disable_if< boost::is_convertible<ForwardWritableRange,unsigned> >::type * = 0);
+# else
+ template <class ForwardWritableRange>
+ typename boost::range_iterator<ForwardWritableRange>::type
+ read (ForwardWritableRange & range);
+ ///< Read data into range
+ /**< \see read(ForwardWritableRange const &) \n
+ read() \n
+ <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a> */
+# endif
+ template <class Sequence>
+ void read (Sequence & container, unsigned limit);
+ ///< Read data into container
+ /**< The data read is written into the given container. Old
+ data in the container will be removed. For this to
+ work, the container must be a model of 'Sequence' as
+ defined in the STL documentation
+ \param[out] container Container to write data to
+ \param[in] limit Maximum number of characters to read
+ \see \ref read() */
+ char * read (char * start, char * end);
///< Read data into memory area
- /**< This variant will read data into the memory area at \c
- buffer of size \c size. This is the most performant
- version of read().
- \param[in] buffer address of buffer to store data at
- \param[in] size size of memory buffer
- \returns Number of bytes read
- \see \ref read() */
+ /**< This variant will read data into the memory area from
+ \a start to before \a end. This is guaranteed to be the
+ most efficient version of read().
+ \param[in] start address of buffer to store data at
+ \param[in] end address one past the end of the buffer
+ \returns pointer past the end of the data read
+ \see \ref read() */
/** \brief Read data from unconnected socket returning address
- This member behaves like read() but should only be available, if the sockets \c
- CommunicationPolicy is \c UnconnectedCommunicationPolicy and the \c AddressingPolicy is
- not \c NoAddressingPolicy. The readfrom() family will in addition to the data return the
- address of the sender.
+ The readfrom() group of member behaves like \ref read() but should only be available, if
+ the sockets \c CommunicationPolicy is \c UnconnectedCommunicationPolicy and the \c
+ AddressingPolicy is not \c NoAddressingPolicy. readfrom() will in addition to the data
+ return the address of the sender.
\throws senf::SystemException
+
This variant will return the data read and the address as a std::pair.
\returns \c std::pair of data read (a string) and the peers address
- \fixme Add \c limit argument
-
\implementation The readfrom() family of members will use \c recvfrom from the BSD
socket API.
*/
std::pair<std::string, Address>
- readfrom ();
- void readfrom (std::string & buffer, Address & from);
- ///< Read data into string buffer
- /**< This variant will return the result in the locations
- passed in
- \param[out] buffer data read
- \param[out] from peer address
- \see \ref readfrom() */
- unsigned readfrom (char * buffer, unsigned size, Address & from);
+ readfrom (unsigned limit=0);
+ template <class ForwardWritableRange>
+ typename boost::range_iterator<ForwardWritableRange const>::type
+ readfrom (ForwardWritableRange const & range, Address & from);
+ ///< Read data into range
+ /**< Read data into the given range. At most
+ <tt>boost::size(range)</tt> characters are read. The
+ data read will start at the beginning of the
+ range. read returns a past-the-end iterator after the
+ last character read. This iterator will point to
+ somewhere within the input range.
+ \param[in,out] range Range to store data in
+ \param[out] from peers address from which the data was
+ received
+ \returns past-the-end iterator pointer to after the
+ last read character
+ \see \ref readfrom() \n
+ <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a> */
+ template <class ForwardWritableRange>
+ typename boost::range_iterator<ForwardWritableRange>::type
+ readfrom (ForwardWritableRange & range, Address & from);
+ ///< Read data into range
+ /**< \see readfrom(ForwardWritableRange const&,Address&) \n
+ readfrom() \n
+ <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a> */
+ template <class Sequence>
+ void readfrom (Sequence & container, Address & from, unsigned limit);
+ ///< Read data into container
+ /**< The data read is written into the given container. Old
+ data in the container will be removed. For this to
+ work, the container must be a model of 'Sequence' as
+ defined in the STL documentation
+ \param[out] container Container to write data to
+ \param[in] limit Maximum number of characters to read
+ \param[out] from peers address from which the data was
+ received
+ \see \ref readfrom() */
+ char * readfrom (char * start, char * end, Address & from);
///< Read data into memory buffer
- /**< This variant will read data into the memory area at \c
- buffer of size \c size. This is the most performant
- version of readfrom().
- \param[in] buffer address of buffer to store data at
- \param[in] size size of buffer
- \param[out] from peer address
- \returns Number of bytes read
- \see \ref readfrom() */
+ /**< This variant will read data into the memory area from
+ \a start to before \a end. This is guaranteed to be the
+ most efficient version of readfrom().
+ \param[in] start address of buffer to store data at
+ \param[in] end address one past the end of the buffer
+ \param[out] from peers address from which the data was
+ received
+ \returns pointer past the end of the data read
+ \see \ref read() */
/** \brief Write data to socket
\throws senf::SystemException
- This variant will write out the string \c data.
+ This variant will write out the range \c data.
- \param[in] data Data to write
- \returns number of bytes written
+ \param[in] range Data to write
+ \returns past-the-end iterator after last element written
\implementation The write() family of members will use POSIX \c write calls, not \c
send.
*/
- unsigned write (std::string const & data);
- unsigned write (char const * buffer, unsigned size);
+ template <class ForwardReadableRange>
+ typename boost::range_const_iterator<ForwardReadableRange const>::type
+ write (ForwardReadableRange const & range);
+ char const * write (char const * start, char const * end);
///< Write data to socket from memory buffer
- /**< \param[in] buffer address of buffer to write
- \param[in] size amount of data to write
- \returns Number of bytes written
- \see \ref write() */
+ /**< \param[in] start beginning of area to write
+ \param[in] end past-the-end pointer to area to write
+ \returns past-the-end pointer after last byte written
+ \see \ref write() \n
+ <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a> */
/** \brief Write data to unconnected socket
\throw senf::SystemException
- This variant will send the string \c data to the peer \c addr.
+ This variant will send the range \c range to peer \c addr.
\param[in] addr Address of peer to send data to
- \param[in] data data to send
+ \param[in] range data to send
\returns Number of bytes written
*/
- unsigned writeto (AddressParam addr, std::string const & data);
- unsigned writeto (AddressParam addr, char const * buffer, unsigned size);
+ template <class ForwardReadableRange>
+ typename boost::range_const_iterator<ForwardReadableRange const>::type
+ writeto (AddressParam addr, ForwardReadableRange const & range);
+ char const * writeto (AddressParam addr, char const * start, char const * end);
///< Write data from memory buffer to unconnected socket
/**< \param[in] addr Address of peer to send data to
- \param[in] buffer address of buffer to write
- \param[in] size amount of data to write
- \returns Number of bytes written
- \see \ref writeto() */
+ \param[in] start address of buffer to write
+ \param[in] end past-the-end pointer after data to write
+ \returns past-the-end iterator after last byte written
+ \see \ref writeto() \n
+ <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a> */
///////////////////////////////////////////////////////////////////////////
///\name Addressing
// c-file-style: "senf"
// indent-tabs-mode: nil
// ispell-local-dictionary: "american"
+// compile-command: "scons -u test"
+// comment-column: 40
// End:
projects / senf.git / blobdiff