Socket/SocketHandle.hh

   1 // $Id:SocketHandle.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 SocketHandle public header
  25  */
  26
  27 #ifndef HH_SocketHandle_
  28 #define HH_SocketHandle_ 1
  29
  30 // Custom includes
  31 #include <memory> // std::auto_ptr
  32 #include "FileHandle.hh"
  33 #include "SocketPolicy.hh"
  34
  35 //#include "SocketHandle.mpp"
  36 #include "SocketHandle.ih"
  37 ///////////////////////////////hh.p////////////////////////////////////////
  38 #include "SocketHandle.ih"
  39
  40 namespace senf {
  41
  42     /// \addtogroup handle_group
  43     /// @{
  44
  45     /** \brief basic SocketHandle supporting protocol and policy abstraction
  46
  47         The %senf::SocketHandle class introduces the two abstraction layers of the socket
  48         library. senf::SocketHandle does \e not provide socket functions it only provides the
  49         infrastructure necessary to support both, the protocol and the policy interface.
  50
  51         %SocketHandle takes the socket policy as a template argument. %SocketHandle also
  52         introduces the protocol class. However, the class has no public constructors (see the
  53         derived classes senf::ProtocolClientSocketHandle and senf::ProtocolServerSocketHandle).
  54
  55         The most important functionality provided by %SocketHandle is the conversion
  56         constructor. This allows to implicitly convert between compatible socket handle types as
  57         specified by the socket policy. The conversion constructor is defined in such a way, that
  58         only valid conversions are possible (see the implementation source for a more complete
  59         discussion).
  60
  61         \tparam SPolicy socket policy
  62
  63         \note This class is \e not meant to be used as a base-class outside the library
  64         implementation; The protected interface is for internal use only.
  65
  66         \todo Create a SocketHandleBase class and move some non-Policy dependent code there
  67      */
  68     template <class SPolicy>
  69     class SocketHandle
  70         : public FileHandle
  71     {
  72     public:
  73         ///////////////////////////////////////////////////////////////////////////
  74         // Types
  75
  76         typedef SPolicy Policy;
  77
  78         /** \brief Check policy compatibility
  79
  80             IsCompatible is a template meta-function which will check some other socket policy for
  81             conversion compatibility. This check is used in the senf::SocketPolicy implementation to
  82             restrict the conversion operator.
  83          */
  84         template <class OtherPolicy>
  85         struct IsCompatible
  86             : public boost::enable_if< SocketPolicyIsBaseOf<Policy,OtherPolicy>, SocketHandle >
  87         {};
  88
  89         ///////////////////////////////////////////////////////////////////////////
  90         ///\name Structors and default members
  91         ///@{
  92
  93         // default default constructor
  94         // default copy constructor
  95         // default copy assignment
  96         // default destructor
  97
  98         // here to implement
  99         SocketHandle();
 100
 101         // conversion constructors
 102
 103         template <class OtherPolicy>
 104         SocketHandle(SocketHandle<OtherPolicy> other,
 105                      typename IsCompatible<OtherPolicy>::type * = 0);
 106                                         ///< Convert from other socket handle checking policy
 107                                         ///< compatibility
 108
 109         ///@}
 110         ///////////////////////////////////////////////////////////////////////////
 111
 112         template <class OtherPolicy>
 113         typename IsCompatible<OtherPolicy>::type const & operator=(SocketHandle<OtherPolicy> other);
 114                                         ///< Assign from other socket handle checking policy
 115                                         ///< compatibility
 116
 117         void state(SocketStateMap & map, unsigned lod=0);
 118                                         ///< Inquire state information of socket handle
 119                                         /**< The map argument (a string to string mapping) will be
 120                                              filled with information covering the current state of
 121                                              the socket. The information provided depends on the
 122                                              socket protocol. The amount of information returned can
 123                                              be controlled using the \p lod value.
 124
 125                                              See senf::SocketProtocol::state() for more information,
 126                                              how the Information is generated.
 127
 128                                              \param map string to string mapping to be filled with
 129                                                  state information
 130                                              \param lod level of %detail requested. The
 131                                                  interpretation of this value is protocol specific
 132
 133                                              \implementation This member will be re-implemented in
 134                                                  every derived class. This is very important since
 135                                                  state() is \e not a virtual function (which we
 136                                                  don't want since we don't want to add a vtable
 137                                                  pointer to every handle instance). */
 138         std::string dumpState(unsigned lod=0);
 139                                         ///< Format complete state information as string
 140                                         /**< Formats the complete state map value and returns it as
 141                                              a single multi-line string.
 142
 143                                              \param lod level of %detail requested. The
 144                                                 interpretation of this value is protocol specific
 145
 146                                              \implementation This member will be re-implemented in
 147                                                  every derived class. See the state()
 148                                                  documentation. */
 149
 150     protected:
 151         explicit SocketHandle(std::auto_ptr<SocketBody> body);
 152                                         ///< Initialize SocketHandle providing the protocol
 153                                         /**< \param protocol Protocol class of the protocol
 154                                                  implemented by this socket handle
 155                                              \param isServer \c true, if this SobcketHandle instance
 156                                                  implements a server handle, \c false otherwise */
 157         SocketHandle(FileHandle other, bool isChecked);
 158                                         ///< Initialize SocketHandle from arbitrary checked
 159                                         ///< FileHandle
 160                                         /**< This constructor is used to support up- and downcasting
 161                                              of SocketHandle instances.
 162
 163                                              \warning It is absolutely necessary to ensure, that the
 164                                                  FileHandle passed in is \e really a SocketHandle
 165                                                  holding a SocketBody (and not a simple FileBody)
 166                                                  instance. Additionally. the SocketPolicy absolutely
 167                                                  must be compatible.
 168
 169                                              \param other FileHandle to assign
 170                                              \param isChecked has to be \c true
 171
 172                                              \todo Answer, why the heck I need the \c isChecked
 173                                                  parameter ?? */
 174
 175         SocketBody & body();            ///< Access socket body
 176                                         /**< This member replaces the corresponding FileHandle
 177                                              member and returns an appropriately cast body
 178                                              reference */
 179         SocketBody const & body() const; ///< Access socket body in const context
 180                                         /**< This member replaces the corresponding FileHandle
 181                                              member and returns an appropriately cast body
 182                                              reference */
 183         SocketProtocol const & protocol() const;
 184                                         ///< Access protocol class
 185
 186         void assign(FileHandle other);  /**< \internal */
 187
 188     public:
 189         static SocketHandle cast_static(FileHandle handle);
 190                                         /**< \internal */
 191         static SocketHandle cast_dynamic(FileHandle handle);
 192                                         /**< \internal */
 193
 194     private:
 195
 196     };
 197
 198     /** \brief Write stream status dump to output stream
 199
 200         Write senf::SocketHandle::dumpState() to \c os
 201
 202         \related senf::SocketHandle
 203      */
 204     template <class SPolicy>
 205     std::ostream & operator<<(std::ostream & os, SocketHandle<SPolicy> handle);
 206
 207     /** \brief static socket (down-)cast
 208
 209         This function is like \c static_cast but for socket handles. It allows to downcast any
 210         FileHandle to any SocketHandle (and its derived types). static_socket_cast will \e not check
 211         the validity of the cast, it will assume, that the cast is valid.
 212
 213         The function will however check, that the cast is possible. Casting between (at compile
 214         time) known incompatible types (like casting a SocketHandle with a communication policy of
 215         ConnectedCommunicationPolicy to a SocketHandle with UnconnectedCommunicationPolicy will fail
 216         at compile time).
 217
 218         \warning
 219         If the type you cast to is not really a compatible socket handle type you will get undefined
 220         behavior, probably your program will crash (You will get an assertion in debug builds).
 221
 222         \related senf::SocketHandle
 223      */
 224     template <class Target, class Source>
 225     Target static_socket_cast(Source handle);
 226
 227     /** \brief dynamic socket (down-)cast
 228
 229         This function is like \c dynamic_cast but for socket handles. It is a runtime typechecked
 230         version of static_socket_cast.
 231
 232         \throws std::bad_cast You have tried to perform an invalid down- or crosscast.
 233
 234         \related senf::SocketHandle
 235      */
 236     template <class Target, class Source>
 237     Target dynamic_socket_cast(Source handle);
 238
 239     /** \brief dynamically check cast validity
 240
 241         This function will check, whether the given cast is valid. This is the same as checking, that
 242         dynamic_socket_cast does not throw.
 243
 244         This member is needed, since there is no 'null' SocketHandle (comparable to a null pointer)
 245         which could be returned by a non-throwing variant of dynamic_socket_cast.
 246
 247         \related senf::SocketHandle
 248      */
 249     template <class Target, class Source>
 250     bool check_socket_cast(Source handle);
 251
 252     /// @}
 253 }
 254
 255 ///////////////////////////////hh.e////////////////////////////////////////
 256 #include "SocketHandle.cci"
 257 #include "SocketHandle.ct"
 258 #include "SocketHandle.cti"
 259 #endif
 260
 261 \f
 262 // Local Variables:
 263 // mode: c++
 264 // fill-column: 100
 265 // c-file-style: "senf"
 266 // indent-tabs-mode: nil
 267 // ispell-local-dictionary: "american"
 268 // compile-command: "scons -u test"
 269 // comment-column: 40
 270 // End: