Socket/ServerSocketHandle.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 ServerSocketHandle public header
  25  */
  26
  27 #ifndef HH_ServerSocketHandle_
  28 #define HH_ServerSocketHandle_ 1
  29
  30 // Custom includes
  31 #include <boost/static_assert.hpp>
  32 #include <boost/call_traits.hpp>
  33 #include "SocketHandle.hh"
  34 #include "CommunicationPolicy.hh"
  35 #include "AddressingPolicy.hh"
  36
  37 //#include "ServerSocketHandle.mpp"
  38 ///////////////////////////////hh.p////////////////////////////////////////
  39
  40 namespace senf {
  41
  42     /// \addtogroup handle_group
  43     /// @{
  44
  45     template <class Policy> class ClientSocketHandle;
  46
  47     /** \brief Generic SocketHandle with server interface
  48
  49         This class provides the server side policy interface of the socket abstraction.
  50         ServerSocketHandle defines the complete policy interface. It does not implement any
  51         functionality itself however. All calls are forwarded to the following policy classes:
  52
  53         <table class="senf">
  54         <tr><td>senf::ServerSocketHandle::bind</td>       <td>AddressingPolicy::bind (\ref senf::AddressingPolicyBase)</td></tr>
  55         <tr><td>senf::ServerSocketHandle::listen</td>     <td>CommunicationPolicy::listen (\ref senf::CommunicationPolicyBase)</td></tr>
  56         <tr><td>senf::ServerSocketHandle::local</td>      <td>AddressingPolicy::local (\ref senf::AddressingPolicyBase)</td></tr>
  57         <tr><td>senf::ServerSocketHandle::accept</td>     <td>CommunicationPolicy::accept (\ref senf::CommunicationPolicyBase)</td></tr>
  58         <tr><td>senf::ServerSocketHandle::acceptfrom</td> <td>CommunicationPolicy::accept (\ref senf::CommunicationPolicyBase)</td></tr>
  59         </table>
  60
  61         A ServerSocketHandle is only meaningful for connection oriented addressable protocols
  62         (CommunicationPolicy is ConnectedCommunicationPolicy and AddressingPolicy is not
  63         NoAddressingPolicy).
  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     template <class Policy>
  76     class ServerSocketHandle
  77         : public SocketHandle<Policy>
  78     {
  79     public:
  80         ///////////////////////////////////////////////////////////////////////////
  81         // Types
  82
  83         /// Address type from the addressing policy
  84         typedef typename Policy::AddressingPolicy::Address Address;
  85         /// 'Best' type for passing address as parameter
  86         /** Depending on the type of \c Address, this will be either <tt>Address</tt> or <tt>Address
  87             const &</tt>. See <a href="http://www.boost.org/libs/utility/call_traits.htm"
  88             class="ext">call_traits documentation in the Boost.Utility library\endlink.</a>
  89          */
  90         typedef typename boost::call_traits<Address>::param_type AddressParam;
  91         /// Corresponding client socket handle with the same policy
  92         typedef ClientSocketHandle<Policy> ClientSocketHandle;
  93
  94         ///////////////////////////////////////////////////////////////////////////
  95         ///\name Structors and default members
  96         ///@{
  97
  98         // no default constructor
  99         // default copy constructor
 100         // default copy assignment
 101         // default destructor
 102
 103         // conversion constructors
 104         template <class OtherPolicy>
 105         ServerSocketHandle(ServerSocketHandle<OtherPolicy> other,
 106                            typename SocketHandle<Policy>::template IsCompatible<OtherPolicy>::type * = 0);
 107
 108         template <class OtherPolicy>
 109         typename SocketHandle<Policy>::template IsCompatible<OtherPolicy>::type const &
 110         operator=(ServerSocketHandle<OtherPolicy> other);
 111
 112         ///@}
 113         ///////////////////////////////////////////////////////////////////////////
 114
 115         ///////////////////////////////////////////////////////////////////////////
 116         ///\name Server socket interface
 117         ///@{
 118
 119         /** \brief Set local address
 120
 121             For addressable protocols (AddressingPolicy is not NoAddressingPolicy), bind() will set
 122             the local address of the socket.
 123
 124             \param[in] addr Local socket address to asign
 125
 126             \throws senf::SystemException
 127          */
 128         void         bind         (AddressParam addr);
 129
 130         /** \brief Allow clients to connect to this server socket
 131
 132             \todo This is very protocol specific, I don't want it in the policy
 133                 interface. Especially the backlog argument seems quite protocol specific to
 134                 me. However, we cannot listen() before we bind() so listen() cannot reside in the
 135                 constructor. We need to find a good solution here.
 136
 137             \throws senf::SystemException
 138          */
 139         // Possible solution: Make listen() an abstract method of the protocol interface, make the
 140         // backlog parameter into a member living in the body or protocol class and set it using
 141         // some accessor. Hmm ... this all seems somehow futile ...
 142         void         listen       (unsigned backlog=0);
 143
 144         /** \brief Query local address
 145
 146             This member will return the address of the local socket in addressable protocols
 147             (AddressingPolicy is not NoAddressingPolicy).
 148
 149             There are two Variants of this member, one will return the address by value, the other
 150             takes a reference argument to elide the copy operation.
 151
 152             \throws senf::SystemException
 153          */
 154         Address      local        ();
 155         void         local        (Address & addr);
 156                                         ///< Query local address
 157                                         /**< \see \ref local() */
 158
 159         /** \brief Accept new connection
 160
 161             If the handle is non-blocking, accept will NOT block. If no connection
 162             is available to be returned, accept will return a ClientSocketHandle
 163             which is not valid()
 164
 165             \throws senf::SystemException
 166
 167             This variant ...
 168
 169             \returns handle of new client connection
 170          */
 171         ClientSocketHandle
 172                      accept       ();
 173         std::pair<ClientSocketHandle, Address>
 174                      acceptfrom   ();   ///< Accept new connection
 175                                         /**< This variant will additionally return the remote
 176                                            address of the client
 177                                            \returns \c std::pair with client handle and client
 178                                            address.
 179                                            \see \ref accept() */
 180         ClientSocketHandle
 181                      acceptfrom   (Address & addr);
 182                                         ///< Accept new connection
 183                                         /**< This variant will additionally return the remote
 184                                            address of the client
 185                                            \param[out] client address
 186                                            \returns handle of new client connection
 187                                            \see \ref accept() */
 188
 189         ///@}
 190
 191         static ServerSocketHandle cast_static(FileHandle handle);
 192         static ServerSocketHandle cast_dynamic(FileHandle handle);
 193
 194         // we need to override both since SocketHandle is *not* polymorphic
 195         void state(SocketStateMap & map, unsigned lod=0);
 196         std::string dumpState(unsigned lod=0);
 197
 198     protected:
 199         ServerSocketHandle(FileHandle other, bool isChecked);
 200         explicit ServerSocketHandle(std::auto_ptr<SocketProtocol> protocol);
 201
 202     private:
 203
 204     };
 205
 206     /// @}
 207 }
 208
 209 ///////////////////////////////hh.e////////////////////////////////////////
 210 //#include "ServerSocketHandle.cci"
 211 //#include "ServerSocketHandle.ct"
 212 #include "ServerSocketHandle.cti"
 213 #endif
 214
 215 \f
 216 // Local Variables:
 217 // mode: c++
 218 // c-file-style: "senf"
 219 // fill-column: 100
 220 // End: