Socket/ClientSocketHandle.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2006
   4 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
   5 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
   6 //     Stefan Bund <stefan.bund@fokus.fraunhofer.de>
   7 //
   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.
  12 //
  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.
  17 //
  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.
  22
  23 /** \file
  24     \brief ClientSocketHandle public header
  25  */
  26
  27 #ifndef HH_ClientSocketHandle_
  28 #define HH_ClientSocketHandle_ 1
  29
  30 // Custom includes
  31 #include <boost/call_traits.hpp>
  32 #include <boost/range.hpp>
  33 #include "SocketHandle.hh"
  34
  35 //#include "ClientSocketHandle.mpp"
  36 ///////////////////////////////hh.p////////////////////////////////////////
  37
  38 namespace senf {
  39
  40     /// \addtogroup handle_group
  41     /// @{
  42
  43     template <class Policy> class ServerSocketHandle;
  44
  45     /** \brief Generic SocketHandle with client interface
  46
  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. The following table shows, to which policy members each
  50         group of ClientSocketHandle members is forwardd. The last collumn shows, on which other
  51         policies this member-group depends <em>in the default policy classes</em>. If you define
  52         your own policy classes, the dependencies are up to you.
  53
  54         <table class="senf">
  55         <tr><th>ClientSocketHandle member</th> <th>Policy member</th> <th>Other policies</th></tr>
  56         <tr><td>read()</td>       <td>ReadPolicy::read (\ref senf::ReadPolicyBase)</td>                  <td></td></tr>
  57         <tr><td>readfrom()</td>   <td>ReadPolicy::readfrom (\ref senf::ReadPolicyBase)</td>              <td>UnconnectedCommunicationPolicy</td></tr>
  58         <tr><td>write()</td>      <td>WritePolicy::write (\ref senf::WritePolicyBase)</td>               <td>ConnectedCommunicationPolicy</td></tr>
  59         <tr><td>writeto()</td>    <td>WritePolicy::writeto (\ref senf::WritePolicyBase)</td>             <td>UnconnectedCommunicationPolicy</td></tr>
  60         <tr><td>connect()</td>    <td>AddressingPolicy::connect (\ref senf::AddressingPolicyBase)</td>   <td></td></tr>
  61         <tr><td>bind()</td>       <td>AddressingPolicy::bind (\ref senf::AddressingPolicyBase)</td>      <td></td></tr>
  62         <tr><td>peer()</td>       <td>AddressingPolicy::peer (\ref senf::AddressingPolicyBase)</td>      <td></td></tr>
  63         <tr><td>local()</td>      <td>AddressingPolicy::local (\ref senf::AddressingPolicyBase)</td>     <td></td></tr>
  64         <tr><td>rcvbuf()</td>     <td>BufferingPolicy::sndbuf (\ref senf::BufferingPolicyBase)</td>      <td></td></tr>
  65         <tr><td>sndbuf()</td>     <td>BufferingPolicy::rcvbuf (\ref senf::BufferingPolicyBase)</td>      <td></td></tr>
  66         </table>
  67
  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.
  73
  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
  76         documentation.
  77
  78         \todo Move all not template-parameter dependent code into a non-template base class
  79
  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.
  84
  85         \see \ref policy_group \n
  86              \ref protocol_group
  87
  88         \fixme Add enable_if conditions so anything convertible to unsigned will not be interpreted
  89             as a Range template argument but will use the unsigned variant of
  90             read/readfrom/write/writeto.
  91       */
  92     template <class Policy>
  93     class ClientSocketHandle
  94         : public SocketHandle<Policy>
  95     {
  96     public:
  97         ///////////////////////////////////////////////////////////////////////////
  98         // Types
  99
 100         /// Address type from the addressing policy
 101         typedef typename Policy::AddressingPolicy::Address Address;
 102         /// 'Best' type for passing address as parameter
 103         /** Depending on the type of \c Address, this will be either <tt>Address</tt> or <tt>Address
 104             const &</tt>. See <a
 105             href="http://www.boost.org/libs/utility/call_traits.htm">call_traits documentation in
 106             the Boost.Utility library.</a>
 107          */
 108         typedef typename boost::call_traits<Address>::param_type AddressParam;
 109         /// Corresponding server socket handle with the same policy
 110         /** This class will probably only be usable, if the \c CommunicationPolicy is \c
 111             ConnectedCommunicationPolicy and the \c AddressingPolicy is not \c
 112             NoAddressingPolicy. */
 113         typedef ServerSocketHandle<Policy> ServerSocketHandle;
 114
 115         ///////////////////////////////////////////////////////////////////////////
 116         ///\name Structors and default members
 117         ///@{
 118
 119         // default default constructor
 120         // default copy constructor
 121         // default copy assignment
 122         // default destructor
 123
 124         // here to implement
 125         ClientSocketHandle();
 126
 127         // conversion constructors
 128         template <class OtherPolicy>
 129         ClientSocketHandle(ClientSocketHandle<OtherPolicy> other,
 130                            typename SocketHandle<Policy>::template IsCompatible<OtherPolicy>::type * = 0);
 131
 132         template <class OtherPolicy>
 133         typename SocketHandle<Policy>::template IsCompatible<OtherPolicy>::type const &
 134         operator=(ClientSocketHandle<OtherPolicy> other);
 135
 136         ///@}
 137         ///////////////////////////////////////////////////////////////////////////
 138
 139         ///////////////////////////////////////////////////////////////////////////
 140         ///\name Reading and Writing
 141         ///@{
 142
 143         /** \brief Read data from socket
 144
 145             If the sockets \c FramingPolicy is \c DatagramFramingPolicy, every read() command will
 146             return a single datagram. If the sockets FramingPolicy is StreamFraming, the operation
 147             will return as much data as possible from the socket buffer. However it cannot be
 148             guaranteed, that the socket buffer will be empty after read() returns.
 149
 150             \attention If the space available for the data read is limited, the read will return no
 151             more than that amount of data. For a datagram socket, a full datagram is still dequeued
 152             from the socket buffer, the remainder of the datagram will be lost.
 153
 154             There are several variants of read which differ in how they return the read string.
 155
 156             If the further document doesn't tell something differently, on a blocking socket the
 157             members will \e always return some data (as long as the socket has not been closed at
 158             the other end) and will block, if no data is available now. If you do not want to block,
 159             you \e must make the socket non-blocking (using FileHandle::blocking()).
 160
 161             \throws senf::SystemException
 162
 163
 164             This variant will read up to \c limit bytes from the
 165             socket and return them as a \c std::string object.
 166
 167             \param[in] limit Maximum number of bytes to read or 0 if unlimited.
 168             \returns data read
 169
 170             \implementation The read() family of members will use standard POSIX \c read calls, not
 171             \c recv.
 172         */
 173         std::string  read         (unsigned limit=0);
 174         template <class ForwardWritableRange>
 175         typename boost::range_iterator<ForwardWritableRange>::type
 176                      read         (ForwardWritableRange const & range);
 177                                         ///< Read data into range
 178                                         /**< Read data into the given range. At most
 179                                              <tt>boost::size(range)</tt> characters are read. The
 180                                              data read will start at the beginning of the
 181                                              range. read returns a past-the-end iterator after the
 182                                              last character read. This iterator will point to
 183                                              somewhere within the input range.
 184                                              \param[in,out] range Range to store data in
 185                                              \returns past-the-end iterator pointer to after the
 186                                                  last read character
 187                                              \see \ref read() \n
 188                                                   <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a> */
 189         template <class ForwardWritableRange>
 190         typename boost::range_iterator<ForwardWritableRange>::type
 191                      read         (ForwardWritableRange & range);
 192                                         ///< Read data into range
 193                                         /**< \see read(ForwardWritableRange const &) \n
 194                                                   read() \n
 195                                                   <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a>  */
 196         template <class Sequence>
 197         void         read         (Sequence & container, unsigned limit);
 198                                         ///< Read data into container
 199                                         /**< The data read is written into the given container. Old
 200                                              data in the container will be removed. For this to
 201                                              work, the container must be a model of 'Sequence' as
 202                                              defined in the STL documentation
 203                                              \param[out] container Container to write data to
 204                                              \param[in] limit Maximum number of characters to read
 205                                              \see \ref read() */
 206         char *       read         (char * start, char * end);
 207                                         ///< Read data into memory area
 208                                         /**< This variant will read data into the memory area from
 209                                              \a start to before \a end. This is guaranteed to be the
 210                                              most efficient version  of read().
 211                                              \param[in] start address of buffer to store data at
 212                                              \param[in] end address one past the end of the buffer
 213                                              \returns pointer past the end of the data read
 214                                              \see \ref read() */
 215
 216         /** \brief Read data from unconnected socket returning address
 217
 218             The readfrom() group of member behaves like \ref read() but should only be available, if
 219             the sockets \c CommunicationPolicy is \c UnconnectedCommunicationPolicy and the \c
 220             AddressingPolicy is not \c NoAddressingPolicy. readfrom() will in addition to the data
 221             return the address of the sender.
 222
 223             \throws senf::SystemException
 224
 225
 226             This variant will return the data read and the address as a std::pair.
 227
 228             \returns \c std::pair of data read (a string) and the peers address
 229
 230             \implementation The readfrom() family of members will use \c recvfrom from the BSD
 231             socket API.
 232          */
 233         std::pair<std::string, Address>
 234                      readfrom     (unsigned limit=0);
 235         template <class ForwardWritableRange>
 236         typename boost::range_iterator<ForwardWritableRange const>::type
 237                      readfrom     (ForwardWritableRange const & range, Address & from);
 238                                         ///< Read data into range
 239                                         /**< Read data into the given range. At most
 240                                              <tt>boost::size(range)</tt> characters are read. The
 241                                              data read will start at the beginning of the
 242                                              range. read returns a past-the-end iterator after the
 243                                              last character read. This iterator will point to
 244                                              somewhere within the input range.
 245                                              \param[in,out] range Range to store data in
 246                                              \param[out] from peers address from which the data was
 247                                                  received
 248                                              \returns past-the-end iterator pointer to after the
 249                                                  last read character
 250                                              \see \ref readfrom() \n
 251                                                   <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a>  */
 252         template <class ForwardWritableRange>
 253         typename boost::range_iterator<ForwardWritableRange>::type
 254                      readfrom     (ForwardWritableRange & range, Address & from);
 255                                         ///< Read data into range
 256                                         /**< \see readfrom(ForwardWritableRange const&,Address&) \n
 257                                                   readfrom()  \n
 258                                                   <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a> */
 259         template <class Sequence>
 260         void         readfrom     (Sequence & container, Address & from, unsigned limit);
 261                                         ///< Read data into container
 262                                         /**< The data read is written into the given container. Old
 263                                              data in the container will be removed. For this to
 264                                              work, the container must be a model of 'Sequence' as
 265                                              defined in the STL documentation
 266                                              \param[out] container Container to write data to
 267                                              \param[in] limit Maximum number of characters to read
 268                                              \param[out] from peers address from which the data was
 269                                                  received
 270                                              \see \ref readfrom() */
 271         char *       readfrom     (char * start, char * end, Address & from);
 272                                         ///< Read data into memory buffer
 273                                         /**< This variant will read data into the memory area from
 274                                              \a start to before \a end. This is guaranteed to be the
 275                                              most efficient version  of readfrom().
 276                                              \param[in] start address of buffer to store data at
 277                                              \param[in] end address one past the end of the buffer
 278                                              \param[out] from peers address from which the data was
 279                                                  received
 280                                              \returns pointer past the end of the data read
 281                                              \see \ref read() */
 282
 283
 284         /** \brief Write data to socket
 285
 286             The write() family of members will write out the data to the socket.  If the sockets \c
 287             FramingPolicy is \c DatagramFramingPolicy, every write() call will result in one
 288             datagram.
 289
 290             A single write call might depending on the circumstances write only part of the data.
 291
 292             There are two variants of this member
 293
 294             \throws senf::SystemException
 295
 296
 297             This variant will write out the range \c data.
 298
 299             \param[in] range Data to write
 300             \returns past-the-end iterator after last element written
 301             \implementation The write() family of members will use POSIX \c write calls, not \c
 302                 send.
 303          */
 304         template <class ForwardReadableRange>
 305         typename boost::range_const_iterator<ForwardReadableRange const>::type
 306                      write        (ForwardReadableRange const & range);
 307         char const * write        (char const * start, char const * end);
 308                                         ///< Write data to socket from memory buffer
 309                                         /**< \param[in] start beginning of area to write
 310                                              \param[in] end past-the-end pointer to area to write
 311                                              \returns past-the-end pointer after last byte written
 312                                              \see \ref write() \n
 313                                                   <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a>  */
 314
 315         /** \brief Write data to unconnected socket
 316
 317             This member behaves like write() but should only be available, if the sockets \c
 318             CommunicationPolicy is \c UnconnectedCommunicationPolicy and the \c AddressingPolicy is
 319             not \c NoAddressingPolicy. The writeto() family of members takes the target address as
 320             an additional argument.
 321
 322             There are two variants of this member.
 323
 324             \throw senf::SystemException
 325
 326
 327             This variant will send the range \c range to peer \c addr.
 328
 329             \param[in] addr Address of peer to send data to
 330             \param[in] range data to send
 331             \returns Number of bytes written
 332          */
 333         template <class ForwardReadableRange>
 334         typename boost::range_const_iterator<ForwardReadableRange const>::type
 335                      writeto      (AddressParam addr, ForwardReadableRange const & range);
 336         char const * writeto      (AddressParam addr, char const * start, char const * end);
 337                                         ///< Write data from memory buffer to unconnected socket
 338                                         /**< \param[in] addr Address of peer to send data to
 339                                              \param[in] start address of buffer to write
 340                                              \param[in] end past-the-end pointer after data to write
 341                                              \returns past-the-end iterator after last byte written
 342                                              \see \ref writeto() \n
 343                                                   <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a>  */
 344
 345         ///////////////////////////////////////////////////////////////////////////
 346         ///\name Addressing
 347         ///@{
 348
 349         /** \brief Connect to remote peer
 350
 351             This member will establish a connection for addressable connection-oriented protocols
 352             (that is, the CommunicationPolicy is ConnectedCommunicationPolicy and the
 353             AddressingPolicy is not NoAddressingPolicy).
 354
 355             \param[in] addr Address to connect to
 356
 357             \throws senf::SystemException
 358          */
 359         void         connect      (AddressParam addr);
 360
 361         /** \brief Set local address
 362
 363             For addressable protocols (AddressingPolicy is not NoAddressingPolicy), bind() will set
 364             the local address of the socket.
 365
 366             \param[in] addr Local socket address to asign
 367
 368             \throws senf::SystemException
 369          */
 370         void         bind         (AddressParam addr);
 371
 372         /** \brief Query remote address
 373
 374             This member will return the address of the communication partner in addressable
 375             connection-oriented protocols (that is, the CommunicationPolicy is
 376             ConnectedCommunicationPolicy and the AddressingPolicy is not NoAddressingPolicy).
 377
 378             There are two Variants of this member, one will return the address by value, the other
 379             takes a reference argument to elide the copy operation.
 380
 381             \throws senf::SystemException
 382          */
 383         Address      peer         ();
 384         void         peer         (Address & addr);
 385                                         ///< Query remote address
 386                                         /**< \see \ref peer() */
 387
 388         /** \brief Query local address
 389
 390             This member will return the address of the local socket in addressable protocols
 391             (AddressingPolicy is not NoAddressingPolicy).
 392
 393             There are two Variants of this member, one will return the address by value, the other
 394             takes a reference argument to elide the copy operation.
 395
 396             \throws senf::SystemException
 397          */
 398         Address      local        ();
 399         void         local        (Address & addr);
 400                                         ///< Query local address
 401                                         /**< \see \ref local() */
 402
 403         ///@}
 404
 405         ///////////////////////////////////////////////////////////////////////////
 406         ///\name Buffering
 407         ///@{
 408
 409         unsigned     rcvbuf      ();    ///< Check size of receive buffer
 410                                         /**< \returns size of receive buffer in bytes */
 411         void         rcvbuf      (unsigned size);
 412                                         ///< Set size of receive buffer
 413                                         /**< \param[in] size size of receive buffer in bytes */
 414
 415         unsigned     sndbuf      ();    ///< Check size of send buffer
 416                                         /**< \returns size of send buffer in bytes */
 417         void         sndbuf      (unsigned size);
 418                                         ///< Set size of send buffer
 419                                         /**< \param[in] size size of send buffer in bytes */
 420
 421         ///@}
 422
 423         static ClientSocketHandle cast_static(FileHandle handle);
 424         static ClientSocketHandle cast_dynamic(FileHandle handle);
 425
 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);
 429
 430     protected:
 431         ClientSocketHandle(FileHandle other, bool isChecked);
 432         explicit ClientSocketHandle(std::auto_ptr<SocketProtocol> protocol,
 433                                     int fd = -1);
 434
 435     private:
 436         unsigned available();
 437
 438         friend class senf::ServerSocketHandle<Policy>;
 439     };
 440
 441     /// @}
 442 }
 443
 444 ///////////////////////////////hh.e////////////////////////////////////////
 445 //#include "ClientSocketHandle.cci"
 446 #include "ClientSocketHandle.ct"
 447 #include "ClientSocketHandle.cti"
 448 #endif
 449
 450 \f
 451 // Local Variables:
 452 // mode: c++
 453 // fill-column: 100
 454 // c-file-style: "senf"
 455 // indent-tabs-mode: nil
 456 // ispell-local-dictionary: "american"
 457 // compile-command: "scons -u test"
 458 // comment-column: 40
 459 // End: