From: tho <tho@270642c3-0616-0410-b53a-bc976706d245>
Date: Mon, 12 Oct 2009 13:31:52 +0000 (+0000)
Subject: Packets/GenericTLV: started with documentation how to use GenericTLVBase
X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=d827fa2c49602de3e7d9559810408f258b5987ba;p=senf.git

Packets/GenericTLV: started with documentation how to use GenericTLVBase
Packets: some minor documentation and #include clean ups

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

diff --git a/senf/Packets/80211Bundle/RadiotapPacket.cc b/senf/Packets/80211Bundle/RadiotapPacket.cc
index 4699d90..7fd01cf 100644
--- a/senf/Packets/80211Bundle/RadiotapPacket.cc
+++ b/senf/Packets/80211Bundle/RadiotapPacket.cc
@@ -20,12 +20,13 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
-// Definition of non-inline non-template functions
+// Definition of RadiotapPacket non-inline non-template functions
 
-// Custom includes
 #include "RadiotapPacket.hh"
+//#include "RadiotapPacket.ih"
+
+// Custom includes
 #include "WLANPacket.hh"
-#include <senf/Packets/Packets.hh>
 #include <boost/io/ios_state.hpp>
 
 #define prefix_
diff --git a/senf/Packets/80211Bundle/RadiotapPacket.hh b/senf/Packets/80211Bundle/RadiotapPacket.hh
index 5987c0e..b84ea55 100644
--- a/senf/Packets/80211Bundle/RadiotapPacket.hh
+++ b/senf/Packets/80211Bundle/RadiotapPacket.hh
@@ -26,10 +26,11 @@
 #ifndef HH_SENF_Packets_80211Bundle_RadiotapPacket_
 #define HH_SENF_Packets_80211Bundle_RadiotapPacket_ 1
 
+// Custom includes
 #include <senf/Packets/Packets.hh>
 
-namespace senf
-{
+///////////////////////////////hh.p////////////////////////////////////////
+namespace senf {
 
     /** \brief Parse Flag field in Radiotap header
 
@@ -232,6 +233,10 @@ namespace senf
     typedef ConcretePacket<RadiotapPacketType> RadiotapPacket;
 }
 
+///////////////////////////////hh.e////////////////////////////////////////
+//#include "RadiotapPacket.cci"
+//#include "RadiotapPacket.ct"
+//#include "RadiotapPacket.cti"
 #endif
 
 
diff --git a/senf/Packets/80211Bundle/RadiotapPacket.test.cc b/senf/Packets/80211Bundle/RadiotapPacket.test.cc
index b16a46f..57da0d3 100644
--- a/senf/Packets/80211Bundle/RadiotapPacket.test.cc
+++ b/senf/Packets/80211Bundle/RadiotapPacket.test.cc
@@ -25,7 +25,6 @@
 
 // Custom includes
 #include "RadiotapPacket.hh"
-#include <senf/Packets/Packets.hh>
 
 #include <senf/Utils/auto_unit_test.hh>
 #include <boost/test/test_tools.hpp>
diff --git a/senf/Packets/80211Bundle/WLANBeaconPacket.hh b/senf/Packets/80211Bundle/WLANBeaconPacket.hh
index 8443d3d..a8accfa 100644
--- a/senf/Packets/80211Bundle/WLANBeaconPacket.hh
+++ b/senf/Packets/80211Bundle/WLANBeaconPacket.hh
@@ -55,7 +55,7 @@ namespace senf {
     /** \brief WLAN Beacon frame packet
 
         \par Packet type (typedef):
-            \refWLANBeaconPacket
+            \ref WLANBeaconPacket
 
         \par Fields:
 
diff --git a/senf/Packets/80211Bundle/WLANBeaconPacket.test.cc b/senf/Packets/80211Bundle/WLANBeaconPacket.test.cc
index e36846f..d38d2ad 100644
--- a/senf/Packets/80211Bundle/WLANBeaconPacket.test.cc
+++ b/senf/Packets/80211Bundle/WLANBeaconPacket.test.cc
@@ -116,7 +116,6 @@ BOOST_AUTO_UNIT_TEST(WLANBeaconPacket_create)
 }
 
 ///////////////////////////////cc.e////////////////////////////////////////
-#undef prefix_
 
 
 // Local Variables:
diff --git a/senf/Packets/80211Bundle/WLANPacket.hh b/senf/Packets/80211Bundle/WLANPacket.hh
index 794007b..69c25a7 100644
--- a/senf/Packets/80211Bundle/WLANPacket.hh
+++ b/senf/Packets/80211Bundle/WLANPacket.hh
@@ -98,7 +98,7 @@ namespace senf
     /** \brief WLAN Management frame packet
 
         \par Packet type (typedef):
-            \refWLANPacket_MgtFrame
+            \ref WLANPacket_MgtFrame
 
         \par Fields:
             \ref WLANPacket_MgtFrameParser
diff --git a/senf/Packets/80211Bundle/WLANPacket.test.cc b/senf/Packets/80211Bundle/WLANPacket.test.cc
index 1c0a7c5..36a1c3c 100644
--- a/senf/Packets/80211Bundle/WLANPacket.test.cc
+++ b/senf/Packets/80211Bundle/WLANPacket.test.cc
@@ -25,8 +25,6 @@
 
 // Custom includes
 #include "WLANPacket.hh"
-#include <senf/Packets/Packets.hh>
-#include <senf/Packets/DefaultBundle/LlcSnapPacket.hh>
 
 #include <senf/Utils/auto_unit_test.hh>
 #include <boost/test/test_tools.hpp>
@@ -202,6 +200,8 @@ BOOST_AUTO_UNIT_TEST(WLANPacket_ctrlFrame_create)
     BOOST_CHECK_EQUAL( p->subtype(), 13u);
 }
 
+///////////////////////////////cc.e////////////////////////////////////////
+
 
 // Local Variables:
 // mode: c++
diff --git a/senf/Packets/DefaultBundle/ListOptionTypeParser.ih b/senf/Packets/DefaultBundle/ListOptionTypeParser.ih
index 5894386..da3d40e 100644
--- a/senf/Packets/DefaultBundle/ListOptionTypeParser.ih
+++ b/senf/Packets/DefaultBundle/ListOptionTypeParser.ih
@@ -36,7 +36,7 @@ namespace senf {
 
         /** \brief Internal: ListPolicy defing the ListOptionTypeParser parser
          \internal
-         \see \ref ListOptionTypeParser
+         \see IPv6HopByHopOptionsPacketParser::ListOptionTypeParser
          */
         template <class ElementParser, class AuxPolicy>
         struct ListOptionTypeParser_Policy
diff --git a/senf/Packets/GenericTLV.cti b/senf/Packets/GenericTLV.cti
index f66eec3..913ef63 100644
--- a/senf/Packets/GenericTLV.cti
+++ b/senf/Packets/GenericTLV.cti
@@ -57,6 +57,8 @@ prefix_ bool senf::GenericTLVParserBase<Base>::is()
     return this->type().value() == Parser::TYPEID;
 }
 
+#ifndef DOXYGEN
+
 template <class Base>
 template <class ForwardReadableRange>
 prefix_ void senf::GenericTLVParserBase<Base>::value(
@@ -85,6 +87,8 @@ prefix_ void senf::GenericTLVParserBase<Base>::value(
     value_( val.second); 
 }
 
+#endif
+
 ///////////////////////////////cti.e///////////////////////////////////////
 #undef prefix_
 
diff --git a/senf/Packets/GenericTLV.dia b/senf/Packets/GenericTLV.dia
new file mode 100644
index 0000000..c1d6b1b
Binary files /dev/null and b/senf/Packets/GenericTLV.dia differ
diff --git a/senf/Packets/GenericTLV.hh b/senf/Packets/GenericTLV.hh
index 894d728..e4c84e6 100644
--- a/senf/Packets/GenericTLV.hh
+++ b/senf/Packets/GenericTLV.hh
@@ -35,6 +35,98 @@
 
 namespace senf {
  
+    /** \brief Base class for generic TLV parsers
+       
+       This abstract base class can be used to define generic TLV parsers. The following
+       class structure is assumed:
+       \image html GenericTLV.png
+        
+        Your TLVParser base class has to define a \c type and a \c length field:
+        \code
+        struct MyTLVParserBase : public senf::PacketParserBase
+        {
+        #   include SENF_PARSER()
+            SENF_PARSER_FIELD    ( type,   senf::UInt8Parser );
+            SENF_PARSER_FIELD_RO ( length, senf::UInt8Parser );
+            SENF_PARSER_FINALIZE ( MyTLVParserBase           );
+        };
+        \endcode
+       
+        Your concrete TLV parsers will inherit from this base class and have to define a specific
+        value field and a \c TYPEID member:
+        \code
+        struct MyConcreteTLVParser : public MyTLVParserBase
+        {
+        #   include SENF_PARSER()
+            SENF_PARSER_INHERIT  ( MyTLVParserBase             );
+            SENF_PARSER_FIELD    ( myValue, senf::UInt32Parser );
+            SENF_PARSER_FINALIZE ( MyConcreteTLVParser         );
+         
+            SENF_PARSER_INIT() {
+                type() = TYPEID;
+                length_() = 4;
+            }        
+            static const type_t::value_type TYPEID = 0x42;
+        };
+        \endcode
+       
+        With GenericTLVParserBase you can define a generic parser class which provides
+        members to access the value data and and to cast the parser to a concrete tlv
+        parser:   
+        \code
+        struct MyGenericTLVParser : public senf::GenericTLVParserBase<MyTLVParserBase>
+        {
+            typedef senf::GenericTLVParserBase<MyTLVParserBase> base;
+            MyGenericTLVParser(data_iterator i, state_type s) : base(i,s) {}
+            
+            // members for your generic TLV parser...
+        };
+        \endcode
+        
+        If your generic TLV parser just inherits from GenericTLVParserBase and doesn't
+        add any additional functionality you can use a simple \c typedef as well:
+        \code
+        typedef senf::GenericTLVParserBase<MyTLVParserBase> MyGenericTLVParser;
+        \endcode
+        
+        This generiv tlv parser can now be used for example in a list:
+        \code
+        class MyTestPacketParser : public senf::PacketParserBase
+        {
+        #   include SENF_PARSER()
+            SENF_PARSER_FIELD_RO ( list_length, senf::UInt8Parser );
+            SENF_PARSER_LIST     ( tlv_list, list_length, MyGenericTLVParser );
+            SENF_PARSER_FINALIZE ( MyTestPacketParser );
+        };
+        \endcode
+        
+        Now, you can access the TLV parsers in the list in a generic way or you
+        can cast the parsers to some concrete tlv parser:
+        \code
+        MyTestPacket p (...
+        typedef MyTestPacket::Parser::tlv_list_t::container container_t;
+        container_t tlvContainer (p->tlv_list() );
+        optContainer_t::iterator listIter (tlvContainer.begin());
+        
+        // listIter points to a MyGenericTLVParser, so you have generic access:
+        listIter->type() = 0x42;
+        listIter->value( someRangeOfValueData);
+        
+        // cast to an instance of MyConcreteTLVParser:
+        if (listIter->is<MyConcreteTLVParser>()) {
+            MyConcreteTLVParser concreteTLVParser ( listIter->as<MyConcreteTLVParser>());
+            concreteTLVParser.myValue() = 0xabababab;
+        }
+        
+        // add a MyConcreteTLV to the list:
+        MyConcreteTLVParser tlv ( tlvContainer.push_back_space().init<MyConcreteTLVParser>());
+        tlv.myValue() = 0xffff;
+        \endcode  
+
+        \see 
+            IPv6GenericOptionTLVParser, \n
+            WLANGenericInfoElementParser 
+     */
     template <class Base>
     class GenericTLVParserBase : public Base
     {
@@ -56,6 +148,7 @@ namespace senf {
 
         senf::PacketInterpreterBase::range value() const;
         
+#ifndef DOXYGEN
         template<class ForwardReadableRange>
         void value(ForwardReadableRange const & val,
                 typename boost::disable_if<senf::is_pair<ForwardReadableRange> >::type * = 0);
@@ -67,7 +160,14 @@ namespace senf {
         template <class Type, class ForwardReadableRange>
         void value(std::pair<Type, ForwardReadableRange> const & val,
                 typename boost::enable_if<boost::is_convertible<Type, typename Base::type_t::value_type> >::type * = 0);        
-
+#else
+        template<class ForwardReadableRange>
+        void value(ForwardReadableRange const & val);
+        
+        template <class ForwardReadableRange>
+        void value(std::pair<typename Base::type_t::value_type, ForwardReadableRange> const & val);
+#endif   
+        
     private:
         template<class ForwardReadableRange>
         void value_(ForwardReadableRange const &range);
diff --git a/senf/Packets/ListBParser.ih b/senf/Packets/ListBParser.ih
index d8f7b11..aa72d28 100644
--- a/senf/Packets/ListBParser.ih
+++ b/senf/Packets/ListBParser.ih
@@ -36,7 +36,7 @@ namespace detail {
 
     /** \brief Internal: ListPolicy defing the ListBParser parser
         \internal
-        \see \ref ListBParser
+        \see \ref ListParser
      */
     template <class ElementParser, class AuxPolicy>
     struct ListBParser_Policy
diff --git a/senf/Packets/ListNParser.ih b/senf/Packets/ListNParser.ih
index f50bbfd..2c8ad05 100644
--- a/senf/Packets/ListNParser.ih
+++ b/senf/Packets/ListNParser.ih
@@ -36,7 +36,7 @@ namespace detail {
 
     /** \brief Internal: ListPolicy defining the ListNParser parser
         \internal
-        \see \ref ListNParser
+        \see \ref ListParser
      */
     template <class ElementParser, class AuxPolicy>
     struct ListNParser_Policy
diff --git a/senf/Packets/ListParser.hh b/senf/Packets/ListParser.hh
index d7c19a1..352d6b1 100644
--- a/senf/Packets/ListParser.hh
+++ b/senf/Packets/ListParser.hh
@@ -63,7 +63,7 @@ namespace senf {
         packet_usage_fields_collection.
 
         \see 
-            \ref How to access \ref packet_usage_fields_collection
+            How to access \ref packet_usage_fields_collection \n
             SENF_PARSER_LIST() macro used to define list fields \n
             ListParser_Container list container wrapper API \n
             ExampleListPolicy
diff --git a/senf/Packets/MPEGDVBBundle/MPESection.hh b/senf/Packets/MPEGDVBBundle/MPESection.hh
index 7c1d7b5..d537eef 100644
--- a/senf/Packets/MPEGDVBBundle/MPESection.hh
+++ b/senf/Packets/MPEGDVBBundle/MPESection.hh
@@ -141,7 +141,9 @@ namespace senf {
         static PacketParserBase::size_type initHeadSize();
     };
 
-    /** \brief MPESection packet typedef */
+    /** \brief MPESection packet typedef 
+         \ingroup protocolbundle_mpegdvb
+     */
     typedef ConcretePacket<MPESectionType> MPESection;
 }
 
diff --git a/senf/Packets/PacketData.hh b/senf/Packets/PacketData.hh
index 0860062..4218a71 100644
--- a/senf/Packets/PacketData.hh
+++ b/senf/Packets/PacketData.hh
@@ -29,9 +29,7 @@
 // Custom includes
 #include <boost/utility.hpp>
 #include <boost/type_traits.hpp>
-#include <senf/Utils/safe_bool.hh>
 #include <senf/Utils/Exception.hh>
-#include "PacketTypes.hh"
 
 //#include "PacketData.mpp"
 ///////////////////////////////hh.p////////////////////////////////////////
diff --git a/senf/Packets/PacketImpl.hh b/senf/Packets/PacketImpl.hh
index e0ab170..489c6e2 100644
--- a/senf/Packets/PacketImpl.hh
+++ b/senf/Packets/PacketImpl.hh
@@ -35,7 +35,6 @@
 #include <boost/type_traits/has_trivial_destructor.hpp>
 #include <boost/static_assert.hpp>
 #include <senf/Utils/pool_alloc_mixin.hh>
-#include "PacketTypes.hh"
 #include <senf/Utils/singleton.hh>
 
 //#include "PacketImpl.mpp"
diff --git a/senf/Packets/SConscript b/senf/Packets/SConscript
index 7fa90ca..b6a6376 100644
--- a/senf/Packets/SConscript
+++ b/senf/Packets/SConscript
@@ -8,6 +8,7 @@ import SENFSCons
 SENFSCons.AutoRules(env, exclude = [ 'bundledump.cc' ], doc_extra_sources = [
     env.Dia2Png("structure.dia"),
     env.Dia2Png("80221Bundle/TLV.dia"),
+    env.Dia2Png("GenericTLV.dia"),
     env.PkgDraw("MPEGDVBBundle/DTCPPacket.hh"),
     env.PkgDraw("DefaultBundle/EthernetPacket.hh",
                 PKGDRAWPACKETS = "EthernetPacketParser"),