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
  88             href="http://www.boost.org/libs/utility/call_traits.htm">call_traits documentation in
  89             the Boost.Utility library\endlink.</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         // no default constructor
 100         // default copy constructor
 101         // default copy assignment
 102         // default destructor
 103
 104         // conversion constructors
 105         template <class OtherPolicy>
 106         ServerSocketHandle(ServerSocketHandle<OtherPolicy> other,
 107                            typename SocketHandle<Policy>::template IsCompatible<OtherPolicy>::type * = 0);
 108
 109         template <class OtherPolicy>
 110         typename SocketHandle<Policy>::template IsCompatible<OtherPolicy>::type const &
 111         operator=(ServerSocketHandle<OtherPolicy> other);
 112
 113         ///@}
 114         ///////////////////////////////////////////////////////////////////////////
 115
 116         ///////////////////////////////////////////////////////////////////////////
 117         ///\name Server socket interface
 118         ///@{
 119
 120         /** \brief Set local address
 121
 122             For addressable protocols (AddressingPolicy is not NoAddressingPolicy), bind() will set
 123             the local address of the socket.
 124
 125             \param[in] addr Local socket address to asign
 126
 127             \throws senf::SystemException
 128          */
 129         void         bind         (AddressParam addr);
 130
 131         /** \brief Allow clients to connect to this server socket
 132
 133             \todo This is very protocol specific, I don't want it in the policy
 134                 interface. Especially the backlog argument seems quite protocol specific to
 135                 me. However, we cannot listen() before we bind() so listen() cannot reside in the
 136                 constructor. We need to find a good solution here.
 137
 138             \throws senf::SystemException
 139          */
 140         // Possible solution: Make listen() an abstract method of the protocol interface, make the
 141         // backlog parameter into a member living in the body or protocol class and set it using
 142         // some accessor. Hmm ... this all seems somehow futile ...
 143         void         listen       (unsigned backlog=0);
 144
 145         /** \brief Query local address
 146
 147             This member will return the address of the local socket in addressable protocols
 148             (AddressingPolicy is not NoAddressingPolicy).
 149
 150             There are two Variants of this member, one will return the address by value, the other
 151             takes a reference argument to elide the copy operation.
 152
 153             \throws senf::SystemException
 154          */
 155         Address      local        ();
 156         void         local        (Address & addr);
 157                                         ///< Query local address
 158                                         /**< \see \ref local() */
 159
 160         /** \brief Accept new connection
 161
 162             If the handle is non-blocking, accept will NOT block. If no connection is available to
 163             be returned, accept will return a ClientSocketHandle 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 // fill-column: 100
 219 // c-file-style: "senf"
 220 // indent-tabs-mode: nil
 221 // ispell-local-dictionary: "american"
 222 // End: