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