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         \idea add more flexible read/write members for a) boost::arrays and arrays of other types b)
  83         std::vector (which uses contiguous memory ..) c) other random-access containers (we should
  84         use some configurable trait class to identify containers with contiguous storage). Probably
  85         we should just use a generic Boost.Range interface. Here we again come to the point: make
  86         all except the most basic members be non-member algorithms ? this would make the
  87         configuration of such extenden members more flexible.
  88
  89         \see \ref policy_group \n
  90              \ref protocol_group
  91       */
  92     template <class Policy>
  93     class ClientSocketHandle
  94         : public SocketHandle<Policy>
  95     {
  96     public:
  97         ///////////////////////////////////////////////////////////////////////////
  98         // Types
  99
 100         /// Address type from the addressing policy
 101         typedef typename Policy::AddressingPolicy::Address Address;
 102         /// 'Best' type for passing address as parameter
 103         /** Depending on the type of \c Address, this will be either <tt>Address</tt> or <tt>Address
 104             const &</tt>. See <a
 105             href="http://www.boost.org/libs/utility/call_traits.htm">call_traits documentation in
 106             the Boost.Utility library.</a>
 107          */
 108         typedef typename boost::call_traits<Address>::param_type AddressParam;
 109         /// Corresponding server socket handle with the same policy
 110         /** This class will probably only be usable, if the \c CommunicationPolicy is \c
 111             ConnectedCommunicationPolicy and the \c AddressingPolicy is not \c
 112             NoAddressingPolicy. */
 113         typedef ServerSocketHandle<Policy> ServerSocketHandle;
 114
 115         ///////////////////////////////////////////////////////////////////////////
 116         ///\name Structors and default members
 117         ///@{
 118
 119         // no default constructor
 120         // default copy constructor
 121         // default copy assignment
 122         // default destructor
 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() */
 185         template <class ForwardWritableRange>
 186         typename boost::range_iterator<ForwardWritableRange>::type
 187                      read         (ForwardWritableRange & range);
 188                                         ///< Read data into range
 189                                         /**< \see
 190                                              read(ForwardWritableRange const &) \n
 191                                              read() */
 192         template <class Sequence>
 193         void         read         (Sequence & container, unsigned limit);
 194                                         ///< Read data into container
 195                                         /**< The data read is written into the given container. Old
 196                                              data in the container will be removed. For this to
 197                                              work, the container must be a model of 'Sequence' as
 198                                              defined in the STL documentation
 199                                              \param[out] container Container to write data to
 200                                              \param[in] limit Maximum number of characters to read
 201                                              \see \ref read() */
 202         char *       read         (char * start, char * end);
 203                                         ///< Read data into memory area
 204                                         /**< This variant will read data into the memory area from
 205                                              \a start to before \a end. This is guaranteed to be the
 206                                              most efficient version  of read().
 207                                              \param[in] start address of buffer to store data at
 208                                              \param[in] end address one past the end of the buffer
 209                                              \returns pointer past the end of the data read
 210                                              \see \ref read() */
 211
 212         /** \brief Read data from unconnected socket returning address
 213
 214             The readfrom() group of member behaves like \ref read() but should only be available, if
 215             the sockets \c CommunicationPolicy is \c UnconnectedCommunicationPolicy and the \c
 216             AddressingPolicy is not \c NoAddressingPolicy. readfrom() will in addition to the data
 217             return the address of the sender.
 218
 219             \throws senf::SystemException
 220
 221
 222             This variant will return the data read and the address as a std::pair.
 223
 224             \returns \c std::pair of data read (a string) and the peers address
 225
 226             \implementation The readfrom() family of members will use \c recvfrom from the BSD
 227             socket API.
 228          */
 229         std::pair<std::string, Address>
 230                      readfrom     (unsigned limit=0);
 231         template <class ForwardWritableRange>
 232         typename boost::range_iterator<ForwardWritableRange>::type
 233                      readfrom     (ForwardWritableRange const & range, Address & from);
 234                                         ///< Read data into range
 235                                         /**< Read data into the given range. At most
 236                                              <tt>boost::size(range)</tt> characters are read. The
 237                                              data read will start at the beginning of the
 238                                              range. read returns a past-the-end iterator after the
 239                                              last character read. This iterator will point to
 240                                              somewhere within the input range.
 241                                              \param[in/out] range Range to store data in
 242                                              \param[out] from peers address from which the data was
 243                                                  received
 244                                              \returns past-the-end iterator pointer to after the
 245                                                  last read character
 246                                              \see \ref readfrom() */
 247         template <class ForwardWritableRange>
 248         typename boost::range_iterator<ForwardWritableRange>::type
 249                      readfrom     (ForwardWritableRange & range, Address & from);
 250                                         ///< Read data into range
 251                                         /**< \see
 252                                              readfrom(ForwardWritableRange const&,Address&) \n
 253                                              readfrom() */
 254         template <class Sequence>
 255         void         readfrom     (Sequence & container, Address & from, unsigned limit);
 256                                         ///< Read data into container
 257                                         /**< The data read is written into the given container. Old
 258                                              data in the container will be removed. For this to
 259                                              work, the container must be a model of 'Sequence' as
 260                                              defined in the STL documentation
 261                                              \param[out] container Container to write data to
 262                                              \param[in] limit Maximum number of characters to read
 263                                              \param[out] from peers address from which the data was
 264                                                  received
 265                                              \see \ref readfrom() */
 266         char *       readfrom     (char * start, char * end, Address & from);
 267                                         ///< Read data into memory buffer
 268                                         /**< This variant will read data into the memory area at \c
 269                                            buffer of size \c size. This is the most performant
 270                                            version of readfrom().
 271                                            \param[in] buffer address of buffer to store data at
 272                                            \param[in] size size of buffer
 273                                            \param[out] from peer address
 274                                            \returns Number of bytes read
 275                                            \see \ref readfrom() */
 276
 277
 278         /** \brief Write data to socket
 279
 280             The write() family of members will write out the data to the socket.  If the sockets \c
 281             FramingPolicy is \c DatagramFramingPolicy, every write() call will result in one
 282             datagram.
 283
 284             A single write call might depending on the circumstances write only part of the data.
 285
 286             There are two variants of this member
 287
 288             \throws senf::SystemException
 289
 290
 291             This variant will write out the string \c data.
 292
 293             \param[in] data Data to write
 294             \returns number of bytes written
 295             \implementation The write() family of members will use POSIX \c write calls, not \c
 296                 send.
 297          */
 298         unsigned     write        (std::string const & data);
 299         unsigned     write        (char const * buffer, unsigned size);
 300                                         ///< Write data to socket from memory buffer
 301                                         /**< \param[in] buffer address of buffer to write
 302                                            \param[in] size amount of data to write
 303                                            \returns Number of bytes written
 304                                            \see \ref write() */
 305
 306         /** \brief Write data to unconnected socket
 307
 308             This member behaves like write() but should only be available, if the sockets \c
 309             CommunicationPolicy is \c UnconnectedCommunicationPolicy and the \c AddressingPolicy is
 310             not \c NoAddressingPolicy. The writeto() family of members takes the target address as
 311             an additional argument.
 312
 313             There are two variants of this member.
 314
 315             \throw senf::SystemException
 316
 317
 318             This variant will send the string \c data to the peer \c addr.
 319
 320             \param[in] addr Address of peer to send data to
 321             \param[in] data data to send
 322             \returns Number of bytes written
 323          */
 324         unsigned     writeto      (AddressParam addr, std::string const & data);
 325         unsigned     writeto      (AddressParam addr, char const * buffer, unsigned size);
 326                                         ///< Write data from memory buffer to unconnected socket
 327                                         /**< \param[in] addr Address of peer to send data to
 328                                            \param[in] buffer address of buffer to write
 329                                            \param[in] size amount of data to write
 330                                            \returns Number of bytes written
 331                                            \see \ref writeto() */
 332
 333         ///////////////////////////////////////////////////////////////////////////
 334         ///\name Addressing
 335         ///@{
 336
 337         /** \brief Connect to remote peer
 338
 339             This member will establish a connection for addressable connection-oriented protocols
 340             (that is, the CommunicationPolicy is ConnectedCommunicationPolicy and the
 341             AddressingPolicy is not NoAddressingPolicy).
 342
 343             \param[in] addr Address to connect to
 344
 345             \throws senf::SystemException
 346          */
 347         void         connect      (AddressParam addr);
 348
 349         /** \brief Set local address
 350
 351             For addressable protocols (AddressingPolicy is not NoAddressingPolicy), bind() will set
 352             the local address of the socket.
 353
 354             \param[in] addr Local socket address to asign
 355
 356             \throws senf::SystemException
 357          */
 358         void         bind         (AddressParam addr);
 359
 360         /** \brief Query remote address
 361
 362             This member will return the address of the communication partner in addressable
 363             connection-oriented protocols (that is, the CommunicationPolicy is
 364             ConnectedCommunicationPolicy and the AddressingPolicy is not NoAddressingPolicy).
 365
 366             There are two Variants of this member, one will return the address by value, the other
 367             takes a reference argument to elide the copy operation.
 368
 369             \throws senf::SystemException
 370          */
 371         Address      peer         ();
 372         void         peer         (Address & addr);
 373                                         ///< Query remote address
 374                                         /**< \see \ref peer() */
 375
 376         /** \brief Query local address
 377
 378             This member will return the address of the local socket in addressable protocols
 379             (AddressingPolicy is not NoAddressingPolicy).
 380
 381             There are two Variants of this member, one will return the address by value, the other
 382             takes a reference argument to elide the copy operation.
 383
 384             \throws senf::SystemException
 385          */
 386         Address      local        ();
 387         void         local        (Address & addr);
 388                                         ///< Query local address
 389                                         /**< \see \ref local() */
 390
 391         ///@}
 392
 393         ///////////////////////////////////////////////////////////////////////////
 394         ///\name Buffering
 395         ///@{
 396
 397         unsigned     rcvbuf      ();    ///< Check size of receive buffer
 398                                         /**< \returns size of receive buffer in bytes */
 399         void         rcvbuf      (unsigned size);
 400                                         ///< Set size of receive buffer
 401                                         /**< \param[in] size size of receive buffer in bytes */
 402
 403         unsigned     sndbuf      ();    ///< Check size of send buffer
 404                                         /**< \returns size of send buffer in bytes */
 405         void         sndbuf      (unsigned size);
 406                                         ///< Set size of send buffer
 407                                         /**< \param[in] size size of send buffer in bytes */
 408
 409         ///@}
 410
 411         static ClientSocketHandle cast_static(FileHandle handle);
 412         static ClientSocketHandle cast_dynamic(FileHandle handle);
 413
 414         // we need to override both since SocketHandle is *not* polymorphic
 415         void state(SocketStateMap & map, unsigned lod=0);
 416         std::string dumpState(unsigned lod=0);
 417
 418     protected:
 419         ClientSocketHandle(FileHandle other, bool isChecked);
 420         explicit ClientSocketHandle(std::auto_ptr<SocketProtocol> protocol,
 421                                     int fd = -1);
 422
 423     private:
 424         unsigned available();
 425
 426         friend class senf::ServerSocketHandle<Policy>;
 427     };
 428
 429     /// @}
 430 }
 431
 432 ///////////////////////////////hh.e////////////////////////////////////////
 433 //#include "ClientSocketHandle.cci"
 434 #include "ClientSocketHandle.ct"
 435 #include "ClientSocketHandle.cti"
 436 #endif
 437
 438 \f
 439 // Local Variables:
 440 // mode: c++
 441 // fill-column: 100
 442 // c-file-style: "senf"
 443 // indent-tabs-mode: nil
 444 // ispell-local-dictionary: "american"
 445 // End: