Socket/SocketProtocol.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
  25     \idea We should optimize the protocol handling. Allocating a protocol instance for every socket
  26         body seems quite wasteful. We could derive SocketPolicy from SocketBody (probably privately,
  27         since private inheritance models more of 'has a' than 'is a'). This would allow to reduce
  28         the number of heap-allocations per socket to one which is good.
  29  */
  30
  31 // The private inheritance idea should indeed work very well: We just need to chnage the
  32 // implementations of body() and protocol() and that of the ProtocolClient/ServerSocketHandle
  33 // constructors and the SocketBody constructor. The body and the protocol would still be visible
  34 // like several instances because of the private inheritance but we would save the backwards
  35 // pointer.
  36
  37 /** \defgroup protocol_group The Protocol Classes
  38
  39     \image html Protocols.png
  40
  41     The socket handle classes and templates only implement the most important socket API methods
  42     using the policy framework. To access the complete API, the protocol interface is
  43     provided. Access to the protocol interface is only possible via senf::ProtocolClientSocketHandle
  44     and senf::ProtocolServerSocketHandle which have the necessary \c protocol() member. This member
  45     returns a reference to the protocol class instance which contains members covering all the API
  46     functions (mostly setsockopt/getsockopt related calls but there may be more, this is completely
  47     up to the implementor of the protocol class) not found in the SocketHandle interface. The
  48     protocol interface is specific to the protocol. It's implementation is quite free. The standard
  49     protocols are implemented using a simple multiple-inheritance hierarchy as shown above.
  50
  51     Since the protocol class is protocol specific (how intelligent ...), the protocol class also
  52     defines the complete socket policy to be used with it's protocol. Complete meaning, that every
  53     policy axis must be assigned it's the most specific (that is derived) policy class to be used
  54     with the protocol.
  55
  56     \see
  57         \ref handle_group \n
  58         \ref policy_group
  59  */
  60
  61 /** \defgroup concrete_protocol_group Protocol Implementations (Concrete Protocol Classes)
  62     \ingroup protocol_group
  63
  64     Theese protocol classes define concrete and complete protocol implementations. They inherit from
  65     ConcreteSocketProtocol and are used with the ProtocolClientSocketHandle and
  66     ProtocolServerSocketHandle templates to instantiate socket handles. Appropriate typedefs are
  67     always provided.
  68
  69     Every protocol defines both the protocol and the policy interface provided by that protocol. See
  70     the documentation of the protocol classes listed below for more information on the supported
  71     protocols. Every protocol class documents it's policy interface. Use the 'list all members' link
  72     of the protocol class to find the complete policy interface.
  73  */
  74
  75 #ifndef HH_SocketProtocol_
  76 #define HH_SocketProtocol_ 1
  77
  78 // Custom includes
  79 #include <boost/utility.hpp>
  80 /** \fixme this is not nice. The includes and predefs should be restructured */
  81 #include "SocketHandle.ih"
  82
  83 //#include "SocketProtocol.mpp"
  84 ///////////////////////////////hh.p////////////////////////////////////////
  85
  86 namespace senf {
  87
  88     /// \addtogroup protocol_group
  89     /// @{
  90
  91     class SocketPolicyBase;
  92
  93     /** \brief Socket protocol base class
  94
  95         This is the base class of all socket protocol classes. Every protocol class must directly or
  96         indirectly inherit from SocketProtocol
  97
  98         \attention SocketProtocol must \e always be inherited using public \e virtual inheritance.
  99      */
 100     class SocketProtocol : boost::noncopyable
 101     {
 102     public:
 103         ///////////////////////////////////////////////////////////////////////////
 104         // Types
 105
 106         ///////////////////////////////////////////////////////////////////////////
 107         ///\name Structors and default members
 108         ///@{
 109
 110         SocketProtocol();
 111         virtual ~SocketProtocol() = 0;
 112
 113         // default default constructor
 114         // no copy
 115         // no conversion constructors
 116
 117         ///@}
 118         ///////////////////////////////////////////////////////////////////////////
 119
 120         SocketBody & body() const;      ///< Access the socket body
 121                                         /**< \todo we don't need body(), we should better provide a
 122                                              handle() member which will return a simple FIleHandle
 123                                              object (we cannot return some other derived class since
 124                                              we don't know the Protocol or Policy at this point) */
 125         virtual SocketPolicyBase const & policy() const = 0;
 126                                         ///< Access the policy instance
 127
 128         ///////////////////////////////////////////////////////////////////////////
 129         // Virtual interface
 130
 131         virtual std::auto_ptr<SocketProtocol> clone() const = 0;
 132                                         ///< Polymorphically return a copy of this protocol class
 133                                         /**< This member will create a new copy of the protocol
 134                                              class on the heap.
 135                                              \attention This member must be implemented in every \e
 136                                                  leaf protocol class to return a new instance of the
 137                                                  appropriate type. */
 138         virtual unsigned available() const = 0;
 139                                         ///< Return number of bytes available for reading without
 140                                         ///< blocking
 141                                         /**< This member will check in a (very, sigh) protocol
 142                                              deqpendent way, how many bytes are guarateed to be
 143                                              readable from the socket without blocking even if the
 144                                              socket is blocking. */
 145
 146         virtual bool eof() const = 0;   ///< Check for end-of-file condition
 147                                         /**< This is another check which (like available()) is
 148                                              extremely protocol dependent. This member will return
 149                                              \c true only, if at end-of-file. If the protocol does
 150                                              not support the notion of EOF, this member should
 151                                              always return \c false. */
 152         virtual void state(SocketStateMap & map, unsigned lod) const;
 153                                         ///< Return socket state information
 154                                         /**< This member is called to add state information to the
 155                                              status \a map. The protocol map should provide as
 156                                              detailed information as possible. The amount of
 157                                              information to be added to the map is selected by the
 158                                              \a lod value with a default value of 0. The
 159                                              interpretation of the \a lod value is completely
 160                                              implementation defined.
 161
 162                                              Every class derived from SocketProtocol should
 163                                              reimplement state(). The reimplemented method should
 164                                              call (all) baseclass-implementations of this
 165                                              member.
 166
 167                                              The \a map Argument is a map which associates
 168                                              std:string keys with std:string-like values. The map
 169                                              keys are interpreted as hierarchical strings with '.'
 170                                              as a separator (like hostnames or struct or class
 171                                              members). They are automatically sorted correctly.
 172
 173                                              The values are std:string with one additional feature:
 174                                              they allow assignment or conversion from *any* type as
 175                                              long as that type is streamable. This simplifies
 176                                              assigning non-string values to the map:
 177
 178                                              \code
 179                                                map["socket.protocol.ip.address"] = peer();
 180                                                map["socket.protocol.tcp.backlog"] = backlog();
 181                                              \endcode
 182
 183                                              This will work even if peer() returns an ip-address
 184                                              object or backlog() returns an integer. The values are
 185                                              automatically converted to their string representation.
 186
 187                                              The operator "+=" also has been reimplemented to
 188                                              simplify adding multiple values to a single entry: It
 189                                              will automatically add a ", " separator if the string
 190                                              is non-empty. */
 191
 192     protected:
 193
 194     private:
 195         // backpointer to owning SocketBody instance
 196         SocketBody * body_;
 197         friend class SocketBody;
 198    };
 199
 200
 201     /** \brief Concrete socket protocol implementation base class
 202
 203         ConcreteSocketProtocol is the base class of a concrete socket protocol implementation. The
 204         final protocol class must inherit from ConcreteSocketProtocol. The template argument \a
 205         SocketPolicy must be set to the complete socket policy of the protocol.
 206
 207         A protocol implementation may define the protocol interface directly. It can also
 208         (additnally) make use of multiple inheritance to combine a set of protocol facets into a
 209         specific protocol implementation (i.e. TCPv4SocketProtocol inherits from
 210         ConcreteSocketProtocol and from the protocol facets IPv4Protocol, TCPProtocol,
 211         BSDSocketProtocol and AddressableBSDSocketProtocol). The protocol facets are not concrete
 212         protocols themselves, they are combined to build concrete protocols. This structure will
 213         remove a lot of code duplication. It is important to ensure, that the protocol facets do not
 214         overlap, since otherwise there will be problems resolving overlapping members.
 215      */
 216     template <class SocketPolicy>
 217     class ConcreteSocketProtocol
 218         : public virtual SocketProtocol
 219     {
 220     public:
 221         ///////////////////////////////////////////////////////////////////////////
 222         // Types
 223
 224         typedef SocketPolicy Policy;    ///< The protocols policy
 225
 226         ///////////////////////////////////////////////////////////////////////////
 227         ///\name Structors and default members
 228         ///@{
 229
 230         ~ConcreteSocketProtocol() = 0;
 231
 232         // no default constructor
 233         // no copy
 234         // no conversion constructors
 235
 236         ///@}
 237         ///////////////////////////////////////////////////////////////////////////
 238
 239         Policy const & policy() const;
 240
 241     protected:
 242
 243     private:
 244         Policy policy_;
 245
 246     };
 247
 248     /// @}
 249 }
 250
 251 ///////////////////////////////hh.e////////////////////////////////////////
 252 #include "SocketProtocol.cci"
 253 //#include "SocketProtocol.ct"
 254 #include "SocketProtocol.cti"
 255 #endif
 256
 257 \f
 258 // Local Variables:
 259 // mode: c++
 260 // c-file-style: "senf"
 261 // fill-column: 100
 262 // End: