PPI: Add missing TargetDgramWriter doku

[senf.git] / PPI / Setup.hh

diff --git a/PPI/Setup.hh b/PPI/Setup.hh
index a4b0b03..7ca5068 100644 (file)
--- a/PPI/Setup.hh
+++ b/PPI/Setup.hh
@@ -1,8 +1,8 @@
 // $Id$
 //
-// Copyright (C) 2007 
-// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
-// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
+// Copyright (C) 2007
+// Fraunhofer Institute for Open Communication Systems (FOKUS)
+// Competence Center NETwork research (NET), St. Augustin, GERMANY
 //     Stefan Bund <g0dil@berlios.de>
 //
 // This program is free software; you can redistribute it and/or modify
@@ -23,8 +23,8 @@
 /** \file
     \brief Setup public header */
 
-#ifndef HH_Setup_
-#define HH_Setup_ 1
+#ifndef HH_SENF_PPI_Setup_
+#define HH_SENF_PPI_Setup_ 1
 
 // Custom includes
 #include <boost/type_traits.hpp>
@@ -37,43 +37,60 @@
 namespace senf {
 namespace ppi {
 
+#ifdef DOXYGEN
+
+    /** \brief Connect modules
+
+        senf::ppi::connect() establishes a connection between two modules or, to be more precise,
+        between two connectors. It will connect any input to any output connector as long as one is
+        active and the other passive.
+
+        If a module has an output connector called \c output, the module may be directly specified
+        as \a source argument. In the same way, if a module has an input connector called \c input,
+        the module may be given directly as \a target argument. This simplifies the most common case
+        of a module with one input and one output connector.
+
+        The connect call will check at runtime, whether the two connectors are type-compatible:
+        \li Either or both of the connectors are untyped (they accept/send arbitrary senf::Packet's)
+        \li Both connectors send/accept the exactly same packet type.
+
+        Depending on the type of input or output, the connect call may require additional
+        arguments. See the respective module documentation for more information
+
+        \throws connector::IncompatibleConnectorsException if the two connectors are not type
+            compatible.
+        
+        \see \ref ppi_connections
+     */
+    void connect(connector::OutputConnector & source, connector::InputConnector & target, ...);
+
+#else
+
+    void connect(connector::GenericActiveOutput & source, connector::GenericPassiveInput & target);
+    void connect(connector::GenericPassiveOutput & source, connector::GenericActiveInput & target);
+
+#endif
+
 #ifndef DOXYGEN    
 
-    void connect(connector::ActiveOutput & source, connector::PassiveInput & target);
-    void connect(connector::PassiveOutput & source, connector::ActiveInput & target);
-    
     template <class T, class C>
     void connect(T & source, C & target,
                  typename boost::disable_if< boost::is_base_of<connector::Connector, T> >::type * = 0,
-                 typename boost::enable_if< boost::is_base_of<connector::Connector, C> >::type * = 0);
+                 typename boost::enable_if< boost::is_base_of<connector::Connector, C> >::type * = 0,
+                 typename boost::disable_if< boost::is_base_of<connector::Jack, T> >:: type * = 0);
 
     template <class C, class T>
     void connect(C & source, T & target,
                  typename boost::enable_if< boost::is_base_of<connector::Connector, C> >::type * = 0,
-                 typename boost::disable_if< boost::is_base_of<connector::Connector,T> >::type * = 0);
+                 typename boost::disable_if< boost::is_base_of<connector::Connector,T> >::type * = 0,
+                 typename boost::disable_if< boost::is_base_of<connector::Jack, T> >:: type * = 0);
 
     template <class T1, class T2>
     void connect(T1 & source, T2 & target,
                  typename boost::disable_if< boost::is_base_of<connector::Connector, T1> >::type * = 0,
-                 typename boost::disable_if< boost::is_base_of<connector::Connector, T2> >::type * = 0);
-
-#else
-
-    /** \brief Connect modules
-
-        senf::ppi::connect() establishes a connection between two modules or, to be more precise,
-        between two connectors. For enhanced usability, \a source and \a target may be a Connector,
-        a Module or a collection/subnetwork. Passing a Module or collection/subnetwork as \a source
-        will originate the connection on the \c output member of that Module or collection while
-        passing a module or collection/subnetwork as \a target will terminate the connection on that
-        Module or collections \c input member. For most simple modules, the specification of the
-        connector is therefore obsolete.
-
-        Furthermore, the connect() call may be extended by special modules (e.g. PassiveJoin which
-        allows an arbitrary of input connections).
-     */
-    template <class Source, class Target>
-    void connect(Source & source, Target & target);
+                 typename boost::disable_if< boost::is_base_of<connector::Connector, T2> >::type * = 0,
+                 typename boost::disable_if< boost::is_base_of<connector::Jack, T1> >:: type * = 0,
+                 typename boost::disable_if< boost::is_base_of<connector::Jack, T2> >:: type * = 0);
 
 #endif
     
@@ -87,6 +104,8 @@ namespace ppi {
         enabled (Since the events are enabled and disabled by the throttle notifications which
         depend among other things on the packet queues, this is the same as checking for packets in
         any queue). It is Ok to call senf::ppi::run() multiple times during the program lifetime.
+
+        \see \ref ppi_run
      */
     void run();