From: tho <tho@270642c3-0616-0410-b53a-bc976706d245>
Date: Mon, 19 Oct 2009 13:32:26 +0000 (+0000)
Subject: Packets/GenericTLV: added some documentation
X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=52ceda9d4019d45ef0d1a941d517b4ffeafe547b;p=senf.git

Packets/GenericTLV: added some documentation
SConstruct: added command line arguments to SCONSARGS

git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@1503 270642c3-0616-0410-b53a-bc976706d245
---

diff --git a/SConstruct b/SConstruct
index d853a52..1fd27f0 100644
--- a/SConstruct
+++ b/SConstruct
@@ -102,7 +102,8 @@ env.SetDefault(
     LCOV              = "lcov",
     GENHTML           = "genhtml",
     SCONSBIN          = env.File("#/tools/scons"),
-    SCONSARGS          = [ '-Q', '-j$CONCURRENCY_LEVEL', 'debug=$debug', 'final=$final' ],
+    SCONSARGS         = [ '-Q', '-j$CONCURRENCY_LEVEL', 'debug=$debug', 'final=$final' ] + \
+        [ '%s=%s' % (k,v) for k,v in ARGUMENTS.iteritems() ],
     SCONS             = "@$SCONSBIN $SCONSARGS",
     CONCURRENCY_LEVEL = env.GetOption('num_jobs') or 1,
     TOPDIR            = env.Dir('#').abspath,
diff --git a/senf/Packets/80221Bundle/TLVParser.hh b/senf/Packets/80221Bundle/TLVParser.hh
index b93f925..c8b49ad 100644
--- a/senf/Packets/80221Bundle/TLVParser.hh
+++ b/senf/Packets/80221Bundle/TLVParser.hh
@@ -130,7 +130,7 @@ namespace senf {
             protect(), length_().finalize();
         };
     
-    typedef GenericTLVParserRegistry<MIHBaseTLVParser> Registry;
+        typedef GenericTLVParserRegistry<MIHBaseTLVParser> Registry;
         
     protected:
         /// resize the packet after the length field to given size
diff --git a/senf/Packets/GenericTLV.ct b/senf/Packets/GenericTLV.ct
index 44b748d..f1f34f7 100644
--- a/senf/Packets/GenericTLV.ct
+++ b/senf/Packets/GenericTLV.ct
@@ -89,6 +89,7 @@ prefix_ void senf::GenericTLVParserRegistry<BaseParser>::registerParser()
 template <class BaseParser>
 prefix_ void senf::GenericTLVParserRegistry<BaseParser>::dump(
         GenericTLVParserBase<BaseParser> const & parser, std::ostream & os)
+    const
 {
     typename Map::iterator i (map_.find( parser.type()));
     if (i == map_.end()) {
diff --git a/senf/Packets/GenericTLV.cti b/senf/Packets/GenericTLV.cti
index 5500516..5c75565 100644
--- a/senf/Packets/GenericTLV.cti
+++ b/senf/Packets/GenericTLV.cti
@@ -121,6 +121,7 @@ prefix_ void senf::GenericTLVParserBase<Base>::value(
 template <class BaseParser, class Parser>
 prefix_ void senf::detail::GenericTLVParserRegistry_Entry<BaseParser, Parser>::dump(
         GenericTLVParserBase<BaseParser> const & parser, std::ostream & os)
+    const
 {
     (parser.template as<Parser>()).dump(os);
 }
diff --git a/senf/Packets/GenericTLV.hh b/senf/Packets/GenericTLV.hh
index e14f5c6..e6f798a 100644
--- a/senf/Packets/GenericTLV.hh
+++ b/senf/Packets/GenericTLV.hh
@@ -126,7 +126,8 @@ namespace senf {
         \endcode  
 
         \see 
-            IPv6GenericOptionTLVParser, WLANGenericInfoElementParser, MIHGenericTLVParser 
+            IPv6GenericOptionParser, WLANGenericInfoElementParser, MIHGenericTLVParser \n
+            GenericTLVParserRegistry
      */
     template <class Base>
     class GenericTLVParserBase : public Base
@@ -183,17 +184,65 @@ namespace senf {
     namespace detail {
         template <class BaseParser>
         struct GenericTLVParserRegistry_EntryBase {
-            virtual void dump(GenericTLVParserBase<BaseParser> const & parser, std::ostream & os) = 0;
+            virtual void dump(GenericTLVParserBase<BaseParser> const & parser, std::ostream & os) const = 0;
         };
     
         template <class BaseParser, class Parser>
         struct GenericTLVParserRegistry_Entry
             : GenericTLVParserRegistry_EntryBase<BaseParser>
         {
-            virtual void dump(GenericTLVParserBase<BaseParser> const & parser, std::ostream & os);
+            virtual void dump(GenericTLVParserBase<BaseParser> const & parser, std::ostream & os) const;
         };
     }
     
+    /** \brief TLV parser registration facility
+
+        The %GenericTLVParserRegistry provides a generic facility to globally register concrete
+        TLV parser by the type value. The concrete TLV parser must therefore provide a \c typeId
+        member. See GenericTLVParserBase for details about the assumed class structure.
+        
+        Every registry is identified by the base tlv parser class. Parsers can be registered 
+        statically only: 
+        \code
+        GenericTLVParserRegistry<MyTLVParserBase>::RegistrationProxy<ConcreteTLVParser>
+            registerConcreteTLVParser;
+        \endcode 
+        This global variable declaration will register ConcreteTLVParser. The variable 
+        registerConcreteTLVParser is a dummy. It's only function is to force the call of 
+        it's constructor during global construction time. This static registration only
+        works when the symbol is included into the final binary.
+        
+        To simplify the registration the \ref SENF_PACKET_TLV_REGISTRY_REGISTER macro can be used.
+        The \c ConreteTLVParser must therefore provide a \c Registry typedef pointing to the
+        %GenericTLVParserRegistry; typically you put this typedef to the TLVBaseParser class.
+        \code
+        struct MyTLVParserBase : public senf::PacketParserBase
+        {
+            ...
+            typedef GenericTLVParserRegistry<MyTLVParserBase> Registry;
+        };
+        struct MyConcreteTLVParser : public MyTLVParserBase
+        {
+            ....
+            static const type_t::value_type typeId = 0x42;
+            void dump(std::ostream & os) const;
+        };
+        
+        // register MyConcreteTLVParser to the MyTLVParserBase-Registry with the type id 0x42:
+        SENF_PACKET_TLV_REGISTRY_REGISTER( MyConcreteTLVParser );
+        \endcode
+        
+        The registry provides a dump() member to dump an instance of a generic TLV parser.
+        If the type value of the given TLV parser is registered the generic tlv will be
+        casted to the registered concrete TLV parser and the dump member from this parser
+        will be called. Otherwise the generic TLV parser will be dumped in a generic way
+        (hexdump of the value).
+        
+        \see
+            GenericTLVParserBase for the general TLV class structure \n
+            IPv6OptionParser::Registry, WLANInfoElementParser::Registry,
+            MIHBaseTLVParser::Registry 
+     */
     template <class BaseParser>
     class GenericTLVParserRegistry
         : public senf::singleton<GenericTLVParserRegistry<BaseParser> >
@@ -216,9 +265,17 @@ namespace senf {
         template <typename Parser>
         void registerParser();
         
-        void dump(GenericTLVParserBase<BaseParser> const & parser, std::ostream & os);
+        void dump(GenericTLVParserBase<BaseParser> const & parser, std::ostream & os) const;
     };
         
+    /** \brief Statically add an entry to a TLV parser registry
+
+        This macro will declare an anonymous global variable in such a way, that constructing 
+        this variable will register the given tlv parser.
+
+        \hideinitializer
+        \see senf::GenericTLVParserRegistry
+     */
 #   define SENF_PACKET_TLV_REGISTRY_REGISTER( ConreteTLVParser )                \
         namespace {                                                             \
             ConreteTLVParser::Registry::RegistrationProxy<ConreteTLVParser>     \