senf/Socket/ClientSocketHandle.hh

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