PPI/SocketSink.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   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 SocketSink public header */
  25
  26 #ifndef HH_SocketSink_
  27 #define HH_SocketSink_ 1
  28
  29 // Custom includes
  30 #include "../Packets/Packets.hh"
  31 #include "../Socket/ClientSocketHandle.hh"
  32 #include "../Socket/SocketPolicy.hh"
  33 #include "../Socket/ReadWritePolicy.hh"
  34 #include "../Socket/FramingPolicy.hh"
  35 #include "../Socket/CommunicationPolicy.hh"
  36 #include "Module.hh"
  37 #include "Connectors.hh"
  38
  39 //#include "SocketSink.mpp"
  40 ///////////////////////////////hh.p////////////////////////////////////////
  41
  42 namespace senf {
  43 namespace ppi {
  44
  45     /** \brief Write helper for module::ActiveSocketSink / module::PassiveSocketSink
  46
  47         This write helper will write the packets completely as datagrams to the given socket.
  48      */
  49     class PacketSink
  50     {
  51     public:
  52         typedef senf::ClientSocketHandle<
  53             senf::MakeSocketPolicy< senf::WriteablePolicy,
  54                                     senf::DatagramFramingPolicy,
  55                                     senf::ConnectedCommunicationPolicy>::policy > Handle;
  56                                         ///< Handle type supported by this writer
  57
  58         void operator()(Handle handle, Packet packet);
  59                                         ///< Write \a packet to \a handle
  60                                         /**< Write the complete \a packet as a datagram to \a
  61                                              handle.
  62                                              \param[in] handle Handle to write data to
  63                                              \param[in] packet Packet to write */
  64     };
  65
  66 }}
  67
  68 namespace senf {
  69 namespace ppi {
  70 namespace module {
  71
  72     /** \brief Output module writing data to arbitrary FileHandle
  73
  74         This output module will write data to a FileHandle object using a given \a Sink. This
  75         output module is active. This requires the file handle to be able to signal its readiness to
  76         accept more data via the Scheduler.
  77
  78         The default \a Sink is senf::ppi::PacketSink which will write out the complete packet to
  79         the file handle.
  80
  81         A \a Sink must fulfill the following interface:
  82         \code
  83           class SomeSink
  84           {
  85           public:
  86               typedef unspecified Handle;                          // type of handle requested
  87
  88               SomeSink();                                          // EITHER default constructible OR
  89               SomeSink(SomeSink const & other);                    // copy constructible
  90
  91               void operator()(Handle handle, Packet packet);       // insertion function
  92           };
  93         \endcode
  94         Whenever a packet is received for sending, the \a Sink's \c operator() is called.
  95
  96         \ingroup io_modules
  97      */
  98     template <class Sink=PacketSink>
  99     class ActiveSocketSink : public Module
 100     {
 101         SENF_PPI_MODULE(ActiveSocketSink);
 102
 103     public:
 104         typedef typename Sink::Handle Handle; ///< Handle type requested by writer
 105
 106         connector::ActiveInput input; ///< Input connector from which data is received
 107
 108         ActiveSocketSink(Handle handle); ///< Create new writer for the given handle
 109                                         /**< Data will be written to \a handle using \a Sink.
 110                                              \pre Requires \a Sink to be default constructible
 111                                              \param[in] handle Handle to write data to */
 112         ActiveSocketSink(Handle handle, Sink const & sink);
 113                                         ///< Create new writer for the given handle
 114                                         /**< Data will be written to \a handle using \a Sink.
 115                                              \pre Requires \a Sink to be copy constructible
 116                                              \param[in] handle Handle to write data to
 117                                              \param[in] sink Sink helper writing packet date to the
 118                                                  socket */
 119
 120         Sink & sink();                  ///< Access the sink helper
 121
 122     private:
 123         void write();
 124
 125         Handle handle_;
 126         IOEvent event_;
 127         Sink writer_;
 128     };
 129
 130     /** \brief Output module writing data to arbitrary FileHandle
 131
 132         This output module will write data to a FileHandle object using a given \a Sink. This
 133         output module is passive. This implies, that the output handle may not block. This also
 134         implies, that data will probably get lost if written to fast for the underlying transport
 135         mechanism. Either this is desired (like for a UDP socket) or some additional bandwidth
 136         shaping needs to be used.
 137
 138         The default \a Sink is senf::ppi::PacketSink which will write out the complete packet to
 139         the file handle.
 140
 141         The \a Sink must fulfill the following interface:
 142         \code
 143           class SomeSink
 144           {
 145           public:
 146               typedef unspecified Handle;                          // type of handle requested
 147
 148               SomeSink();                                          // EITHER default constructible
 149               SomeSink(SomeSink const & other);                    // OR copy constructible
 150
 151               void operator()(Handle handle, Packet packet);       // insertion function
 152           };
 153         \endcode
 154         Whenever a packet is received for sending, the \a Sink's \c operator() is called.
 155
 156         \ingroup io_modules
 157      */
 158     template <class Sink=PacketSink>
 159     class PassiveSocketSink : public Module
 160     {
 161         SENF_PPI_MODULE(PassiveSocketSink);
 162
 163     public:
 164         typedef typename Sink::Handle Handle; ///< Handle type requested by writer
 165
 166         connector::PassiveInput input; ///< Input connector from which data is received
 167
 168         PassiveSocketSink(Handle handle); ///< Create new writer for the given handle
 169                                         /**< Data will be written to \a handle using \a Sink.
 170                                              \pre Requires \a Sink to be default constructible
 171                                              \param[in] handle Handle to write data to */
 172         PassiveSocketSink(Handle handle, Sink const & sink);
 173                                         ///< Create new writer for the given handle
 174                                         /**< Data will be written to \a handle using \a Sink.
 175                                              \pre Requires \a Sink to be copy constructible
 176                                              \param[in] handle Handle to write data to */
 177
 178         Sink & sink();                  ///< Access the sink helper
 179
 180     private:
 181         void write();
 182
 183         Handle handle_;
 184         Sink writer_;
 185     };
 186
 187 }}}
 188
 189
 190 ///////////////////////////////hh.e////////////////////////////////////////
 191 #include "SocketSink.cci"
 192 #include "SocketSink.ct"
 193 #include "SocketSink.cti"
 194 #endif
 195
 196 \f
 197 // Local Variables:
 198 // mode: c++
 199 // fill-column: 100
 200 // c-file-style: "senf"
 201 // indent-tabs-mode: nil
 202 // ispell-local-dictionary: "american"
 203 // compile-command: "scons -u test"
 204 // comment-column: 40
 205 // End: