senf/Packets/GenericTLV.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2009
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Thorsten Horstmann <tho@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 GenericTLV public header */
  25
  26 #ifndef HH_SENF_Packets_GenericTLV_
  27 #define HH_SENF_Packets_GenericTLV_ 1
  28
  29 // Custom includes
  30 #include <senf/Packets/Packets.hh>
  31 #include <senf/Utils/type_traits.hh>
  32
  33 //#include "GenericTLV.hh.mpp"
  34 ///////////////////////////////hh.p////////////////////////////////////////
  35
  36 namespace senf {
  37
  38     /** \brief Base class for generic TLV parsers
  39
  40        This abstract base class can be used to define generic TLV parsers. The following
  41        class structure is assumed:
  42        \image html GenericTLV.png
  43
  44         Your TLVParser base class has to define a \c type and a \c length field:
  45         \code
  46         struct MyTLVParserBase : public senf::PacketParserBase
  47         {
  48         #   include SENF_PARSER()
  49             SENF_PARSER_FIELD    ( type,   senf::UInt8Parser );
  50             SENF_PARSER_FIELD_RO ( length, senf::UInt8Parser );
  51             SENF_PARSER_FINALIZE ( MyTLVParserBase           );
  52         };
  53         \endcode
  54
  55         Your concrete TLV parsers will inherit from this base class and have to define a specific
  56         value field and a \c TYPEID member:
  57         \code
  58         struct MyConcreteTLVParser : public MyTLVParserBase
  59         {
  60         #   include SENF_PARSER()
  61             SENF_PARSER_INHERIT  ( MyTLVParserBase             );
  62             SENF_PARSER_FIELD    ( myValue, senf::UInt32Parser );
  63             SENF_PARSER_FINALIZE ( MyConcreteTLVParser         );
  64
  65             SENF_PARSER_INIT() {
  66                 type() = TYPEID;
  67                 length_() = 4;
  68             }
  69             static const type_t::value_type TYPEID = 0x42;
  70         };
  71         \endcode
  72
  73         With GenericTLVParserBase you can define a generic parser class which provides
  74         members to access the value data and and to cast the parser to a concrete tlv
  75         parser:
  76         \code
  77         struct MyGenericTLVParser : public senf::GenericTLVParserBase<MyTLVParserBase>
  78         {
  79             typedef senf::GenericTLVParserBase<MyTLVParserBase> base;
  80             MyGenericTLVParser(data_iterator i, state_type s) : base(i,s) {}
  81
  82             // members for your generic TLV parser...
  83         };
  84         \endcode
  85
  86         If your generic TLV parser just inherits from GenericTLVParserBase and doesn't
  87         add any additional functionality you can use a simple \c typedef as well:
  88         \code
  89         typedef senf::GenericTLVParserBase<MyTLVParserBase> MyGenericTLVParser;
  90         \endcode
  91
  92         This generiv tlv parser can now be used for example in a list:
  93         \code
  94         class MyTestPacketParser : public senf::PacketParserBase
  95         {
  96         #   include SENF_PARSER()
  97             SENF_PARSER_FIELD_RO ( list_length, senf::UInt8Parser );
  98             SENF_PARSER_LIST     ( tlv_list, list_length, MyGenericTLVParser );
  99             SENF_PARSER_FINALIZE ( MyTestPacketParser );
 100         };
 101         \endcode
 102
 103         Now, you can access the TLV parsers in the list in a generic way or you
 104         can cast the parsers to some concrete tlv parser:
 105         \code
 106         MyTestPacket p (...
 107         typedef MyTestPacket::Parser::tlv_list_t::container container_t;
 108         container_t tlvContainer (p->tlv_list() );
 109         optContainer_t::iterator listIter (tlvContainer.begin());
 110
 111         // listIter points to a MyGenericTLVParser, so you have generic access:
 112         listIter->type() = 0x42;
 113         listIter->value( someRangeOfValueData);
 114
 115         // cast to an instance of MyConcreteTLVParser:
 116         if (listIter->is<MyConcreteTLVParser>()) {
 117             MyConcreteTLVParser concreteTLVParser ( listIter->as<MyConcreteTLVParser>());
 118             concreteTLVParser.myValue() = 0xabababab;
 119         }
 120
 121         // add a MyConcreteTLV to the list:
 122         MyConcreteTLVParser tlv ( tlvContainer.push_back_space().init<MyConcreteTLVParser>());
 123         tlv.myValue() = 0xffff;
 124         \endcode
 125
 126         \see
 127             IPv6GenericOptionTLVParser, \n
 128             WLANGenericInfoElementParser
 129      */
 130     template <class Base>
 131     class GenericTLVParserBase : public Base
 132     {
 133     public:
 134         GenericTLVParserBase(senf::PacketParserBase::data_iterator i, senf::PacketParserBase::state_type s)
 135             : Base(i,s) {}
 136
 137         senf::PacketParserBase::size_type bytes();
 138         void init() const;
 139
 140         template <class Parser>
 141         Parser init();
 142
 143         template <class Parser>
 144         Parser as();
 145
 146         template <class Parser>
 147         bool is();
 148
 149         senf::PacketInterpreterBase::range value() const;
 150
 151 #ifndef DOXYGEN
 152         template<class ForwardReadableRange>
 153         void value(ForwardReadableRange const & val,
 154                 typename boost::disable_if<senf::is_pair<ForwardReadableRange> >::type * = 0);
 155
 156         template<class First, class Second>
 157         void value(std::pair<First, Second> const & val,
 158                 typename boost::disable_if<boost::is_convertible<First, typename Base::type_t::value_type> >::type * = 0);
 159
 160         template <class Type, class ForwardReadableRange>
 161         void value(std::pair<Type, ForwardReadableRange> const & val,
 162                 typename boost::enable_if<boost::is_convertible<Type, typename Base::type_t::value_type> >::type * = 0);
 163 #else
 164         template<class ForwardReadableRange>
 165         void value(ForwardReadableRange const & val);
 166
 167         template <class ForwardReadableRange>
 168         void value(std::pair<typename Base::type_t::value_type, ForwardReadableRange> const & val);
 169 #endif
 170
 171     private:
 172         template<class ForwardReadableRange>
 173         void value_(ForwardReadableRange const &range);
 174     };
 175 }
 176
 177
 178 ///////////////////////////////hh.e////////////////////////////////////////
 179 //#include "GenericTLV.cci"
 180 #include "GenericTLV.ct"
 181 #include "GenericTLV.cti"
 182 #endif
 183
 184 \f
 185 // Local Variables:
 186 // mode: c++
 187 // fill-column: 100
 188 // comment-column: 40
 189 // c-file-style: "senf"
 190 // indent-tabs-mode: nil
 191 // ispell-local-dictionary: "american"
 192 // compile-command: "scons -u test"
 193 // End: