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 <boost/ptr_container/ptr_map.hpp>
  31 #include <senf/Packets/Packets.hh>
  32 #include <senf/Utils/type_traits.hh>
  33 #include <senf/Utils/singleton.hh>
  34
  35 //#include "GenericTLV.hh.mpp"
  36 ///////////////////////////////hh.p////////////////////////////////////////
  37
  38 namespace senf {
  39
  40     /** \brief Base class for generic TLV parsers
  41
  42        This abstract base class can be used to define generic TLV parsers. The following
  43        class structure is assumed:
  44        \image html GenericTLV.png
  45
  46         Your TLVParser base class has to define a \c type and a \c length field:
  47         \code
  48         struct MyTLVParserBase : public senf::PacketParserBase
  49         {
  50         #   include SENF_PARSER()
  51             SENF_PARSER_FIELD    ( type,   senf::UInt8Parser );
  52             SENF_PARSER_FIELD_RO ( length, senf::UInt8Parser );
  53             SENF_PARSER_FINALIZE ( MyTLVParserBase           );
  54         };
  55         \endcode
  56
  57         Your concrete TLV parsers will inherit from this base class and have to define a specific
  58         value field and a \c typeId member:
  59         \code
  60         struct MyConcreteTLVParser : public MyTLVParserBase
  61         {
  62         #   include SENF_PARSER()
  63             SENF_PARSER_INHERIT  ( MyTLVParserBase             );
  64             SENF_PARSER_FIELD    ( myValue, senf::UInt32Parser );
  65             SENF_PARSER_FINALIZE ( MyConcreteTLVParser         );
  66
  67             SENF_PARSER_INIT() {
  68                 type() = typeId;
  69                 length_() = 4;
  70             }
  71             static const type_t::value_type typeId = 0x42;
  72         };
  73         \endcode
  74
  75         With GenericTLVParserBase you can define a generic parser class which provides
  76         members to access the value data and and to cast the parser to a concrete tlv
  77         parser:
  78         \code
  79         struct MyGenericTLVParser : public senf::GenericTLVParserBase<MyTLVParserBase>
  80         {
  81             typedef senf::GenericTLVParserBase<MyTLVParserBase> base;
  82             MyGenericTLVParser(data_iterator i, state_type s) : base(i,s) {}
  83
  84             // members for your generic TLV parser...
  85         };
  86         \endcode
  87
  88         If your generic TLV parser just inherits from GenericTLVParserBase and doesn't
  89         add any additional functionality you can use a simple \c typedef as well:
  90         \code
  91         typedef senf::GenericTLVParserBase<MyTLVParserBase> MyGenericTLVParser;
  92         \endcode
  93
  94         This generic tlv parser can now be used for example in a list:
  95         \code
  96         class MyTestPacketParser : public senf::PacketParserBase
  97         {
  98         #   include SENF_PARSER()
  99             SENF_PARSER_FIELD_RO ( list_length, senf::UInt8Parser );
 100             SENF_PARSER_LIST     ( tlv_list, list_length, MyGenericTLVParser );
 101             SENF_PARSER_FINALIZE ( MyTestPacketParser );
 102         };
 103         \endcode
 104
 105         Now, you can access the TLV parsers in the list in a generic way or you
 106         can cast the parsers to some concrete tlv parser:
 107         \code
 108         MyTestPacket p (...
 109         typedef MyTestPacket::Parser::tlv_list_t::container container_t;
 110         container_t tlvContainer (p->tlv_list() );
 111         optContainer_t::iterator listIter (tlvContainer.begin());
 112
 113         // listIter points to a MyGenericTLVParser, so you have generic access:
 114         listIter->type() = 0x42;
 115         listIter->value( someRangeOfValueData);
 116
 117         // cast to an instance of MyConcreteTLVParser:
 118         if (listIter->is<MyConcreteTLVParser>()) {
 119             MyConcreteTLVParser concreteTLVParser ( listIter->as<MyConcreteTLVParser>());
 120             concreteTLVParser.myValue() = 0xabababab;
 121         }
 122
 123         // add a MyConcreteTLV to the list:
 124         MyConcreteTLVParser tlv ( tlvContainer.push_back_space().init<MyConcreteTLVParser>());
 125         tlv.myValue() = 0xffff;
 126         \endcode
 127
 128         \see
 129             IPv6GenericOptionParser, WLANGenericInfoElementParser, MIHGenericTLVParser \n
 130             GenericTLVParserRegistry
 131      */
 132     template <class Base>
 133     class GenericTLVParserBase : public Base
 134     {
 135     public:
 136         GenericTLVParserBase(senf::PacketParserBase::data_iterator i, senf::PacketParserBase::state_type s)
 137             : Base(i,s) {}
 138
 139         senf::PacketParserBase::size_type bytes();
 140         void init() const;
 141
 142         template <class Parser>
 143         Parser init();
 144
 145         template <class Parser>
 146         Parser as() const;
 147
 148         template <class Parser>
 149         bool is() const;
 150
 151         senf::PacketInterpreterBase::range value() const;
 152
 153         void dump(std::ostream & os) const;
 154
 155 #ifndef DOXYGEN
 156         template<class ForwardReadableRange>
 157         void value(ForwardReadableRange const & val,
 158                 typename boost::disable_if<senf::is_pair<ForwardReadableRange> >::type * = 0);
 159
 160         template<class First, class Second>
 161         void value(std::pair<First, Second> const & val,
 162                 typename boost::disable_if<boost::is_convertible<First, typename Base::type_t::value_type> >::type * = 0);
 163
 164         template <class Type, class ForwardReadableRange>
 165         void value(std::pair<Type, ForwardReadableRange> const & val,
 166                 typename boost::enable_if<boost::is_convertible<Type, typename Base::type_t::value_type> >::type * = 0);
 167 #else
 168         template<class ForwardReadableRange>
 169         void value(ForwardReadableRange const & val);
 170
 171         template <class ForwardReadableRange>
 172         void value(std::pair<typename Base::type_t::value_type, ForwardReadableRange> const & val);
 173 #endif
 174
 175     private:
 176         template<class ForwardReadableRange>
 177         void value_(ForwardReadableRange const &range);
 178
 179         Base & self();
 180         Base const & self() const;
 181     };
 182
 183
 184     namespace detail {
 185         template <class BaseParser>
 186         struct GenericTLVParserRegistry_EntryBase {
 187             virtual void dump(GenericTLVParserBase<BaseParser> const & parser, std::ostream & os) const = 0;
 188         };
 189
 190         template <class BaseParser, class Parser>
 191         struct GenericTLVParserRegistry_Entry
 192             : GenericTLVParserRegistry_EntryBase<BaseParser>
 193         {
 194             virtual void dump(GenericTLVParserBase<BaseParser> const & parser, std::ostream & os) const;
 195         };
 196     }
 197
 198     /** \brief TLV parser registration facility
 199
 200         The %GenericTLVParserRegistry provides a generic facility to globally register concrete
 201         TLV parser by the type value. The concrete TLV parser must therefore provide a \c typeId
 202         member. See GenericTLVParserBase for details about the assumed class structure.
 203
 204         Every registry is identified by the base tlv parser class. Parsers can be registered
 205         statically only:
 206         \code
 207         GenericTLVParserRegistry<MyTLVParserBase>::RegistrationProxy<ConcreteTLVParser>
 208             registerConcreteTLVParser;
 209         \endcode
 210         This global variable declaration will register ConcreteTLVParser. The variable
 211         registerConcreteTLVParser is a dummy. It's only function is to force the call of
 212         it's constructor during global construction time. This static registration only
 213         works when the symbol is included into the final binary.
 214
 215         To simplify the registration the \ref SENF_PACKET_TLV_REGISTRY_REGISTER macro can be used.
 216         The \c ConreteTLVParser must therefore provide a \c Registry typedef pointing to the
 217         %GenericTLVParserRegistry; typically you put this typedef to the TLVBaseParser class.
 218         \code
 219         struct MyTLVParserBase : public senf::PacketParserBase
 220         {
 221             ...
 222             typedef GenericTLVParserRegistry<MyTLVParserBase> Registry;
 223         };
 224         struct MyConcreteTLVParser : public MyTLVParserBase
 225         {
 226             ....
 227             static const type_t::value_type typeId = 0x42;
 228             void dump(std::ostream & os) const;
 229         };
 230
 231         // register MyConcreteTLVParser to the MyTLVParserBase-Registry with the type id 0x42:
 232         SENF_PACKET_TLV_REGISTRY_REGISTER( MyConcreteTLVParser );
 233         \endcode
 234
 235         The registry provides a dump() member to dump an instance of a generic TLV parser.
 236         If the type value of the given TLV parser is registered the generic tlv will be
 237         casted to the registered concrete TLV parser and the dump member from this parser
 238         will be called. Otherwise the generic TLV parser will be dumped in a generic way
 239         (hexdump of the value).
 240
 241         \see
 242             GenericTLVParserBase for the general TLV class structure \n
 243             IPv6OptionParser::Registry, WLANInfoElementParser::Registry,
 244             MIHBaseTLVParser::Registry
 245      */
 246     template <class BaseParser>
 247     class GenericTLVParserRegistry
 248         : public senf::singleton<GenericTLVParserRegistry<BaseParser> >
 249     {
 250         typedef boost::ptr_map<
 251             typename BaseParser::type_t::value_type,
 252             detail::GenericTLVParserRegistry_EntryBase<BaseParser> > Map;
 253         Map map_;
 254
 255         GenericTLVParserRegistry() {};
 256     public:
 257         using senf::singleton<GenericTLVParserRegistry<BaseParser> >::instance;
 258         friend class senf::singleton<GenericTLVParserRegistry<BaseParser> >;
 259
 260         template <class PacketParser>
 261         struct RegistrationProxy {
 262             RegistrationProxy();
 263         };
 264
 265         template <typename Parser>
 266         void registerParser();
 267
 268         void dump(GenericTLVParserBase<BaseParser> const & parser, std::ostream & os) const;
 269     };
 270
 271     /** \brief Statically add an entry to a TLV parser registry
 272
 273         This macro will declare an anonymous global variable in such a way, that constructing
 274         this variable will register the given tlv parser.
 275
 276         \hideinitializer
 277         \see senf::GenericTLVParserRegistry
 278      */
 279 #   define SENF_PACKET_TLV_REGISTRY_REGISTER( ConreteTLVParser )                \
 280         namespace {                                                             \
 281             ConreteTLVParser::Registry::RegistrationProxy<ConreteTLVParser>     \
 282                     BOOST_PP_CAT(tlvparserRegistration_, __LINE__);             \
 283         }
 284
 285 }
 286
 287 ///////////////////////////////hh.e////////////////////////////////////////
 288 //#include "GenericTLV.cci"
 289 #include "GenericTLV.ct"
 290 #include "GenericTLV.cti"
 291 #endif
 292
 293 \f
 294 // Local Variables:
 295 // mode: c++
 296 // fill-column: 100
 297 // comment-column: 40
 298 // c-file-style: "senf"
 299 // indent-tabs-mode: nil
 300 // ispell-local-dictionary: "american"
 301 // compile-command: "scons -u test"
 302 // End: