PPI: Add senf::connect() packet type compatibility check documentation

[senf.git] / PPI / Connectors.hh

diff --git a/PPI/Connectors.hh b/PPI/Connectors.hh
index d96a0d7..60b1f71 100644 (file)
--- a/PPI/Connectors.hh
+++ b/PPI/Connectors.hh
@@ -31,6 +31,7 @@
 #include <boost/utility.hpp>
 #include <boost/scoped_ptr.hpp>
 #include "../Utils/safe_bool.hh"
+#include "../Utils/Exception.hh"
 #include "../Packets/Packets.hh"
 #include "predecl.hh"
 #include "detail/Callback.hh"
@@ -99,6 +100,9 @@ namespace connector {
             \ref ppi_connectors
      */
 
+    struct IncompatibleConnectorsException : public senf::Exception
+    { IncompatibleConnectorsException() : senf::Exception("Incompatible connectors") {} };
+
     /** \brief Connector base-class
 
         This connector provides access to the generic connector facilities. This includes the
@@ -119,6 +123,8 @@ namespace connector {
         void connect(Connector & target);
 
     private:
+        virtual std::type_info const & packetTypeID();
+
         void setModule(module::Module & module);
 
         Connector * peer_;
@@ -450,19 +456,23 @@ namespace connector {
 
 #   define TypedConnector_Input read
 #   define TypedConnector_Output write
-#   define TypedConnector(type, dir)                                                              \
+#   define TypedConnector(pType, dir)                                                             \
         template <class PacketType>                                                               \
-        class type ## dir                                                                         \
-            : public Generic ## type ## dir,                                                      \
-              private detail::Typed ## dir ## Mixin<type ## dir <PacketType>, PacketType>         \
+        class pType ## dir                                                                        \
+            : public Generic ## pType ## dir,                                                     \
+              private detail::Typed ## dir ## Mixin<pType ## dir <PacketType>, PacketType>        \
         {                                                                                         \
-            typedef detail::Typed ## dir ## Mixin<type ## dir <PacketType>, PacketType> mixin;    \
+            typedef detail::Typed ## dir ## Mixin<pType ## dir <PacketType>, PacketType> mixin;   \
         public:                                                                                   \
             using mixin::operator();                                                              \
             using mixin::TypedConnector_ ## dir ;                                                 \
+        private:                                                                                  \
+            virtual std::type_info const & packetTypeID()                                         \
+                { return typeid(typename PacketType::type); }                                     \
+            friend class detail::Typed ## dir ## Mixin<pType ## dir <PacketType>, PacketType>;    \
         };                                                                                        \
         template <>                                                                               \
-        class type ## dir <Packet> : public Generic ## type ## dir                                \
+        class pType ## dir <Packet> : public Generic ## pType ## dir                              \
         {}
 
     TypedConnector( Passive, Input  );
@@ -477,6 +487,8 @@ namespace connector {
 #else
 
     /** \brief Connector actively reading packets
+        
+        \tparam PacketType Type of packet to read. Defaults to senf::Packet
 
         The ActiveInput connector template reads data actively from a connected module. This class
         is completely implemented via it's base-class, GenericActiveInput, the only difference is
@@ -485,7 +497,7 @@ namespace connector {
         \see GenericActiveInput \n
             senf::ppi::connector
      */
-    template <class PacketType>
+    template <class PacketType=Packet>
     class ActiveInput : public GenericActiveInput
     {
     public:
@@ -498,6 +510,8 @@ namespace connector {
 
     /** \brief Connector passively receiving packets
 
+        \tparam PacketType Type of packet to read. Defaults to senf::Packet
+
         The PassiveInput connector template receives packets sent to it from a connected
         module. This class is completely implemented via it's base-class, GenericPassiveInput, the
         only difference is that read packets are returned as \a PacketType instead of generic
@@ -519,6 +533,8 @@ namespace connector {
 
     /** \brief Connector actively sending packets
 
+        \tparam PacketType Type of packet to send. Defaults to senf::Packet
+
         The ActiveOutput connector template sends data actively to a connected module. This class is
         completely implemented via it's base-class, GenericActiveOutput, the only difference is that
         it only sends packets of type \a PacketType.
@@ -526,16 +542,18 @@ namespace connector {
         \see GenericActiveOutput \n
             senf::ppi::connector
      */
-    template <class PacketType>
+    template <class PacketType=Packet>
     class ActiveOutput : public GenericActiveOutput
     {
     public:
-        PacketType operator()();
-        PacketType write();
+        operator()(PacketType packet);  ///< Send out a packet
+        write(PacketType packet);       ///< Alias for operator()
     };
 
     /** \brief Connector passively providing packets
 
+        \tparam PacketType Type of packet to send. Defaults to senf::Packet
+
         The PassiveOutput connector template provides data passively to a connected module whenever
         signaled. This class is completely implemented via it's base-class, GenericPassiveOutput, the
         only difference is that it only sends packets of type \a PacketType.
@@ -543,12 +561,12 @@ namespace connector {
         \see GenericPassiveOutput \n
             senf::ppi::connector
      */
-    template <class PacketType>
+    template <class PacketType=Packet>
     class PassiveOutput : public GenericPassiveOutput
     {
     public:
-        PacketType operator()();
-        PacketType write();
+        operator()(PacketType packet);  ///< Send out a packet
+        write(PacketType packet);       ///< Alias for operator()
     };
 
 #endif