senf/Socket/ServerSocketHandle.hh

   1 // $Id:ServerSocketHandle.hh 218 2007-03-20 14:39:32Z tho $
   2 //
   3 // Copyright (C) 2006
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Stefan Bund <g0dil@berlios.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_SENF_Socket_ServerSocketHandle_
  28 #define HH_SENF_Socket_ServerSocketHandle_ 1
  29
  30 // Custom includes
  31 #include <boost/call_traits.hpp>
  32 #include "SocketHandle.hh"
  33
  34 //#include "ServerSocketHandle.mpp"
  35 //-/////////////////////////////////////////////////////////////////////////////////////////////////
  36
  37 namespace senf {
  38
  39     /// \addtogroup handle_group
  40     //\{
  41
  42     template <class SPolicy> class ClientSocketHandle;
  43
  44     /** \brief Generic SocketHandle with server interface
  45
  46         This class provides the server side policy interface of the socket abstraction.
  47         ServerSocketHandle defines the complete policy interface. It does not implement any
  48         functionality itself however. All calls are forwarded to the following policy classes:
  49
  50         <table class="senf">
  51         <tr><td>senf::ServerSocketHandle::bind</td>       <td>AddressingPolicy::bind (\ref senf::AddressingPolicyBase)</td></tr>
  52         <tr><td>senf::ServerSocketHandle::listen</td>     <td>CommunicationPolicy::listen (\ref senf::CommunicationPolicyBase)</td></tr>
  53         <tr><td>senf::ServerSocketHandle::local</td>      <td>AddressingPolicy::local (\ref senf::AddressingPolicyBase)</td></tr>
  54         <tr><td>senf::ServerSocketHandle::accept</td>     <td>CommunicationPolicy::accept (\ref senf::CommunicationPolicyBase)</td></tr>
  55         <tr><td>senf::ServerSocketHandle::acceptfrom</td> <td>CommunicationPolicy::accept (\ref senf::CommunicationPolicyBase)</td></tr>
  56         </table>
  57
  58         A ServerSocketHandle is only meaningful for connection oriented addressable protocols
  59         (CommunicationPolicy is ConnectedCommunicationPolicy and AddressingPolicy is not
  60         NoAddressingPolicy).
  61
  62         It is important to note, that not all members are always accessible. Which are depends on
  63         the \c Policy template argument. If any of the policy axis is left unspecified the
  64         corresponding members will not be callable (you will get a compile time error). Even if
  65         every policy axis is defined, some members might (and will) not exist if they are
  66         meaningless for the protocol of the socket. This depends on the exact policy.
  67
  68         To find out, which members are available, you have to check the documentation of the policy
  69         classes. You can also find a summary of all members available in the leaf protocol class
  70         documentation.
  71       */
  72     template <class SPolicy>
  73     class ServerSocketHandle
  74         : public SocketHandle<SPolicy>
  75     {
  76     public:
  77         //-////////////////////////////////////////////////////////////////////////
  78         // Types
  79
  80         /// Address type from the addressing policy
  81         typedef typename SPolicy::AddressingPolicy::Address Address;
  82         /// 'Best' type for passing address as parameter
  83         /** Depending on the type of \c Address, this will be either <tt>Address</tt> or <tt>Address
  84             const &</tt>. See <a
  85             href="http://www.boost.org/doc/libs/release/libs/utility/call_traits.htm">call_traits documentation in
  86             the Boost.Utility library.</a>
  87          */
  88         typedef typename boost::call_traits<Address>::param_type AddressParam;
  89         /// Corresponding client socket handle with the same policy
  90         typedef ClientSocketHandle<SPolicy> ClientHandle;
  91
  92         //-////////////////////////////////////////////////////////////////////////
  93         ///\name Structors and default members
  94         //\{
  95
  96         // default default constructor
  97         // default copy constructor
  98         // default copy assignment
  99         // default destructor
 100
 101         // here to implement
 102         ServerSocketHandle();
 103
 104         // conversion constructors
 105         template <class OtherPolicy>
 106         ServerSocketHandle(ServerSocketHandle<OtherPolicy> other,
 107                            typename SocketHandle<SPolicy>::template IsCompatible<OtherPolicy>::type * = 0);
 108
 109         template <class OtherPolicy>
 110         typename SocketHandle<SPolicy>::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 assign
 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         ClientHandle accept       ();
 172         std::pair<ClientHandle, Address>
 173                      acceptfrom   ();   ///< Accept new connection
 174                                         /**< This variant will additionally return the remote
 175                                            address of the client
 176                                            \returns \c std::pair with client handle and client
 177                                            address.
 178                                            \see \ref accept() */
 179         ClientHandle acceptfrom   (Address & addr);
 180                                         ///< Accept new connection
 181                                         /**< This variant will additionally return the remote
 182                                            address of the client
 183                                            \param[out] addr address
 184                                            \returns handle of new client connection
 185                                            \see \ref accept() */
 186
 187         //\}
 188
 189         static ServerSocketHandle cast_static(FileHandle handle);
 190         static ServerSocketHandle cast_dynamic(FileHandle handle);
 191
 192         // we need to override both since SocketHandle is *not* polymorphic
 193         void state(SocketStateMap & map, unsigned lod=0);
 194         std::string dumpState(unsigned lod=0);
 195
 196     protected:
 197         ServerSocketHandle(FileHandle other, bool isChecked);
 198         explicit ServerSocketHandle(std::auto_ptr<SocketBody> body);
 199
 200     private:
 201
 202     };
 203
 204     //\}
 205 }
 206
 207 //-/////////////////////////////////////////////////////////////////////////////////////////////////
 208 //#include "ServerSocketHandle.cci"
 209 //#include "ServerSocketHandle.ct"
 210 #include "ServerSocketHandle.cti"
 211 #endif
 212
 213 \f
 214 // Local Variables:
 215 // mode: c++
 216 // fill-column: 100
 217 // c-file-style: "senf"
 218 // indent-tabs-mode: nil
 219 // ispell-local-dictionary: "american"
 220 // compile-command: "scons -u test"
 221 // comment-column: 40
 222 // End: