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