Socket/ServerSocketHandle.hh

   1 // $Id:ServerSocketHandle.hh 218 2007-03-20 14:39:32Z tho $
   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
  88             href="http://www.boost.org/libs/utility/call_traits.htm">call_traits documentation in
  89             the Boost.Utility library.</a>
  90          */
  91         typedef typename boost::call_traits<Address>::param_type AddressParam;
  92         /// Corresponding client socket handle with the same policy
  93         typedef ClientSocketHandle<Policy> ClientSocketHandle;
  94
  95         ///////////////////////////////////////////////////////////////////////////
  96         ///\name Structors and default members
  97         ///@{
  98
  99         // default default constructor
 100         // default copy constructor
 101         // default copy assignment
 102         // default destructor
 103
 104         // here to implement
 105         ServerSocketHandle();
 106
 107         // conversion constructors
 108         template <class OtherPolicy>
 109         ServerSocketHandle(ServerSocketHandle<OtherPolicy> other,
 110                            typename SocketHandle<Policy>::template IsCompatible<OtherPolicy>::type * = 0);
 111
 112         template <class OtherPolicy>
 113         typename SocketHandle<Policy>::template IsCompatible<OtherPolicy>::type const &
 114         operator=(ServerSocketHandle<OtherPolicy> other);
 115
 116         ///@}
 117         ///////////////////////////////////////////////////////////////////////////
 118
 119         ///////////////////////////////////////////////////////////////////////////
 120         ///\name Server socket interface
 121         ///@{
 122
 123         /** \brief Set local address
 124
 125             For addressable protocols (AddressingPolicy is not NoAddressingPolicy), bind() will set
 126             the local address of the socket.
 127
 128             \param[in] addr Local socket address to assign
 129
 130             \throws senf::SystemException
 131          */
 132         void         bind         (AddressParam addr);
 133
 134         /** \brief Allow clients to connect to this server socket
 135
 136             \todo This is very protocol specific, I don't want it in the policy
 137                 interface. Especially the backlog argument seems quite protocol specific to
 138                 me. However, we cannot listen() before we bind() so listen() cannot reside in the
 139                 constructor. We need to find a good solution here.
 140
 141             \throws senf::SystemException
 142          */
 143         // Possible solution: Make listen() an abstract method of the protocol interface, make the
 144         // backlog parameter into a member living in the body or protocol class and set it using
 145         // some accessor. Hmm ... this all seems somehow futile ...
 146         void         listen       (unsigned backlog=0);
 147
 148         /** \brief Query local address
 149
 150             This member will return the address of the local socket in addressable protocols
 151             (AddressingPolicy is not NoAddressingPolicy).
 152
 153             There are two Variants of this member, one will return the address by value, the other
 154             takes a reference argument to elide the copy operation.
 155
 156             \throws senf::SystemException
 157          */
 158         Address      local        ();
 159         void         local        (Address & addr);
 160                                         ///< Query local address
 161                                         /**< \see \ref local() */
 162
 163         /** \brief Accept new connection
 164
 165             If the handle is non-blocking, accept will NOT block. If no connection is available to
 166             be returned, accept will return a ClientSocketHandle which is not valid()
 167
 168             \throws senf::SystemException
 169
 170             This variant ...
 171
 172             \returns handle of new client connection
 173          */
 174         ClientSocketHandle
 175                      accept       ();
 176         std::pair<ClientSocketHandle, Address>
 177                      acceptfrom   ();   ///< Accept new connection
 178                                         /**< This variant will additionally return the remote
 179                                            address of the client
 180                                            \returns \c std::pair with client handle and client
 181                                            address.
 182                                            \see \ref accept() */
 183         ClientSocketHandle
 184                      acceptfrom   (Address & addr);
 185                                         ///< Accept new connection
 186                                         /**< This variant will additionally return the remote
 187                                            address of the client
 188                                            \param[out] addr address
 189                                            \returns handle of new client connection
 190                                            \see \ref accept() */
 191
 192         ///@}
 193
 194         static ServerSocketHandle cast_static(FileHandle handle);
 195         static ServerSocketHandle cast_dynamic(FileHandle handle);
 196
 197         // we need to override both since SocketHandle is *not* polymorphic
 198         void state(SocketStateMap & map, unsigned lod=0);
 199         std::string dumpState(unsigned lod=0);
 200
 201     protected:
 202         ServerSocketHandle(FileHandle other, bool isChecked);
 203         explicit ServerSocketHandle(std::auto_ptr<SocketProtocol> protocol);
 204
 205     private:
 206
 207     };
 208
 209     /// @}
 210 }
 211
 212 ///////////////////////////////hh.e////////////////////////////////////////
 213 //#include "ServerSocketHandle.cci"
 214 //#include "ServerSocketHandle.ct"
 215 #include "ServerSocketHandle.cti"
 216 #endif
 217
 218 \f
 219 // Local Variables:
 220 // mode: c++
 221 // fill-column: 100
 222 // c-file-style: "senf"
 223 // indent-tabs-mode: nil
 224 // ispell-local-dictionary: "american"
 225 // compile-command: "scons -u test"
 226 // comment-column: 40
 227 // End: