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