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