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 //
   6 // The contents of this file are subject to the Fraunhofer FOKUS Public License
   7 // Version 1.0 (the "License"); you may not use this file except in compliance
   8 // with the License. You may obtain a copy of the License at
   9 // http://senf.berlios.de/license.html
  10 //
  11 // The Fraunhofer FOKUS Public License Version 1.0 is based on,
  12 // but modifies the Mozilla Public License Version 1.1.
  13 // See the full license text for the amendments.
  14 //
  15 // Software distributed under the License is distributed on an "AS IS" basis,
  16 // WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  17 // for the specific language governing rights and limitations under the License.
  18 //
  19 // The Original Code is Fraunhofer FOKUS code.
  20 //
  21 // The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V.
  22 // (registered association), Hansastraße 27 c, 80686 Munich, Germany.
  23 // All Rights Reserved.
  24 //
  25 // Contributor(s):
  26 //   Stefan Bund <g0dil@berlios.de>
  27
  28 /** \file
  29     \brief ServerSocketHandle public header
  30  */
  31
  32 #ifndef HH_SENF_Socket_ServerSocketHandle_
  33 #define HH_SENF_Socket_ServerSocketHandle_ 1
  34
  35 // Custom includes
  36 #include <boost/call_traits.hpp>
  37 #include "SocketHandle.hh"
  38
  39 //#include "ServerSocketHandle.mpp"
  40 //-/////////////////////////////////////////////////////////////////////////////////////////////////
  41
  42 namespace senf {
  43
  44     /// \addtogroup handle_group
  45     //\{
  46
  47     template <class SPolicy> class ClientSocketHandle;
  48
  49     /** \brief Generic SocketHandle with server interface
  50
  51         This class provides the server side policy interface of the socket abstraction.
  52         ServerSocketHandle defines the complete policy interface. It does not implement any
  53         functionality itself however. All calls are forwarded to the following policy classes:
  54
  55         <table class="senf">
  56         <tr><td>senf::ServerSocketHandle::bind</td>       <td>AddressingPolicy::bind (\ref senf::AddressingPolicyBase)</td></tr>
  57         <tr><td>senf::ServerSocketHandle::listen</td>     <td>CommunicationPolicy::listen (\ref senf::CommunicationPolicyBase)</td></tr>
  58         <tr><td>senf::ServerSocketHandle::local</td>      <td>AddressingPolicy::local (\ref senf::AddressingPolicyBase)</td></tr>
  59         <tr><td>senf::ServerSocketHandle::accept</td>     <td>CommunicationPolicy::accept (\ref senf::CommunicationPolicyBase)</td></tr>
  60         <tr><td>senf::ServerSocketHandle::acceptfrom</td> <td>CommunicationPolicy::accept (\ref senf::CommunicationPolicyBase)</td></tr>
  61         </table>
  62
  63         A ServerSocketHandle is only meaningful for connection oriented addressable protocols
  64         (CommunicationPolicy is ConnectedCommunicationPolicy and AddressingPolicy is not
  65         NoAddressingPolicy).
  66
  67         It is important to note, that not all members are always accessible. Which are depends on
  68         the \c Policy template argument. If any of the policy axis is left unspecified the
  69         corresponding members will not be callable (you will get a compile time error). Even if
  70         every policy axis is defined, some members might (and will) not exist if they are
  71         meaningless for the protocol of the socket. This depends on the exact policy.
  72
  73         To find out, which members are available, you have to check the documentation of the policy
  74         classes. You can also find a summary of all members available in the leaf protocol class
  75         documentation.
  76       */
  77     template <class SPolicy>
  78     class ServerSocketHandle
  79         : public SocketHandle<SPolicy>
  80     {
  81     public:
  82         //-////////////////////////////////////////////////////////////////////////
  83         // Types
  84
  85         /// Address type from the addressing policy
  86         typedef typename SPolicy::AddressingPolicy::Address Address;
  87         /// 'Best' type for passing address as parameter
  88         /** Depending on the type of \c Address, this will be either <tt>Address</tt> or <tt>Address
  89             const &</tt>. See <a
  90             href="http://www.boost.org/doc/libs/release/libs/utility/call_traits.htm">call_traits documentation in
  91             the Boost.Utility library.</a>
  92          */
  93         typedef typename boost::call_traits<Address>::param_type AddressParam;
  94         /// Corresponding client socket handle with the same policy
  95         typedef ClientSocketHandle<SPolicy> ClientHandle;
  96
  97         //-////////////////////////////////////////////////////////////////////////
  98         ///\name Structors and default members
  99         //\{
 100
 101         // default default constructor
 102         // default copy constructor
 103         // default copy assignment
 104         // default destructor
 105
 106         // here to implement
 107         ServerSocketHandle();
 108
 109         // conversion constructors
 110         template <class OtherPolicy>
 111         ServerSocketHandle(ServerSocketHandle<OtherPolicy> other,
 112                            typename SocketHandle<SPolicy>::template IsCompatible<OtherPolicy>::type * = 0);
 113
 114         template <class OtherPolicy>
 115         typename SocketHandle<SPolicy>::template IsCompatible<OtherPolicy>::type const &
 116         operator=(ServerSocketHandle<OtherPolicy> other);
 117
 118         //\}
 119         //-////////////////////////////////////////////////////////////////////////
 120
 121         //-////////////////////////////////////////////////////////////////////////
 122         ///\name Server socket interface
 123         //\{
 124
 125         /** \brief Set local address
 126
 127             For addressable protocols (AddressingPolicy is not NoAddressingPolicy), bind() will set
 128             the local address of the socket.
 129
 130             \param[in] addr Local socket address to assign
 131
 132             \throws senf::SystemException
 133          */
 134         void         bind         (AddressParam addr);
 135
 136         /** \brief Allow clients to connect to this server socket
 137
 138             \todo This is very protocol specific, I don't want it in the policy
 139                 interface. Especially the backlog argument seems quite protocol specific to
 140                 me. However, we cannot listen() before we bind() so listen() cannot reside in the
 141                 constructor. We need to find a good solution here.
 142
 143             \throws senf::SystemException
 144          */
 145         // Possible solution: Make listen() an abstract method of the protocol interface, make the
 146         // backlog parameter into a member living in the body or protocol class and set it using
 147         // some accessor. Hmm ... this all seems somehow futile ...
 148         void         listen       (unsigned backlog=0);
 149
 150         /** \brief Query local address
 151
 152             This member will return the address of the local socket in addressable protocols
 153             (AddressingPolicy is not NoAddressingPolicy).
 154
 155             There are two Variants of this member, one will return the address by value, the other
 156             takes a reference argument to elide the copy operation.
 157
 158             \throws senf::SystemException
 159          */
 160         Address      local        ();
 161         void         local        (Address & addr);
 162                                         ///< Query local address
 163                                         /**< \see \ref local() */
 164
 165         /** \brief Accept new connection
 166
 167             If the handle is non-blocking, accept will NOT block. If no connection is available to
 168             be returned, accept will return a ClientSocketHandle which is not valid()
 169
 170             \throws senf::SystemException
 171
 172             This variant ...
 173
 174             \returns handle of new client connection
 175          */
 176         ClientHandle accept       ();
 177         std::pair<ClientHandle, Address>
 178                      acceptfrom   ();   ///< Accept new connection
 179                                         /**< This variant will additionally return the remote
 180                                            address of the client
 181                                            \returns \c std::pair with client handle and client
 182                                            address.
 183                                            \see \ref accept() */
 184         ClientHandle 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<SocketBody> body);
 204
 205     private:
 206
 207     };
 208
 209     //\}
 210 }
 211
 212 //-/////////////////////////////////////////////////////////////////////////////////////////////////
 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: