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 senf::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 "SocketHandle.hh"
  33
  34 //#include "ClientSocketHandle.mpp"
  35 ///////////////////////////////hh.p////////////////////////////////////////
  36
  37 namespace senf {
  38
  39     /// \addtogroup handle_group
  40     /// @{
  41
  42     template <class Policy> class ServerSocketHandle;
  43
  44     /** \brief Generic SocketHandle with client interface
  45
  46         This class provides the client side policy interface of the socket
  47         abstraction. ClientSocketHandle defines the complete policy interface. It does not implement
  48         any functionality itself however. All calls are forward to the following policy classes:
  49
  50         <table class="senf">
  51         <tr><th>ClientSocketHandle member</th> <th>Policy member</th></tr>
  52         <tr><td>read()</td>       <td>ReadPolicy::read (\ref senf::ReadPolicyBase)</td></tr>
  53         <tr><td>readfrom()</td>   <td>ReadPolicy::readfrom (\ref senf::ReadPolicyBase)</td></tr>
  54         <tr><td>write()</td>      <td>WritePolicy::write (\ref senf::WritePolicyBase)</td></tr>
  55         <tr><td>writeto()</td>    <td>WritePolicy::writeto (\ref senf::WritePolicyBase)</td></tr>
  56         <tr><td>connect()</td>    <td>AddressingPolicy::connect (\ref senf::AddressingPolicyBase)</td></tr>
  57         <tr><td>bind()</td>       <td>AddressingPolicy::bind (\ref senf::AddressingPolicyBase)</td></tr>
  58         <tr><td>peer()</td>       <td>AddressingPolicy::peer (\ref senf::AddressingPolicyBase)</td></tr>
  59         <tr><td>local()</td>      <td>AddressingPolicy::local (\ref senf::AddressingPolicyBase)</td></tr>
  60         <tr><td>rcvbuf()</td>     <td>BufferingPolicy::sndbuf (\ref senf::BufferingPolicyBase)</td></tr>
  61         <tr><td>sndbuf()</td>     <td>BufferingPolicy::rcvbuf (\ref senf::BufferingPolicyBase)</td></tr>
  62         </table>
  63
  64         It is important to note, that not all members are always accessible. Which are depends on
  65         the \c Policy template argument. If any of the policy axis is left unspecified the
  66         corresponding members will not be callable (you will get a compile time error). Even if
  67         every policy axis is defined, some members might (and will) not exist if they are
  68         meaningless for the protocol of the socket. This depends on the exact policy.
  69
  70         To find out, which members are available, you have to check the documentation of the policy
  71         classes. You can also find a summary of all members available in the leaf protocol class
  72         documentation.
  73
  74         \todo Move all not template-parameter dependent code into a non-template base class
  75
  76         \idea Give SocketHandle (and therefore ClientSocketHandle and ServerSocketHandle) a \c
  77         protocol() template member and an additional template arg \c Policies. This arg should be a
  78         typelist of Poclicy classes which can be accessed. You use protocol<ProtocolClass>() to
  79         access a protocol class. \c Policies can of course be underspecified or even empty.
  80
  81         \idea add more flexible read/write members for a) boost::arrays and arrays of other types b)
  82         std::vector (which uses contiguous memory ..) c) other random-access containers (we should
  83         use some configurable trait class to identify containers with contiguous storage). Probably
  84         we should just use a generic Boost.Range interface. Here we again come to the point: make
  85         all except the most basic members be non-member algorithms ? this would make the
  86         configuration of such extenden members more flexible.
  87
  88         \see \ref policy_group \n
  89              \ref protocol_group
  90       */
  91     template <class Policy>
  92     class ClientSocketHandle
  93         : public SocketHandle<Policy>
  94     {
  95     public:
  96         ///////////////////////////////////////////////////////////////////////////
  97         // Types
  98
  99         /// Address type from the addressing policy
 100         typedef typename Policy::AddressingPolicy::Address Address;
 101         /// 'Best' type for passing address as parameter
 102         /** Depending on the type of \c Address, this will be either <tt>Address</tt> or <tt>Address
 103             const &</tt>. See <a href="http://www.boost.org/libs/utility/call_traits.htm"
 104             class="ext">call_traits documentation in the Boost.Utility library\endlink.</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          */
 112         typedef ServerSocketHandle<Policy> ServerSocketHandle;
 113
 114         ///////////////////////////////////////////////////////////////////////////
 115         ///\name Structors and default members
 116         ///@{
 117
 118         // no default constructor
 119         // default copy constructor
 120         // default copy assignment
 121         // default destructor
 122
 123         // conversion constructors
 124         template <class OtherPolicy>
 125         ClientSocketHandle(ClientSocketHandle<OtherPolicy> other,
 126                            typename SocketHandle<Policy>::template IsCompatible<OtherPolicy>::type * = 0);
 127
 128         template <class OtherPolicy>
 129         typename SocketHandle<Policy>::template IsCompatible<OtherPolicy>::type const &
 130         operator=(ClientSocketHandle<OtherPolicy> other);
 131
 132         ///@}
 133         ///////////////////////////////////////////////////////////////////////////
 134
 135         ///////////////////////////////////////////////////////////////////////////
 136         ///\name Reading and Writing
 137         ///@{
 138
 139         /** \brief Read data from socket
 140
 141             If the sockets \c FramingPolicy is \c DatagramFramingPolicy, every read() command will
 142             return a single datagram. If the sockets FramingPolicy is StreamFraming, the operation will
 143             return as much data as possible from the socket buffer. However it cannot be guaranteed,
 144             that the socket buffer will be empty after read() returns.
 145
 146             \attention If the space available for the data read is limited, the read will return no
 147             more than that amount of data. For a datagram socket, a full datagram is still dequed
 148             from the socket buffer, the remainder of the datagram will be lost.
 149
 150             There are three variants of read which differ in how they return the read string.
 151
 152             \throws senf::SystemException
 153
 154
 155             This variant will read up to \c limit bytes from the
 156             socket and return them as a \c std::string object.
 157
 158             On a blocking socket, this member will \e always return some data (as long as the socket
 159             has not been closed at the other end) and will block, if no data is available now. If
 160             you do not want to block, you \e must make the socket non-blocking (using
 161             FileHandle::blocking()).
 162
 163             \param[in] limit Maximum number of bytes to read or 0 if unlimited.
 164             \returns data read
 165
 166             \implementation The read() family of members will use standard POSIX \c read calls, not
 167             \c recv.
 168         */
 169         std::string  read         (unsigned limit=0);
 170         void         read         (std::string & buffer, unsigned limit=0);
 171                                         ///< Read data into string buffer
 172                                         /**< On a blocking socket, this member will \e always return
 173                                            some data (as long as the socket has not been closed at
 174                                            the other end) and will block, if no data is available
 175                                            now. If you do not want to block, you \e must make the
 176                                            socket non-blocking (using FileHandle::blocking()).
 177                                            \param[out] buffer data read
 178                                            \param[in] limit Maximum number of buytes to read or 0
 179                                            if unlimited
 180                                            \see \ref read() */
 181         unsigned     read         (char * buffer, unsigned size);
 182                                         ///< Read data into memory area
 183                                         /**< This variant will read data into the memory area at \c
 184                                            buffer of size \c size. This is the most performant
 185                                            version of read().
 186                                            \param[in] buffer address of buffer to store data at
 187                                            \param[in] size size of memory buffer
 188                                            \returns Number of bytes read
 189                                            \see \ref read() */
 190
 191         /** \brief Read data from unconnected socket returning address
 192
 193             This member behaves like read() but should only be available, if the sockets \c
 194             CommunicationPolicy is \c UnconnectedCommunicationPolicy and the \c AddressingPolicy is
 195             not \c NoAddressingPolicy. The readfrom() family will in addition to the data return the
 196             address of the sender.
 197
 198             \throws senf::SystemException
 199
 200             This variant will return the data read and the address as a std::pair.
 201
 202             \returns \c std::pair of data read (a string) and the peers address
 203
 204             \todo Add \c limit argument
 205
 206             \implementation The readfrom() family of members will use \c recvfrom from the BSD
 207             socket API.
 208          */
 209         std::pair<std::string, Address>
 210                      readfrom     ();
 211         void         readfrom     (std::string & buffer, Address & from);
 212                                         ///< Read data into string buffer
 213                                         /**< This variant will return the result in the locations
 214                                            passed in
 215                                            \param[out] buffer data read
 216                                            \param[out] from peer address
 217                                            \see \ref readfrom() */
 218         unsigned     readfrom     (char * buffer, unsigned size, Address & from);
 219                                         ///< Read data into memory byffer
 220                                         /**< This variant will read data into the memory area at \c
 221                                            buffer of size \c size. This is the most performant
 222                                            version of readfrom().
 223                                            \param[in] buffer address of buffer to store data at
 224                                            \param[in] size size of bnuffer
 225                                            \param[out] from peer address
 226                                            \returns Number of bytes read
 227                                            \see \ref readfrom() */
 228
 229
 230         /** \brief Write data to socket
 231
 232             The write() family of members will write out the data to the socket.  If the sockets \c
 233             FramingPolicy is \c DatagramFramingPolicy, every write() call will result in one
 234             datagram.
 235
 236             A single write call might depending on the circumstances write only part of the data.
 237
 238             There are two variants of thie member
 239
 240             \throws senf::SystemException
 241
 242
 243             This variant will write out the string \c data.
 244
 245             \param[in] data Data to write
 246             \returns number of bytes written
 247             \todo Make this member write the complete string if the socket is blocking
 248             \implementation The write() family of members will use POSIX \c write calls, not \c
 249                 send.
 250          */
 251         unsigned     write        (std::string const & data);
 252         unsigned     write        (char const * buffer, unsigned size);
 253                                         ///< Write data to socket from memory buffer
 254                                         /**< \param[in] buffer address of buffer to write
 255                                            \param[in] size amount of data to write
 256                                            \returns Number of bytes written
 257                                            \see \ref write() */
 258
 259         /** \brief Write data to unconnected socket
 260
 261             This member behaves like write() but should only be available, if the sockets \c
 262             CommunicationPolicy is \c UnconnectedCommunicationPolicy and the \c AddressingPolicy is
 263             not \c NoAddressingPolicy. The writeto() family of members takes the target address as
 264             an additional argument.
 265
 266             There are two variants of this member.
 267
 268             \throw senf::SystemException
 269
 270
 271             This variant will send the string \c data to the peer \c addr.
 272
 273             \param[in] addr Address of peer to send data to
 274             \param[in] data data to send
 275             \returns Number of bytes written
 276          */
 277         unsigned     writeto      (AddressParam addr, std::string const & data);
 278         unsigned     writeto      (AddressParam addr, char const * buffer, unsigned size);
 279                                         ///< Write data from memory buffer to unconnected socket
 280                                         /**< \param[in] addr Address o fpeer to send data to
 281                                            \param[in] buffer address of buffer to write
 282                                            \param[in] size amount of data to write
 283                                            \returns Number of bytes written
 284                                            \see \ref writeto() */
 285
 286         ///////////////////////////////////////////////////////////////////////////
 287         ///\name Addressing
 288         ///@{
 289
 290         /** \brief Connect to remote peer
 291
 292             This member will establish a connection for addressable connection-oriented protocols
 293             (that is, the CommunicationPolicy is ConnectedCommunicationPolicy and the
 294             AddressingPolicy is not NoAddressingPolicy).
 295
 296             \param[in] addr Address to connect to
 297
 298             \throws senf::SystemException
 299          */
 300         void         connect      (AddressParam addr);
 301
 302         /** \brief Set local address
 303
 304             For addressable protocols (AddressingPolicy is not NoAddressingPolicy), bind() will set
 305             the local address of the socket.
 306
 307             \parm[in] addr Local socket address to asign
 308
 309             \throws senf::SystemException
 310          */
 311         void         bind         (AddressParam addr);
 312
 313         /** \brief Query remote address
 314
 315             This member will return the address of the communication partner in addressable
 316             connection-oriented protocols (that is, the CommunicationPolicy is
 317             ConnectedCommunicationPolicy and the AddressingPolicy is not NoAddressingPolicy).
 318
 319             There are two Variants of this member, one will return the address by value, the other
 320             takes a reference argument to elide the copy operation.
 321
 322             \throws senf::SystemException
 323          */
 324         Address      peer         ();
 325         void         peer         (Address & addr);
 326                                         ///< Query remote address
 327                                         /**< \see \ref peer() */
 328
 329         /** \brief Query local address
 330
 331             This member will return the address of the local socket in addressable protocols
 332             (AddressingPolicy is not NoAddressingPolicy).
 333
 334             There are two Variants of this member, one will return the address by value, the other
 335             takes a reference argument to elide the copy operation.
 336
 337          */
 338         Address      local        ();
 339         void         local        (Address & addr);
 340                                         ///< Query local address
 341                                         /**< \see \ref local() */
 342
 343         ///@}
 344
 345         ///////////////////////////////////////////////////////////////////////////
 346         ///\name Buffering
 347         ///@{
 348
 349         unsigned     rcvbuf      ();    ///< Check size of receive buffer
 350                                         /**< \returns size of receive buffer in bytes */
 351         void         rcvbuf      (unsigned size);
 352                                         ///< Set size of receive buffer
 353                                         /**< \param[in] size size of receive buffer in bytes */
 354
 355         unsigned     sndbuf      ();    ///< Check size of send buffer
 356                                         /**< \returns size of send buffer in bytes */
 357         void         sndbuf      (unsigned size);
 358                                         ///< Set size of send buffer
 359                                         /**< \param[in] size size of send buffer in bytes */
 360
 361         ///@}
 362
 363         static ClientSocketHandle cast_static(FileHandle handle);
 364                                         /**< \internal */
 365         static ClientSocketHandle cast_dynamic(FileHandle handle);
 366                                         /**< \internal */
 367
 368         // we need to override both since SocketHandle is *not* polymorphic
 369         void state(SocketStateMap & map, unsigned lod=0);
 370         std::string dumpState(unsigned lod=0);
 371
 372     protected:
 373         ClientSocketHandle(FileHandle other, bool isChecked);
 374         explicit ClientSocketHandle(std::auto_ptr<SocketProtocol> protocol,
 375                                     int fd = -1);
 376
 377     private:
 378         unsigned available();
 379
 380         friend class senf::ServerSocketHandle<Policy>;
 381     };
 382
 383     /// @}
 384 }
 385
 386 ///////////////////////////////hh.e////////////////////////////////////////
 387 //#include "ClientSocketHandle.cci"
 388 #include "ClientSocketHandle.ct"
 389 #include "ClientSocketHandle.cti"
 390 #endif
 391
 392 \f
 393 // Local Variables:
 394 // mode: c++
 395 // c-file-style: "senf"
 396 // fill-column: 100
 397 // End: