senf/Socket/ClientSocketHandle.hh

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