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() const;
 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             virtual PacketParserBase::size_type bytes(GenericTLVParserBase<BaseParser> const & parser) const = 0;
 189         };
 190
 191         template <class BaseParser, class Parser>
 192         struct GenericTLVParserRegistry_Entry
 193             : GenericTLVParserRegistry_EntryBase<BaseParser>
 194         {
 195             virtual void dump(GenericTLVParserBase<BaseParser> const & parser, std::ostream & os) const;
 196             virtual PacketParserBase::size_type bytes(GenericTLVParserBase<BaseParser> const & parser) const;
 197         };
 198
 199         //Helper Functor for STL-compatible predicate (E.g. find_if, for_each ...)
 200         template <class BaseParser, class Parser>
 201         class Predicate
 202         {
 203             public:
 204                 bool operator() (BaseParser const &p) const {
 205                     return p.template is<Parser>();
 206                 }
 207         };
 208     }
 209
 210     /** \brief TLV parser registration facility
 211
 212         The %GenericTLVParserRegistry provides a generic facility to globally register concrete
 213         TLV parser by the type value. The concrete TLV parser must therefore provide a \c typeId
 214         member. See GenericTLVParserBase for details about the assumed class structure.
 215
 216         Every registry is identified by the base tlv parser class. Parsers can be registered
 217         statically only:
 218         \code
 219         GenericTLVParserRegistry<MyTLVParserBase>::RegistrationProxy<ConcreteTLVParser>
 220             registerConcreteTLVParser;
 221         \endcode
 222         This global variable declaration will register ConcreteTLVParser. The variable
 223         registerConcreteTLVParser is a dummy. It's only function is to force the call of
 224         it's constructor during global construction time. This static registration only
 225         works when the symbol is included into the final binary.
 226
 227         To simplify the registration the \ref SENF_PACKET_TLV_REGISTRY_REGISTER macro can be used.
 228         The \c ConreteTLVParser must therefore provide a \c Registry typedef pointing to the
 229         %GenericTLVParserRegistry; typically you put this typedef to the TLVBaseParser class.
 230         \code
 231         struct MyTLVParserBase : public senf::PacketParserBase
 232         {
 233             ...
 234             typedef GenericTLVParserRegistry<MyTLVParserBase> Registry;
 235         };
 236         struct MyConcreteTLVParser : public MyTLVParserBase
 237         {
 238             ....
 239             static const type_t::value_type typeId = 0x42;
 240             void dump(std::ostream & os) const;
 241         };
 242
 243         // register MyConcreteTLVParser to the MyTLVParserBase-Registry with the type id 0x42:
 244         SENF_PACKET_TLV_REGISTRY_REGISTER( MyConcreteTLVParser );
 245         \endcode
 246
 247         The registry provides a dump() member to dump an instance of a generic TLV parser.
 248         If the type value of the given TLV parser is registered the generic tlv will be
 249         casted to the registered concrete TLV parser and the dump member from this parser
 250         will be called.
 251
 252         \see
 253             GenericTLVParserBase for the general TLV class structure \n
 254             IPv6OptionParser::Registry, WLANInfoElementParser::Registry,
 255             MIHBaseTLVParser::Registry
 256      */
 257     template <class BaseParser, class Keytype = typename BaseParser::type_t::value_type>
 258     class GenericTLVParserRegistry
 259         : public senf::singleton<GenericTLVParserRegistry<BaseParser,Keytype> >
 260     {
 261         typedef boost::ptr_map<Keytype,
 262             detail::GenericTLVParserRegistry_EntryBase<BaseParser> > Map;
 263         Map map_;
 264
 265         GenericTLVParserRegistry() {};
 266     public:
 267         using senf::singleton<GenericTLVParserRegistry<BaseParser,Keytype> >::instance;
 268         friend class senf::singleton<GenericTLVParserRegistry<BaseParser,Keytype> >;
 269
 270         template <class PacketParser>
 271         struct RegistrationProxy {
 272             RegistrationProxy();
 273         };
 274
 275         template <typename Parser>
 276         void registerParser();
 277
 278         typedef GenericTLVParserBase<BaseParser> GenericTLVParser;
 279
 280         bool isRegistered(GenericTLVParserBase<BaseParser> const & parser) const;
 281         bool isRegistered(Keytype const & key) const;
 282
 283         void dump(GenericTLVParser const & parser, std::ostream & os) const;
 284         void dump(GenericTLVParser const & parser, Keytype const & key, std::ostream & os) const;
 285
 286         PacketParserBase::size_type bytes(GenericTLVParser const & parser) const;
 287         PacketParserBase::size_type bytes(GenericTLVParser const & parser, Keytype const & key) const;
 288     };
 289
 290     struct TLVParserNotRegisteredException : public senf::Exception
 291     {
 292         TLVParserNotRegisteredException() : senf::Exception("tlv parser not registered") {}
 293     };
 294
 295
 296     /** \brief Statically add an entry to a TLV parser registry
 297
 298         This macro will declare an anonymous global variable in such a way, that constructing
 299         this variable will register the given tlv parser.
 300
 301         \hideinitializer
 302         \see senf::GenericTLVParserRegistry
 303      */
 304 #   define SENF_PACKET_TLV_REGISTRY_REGISTER( ConreteTLVParser )                \
 305         namespace {                                                             \
 306             ConreteTLVParser::Registry::RegistrationProxy<ConreteTLVParser>     \
 307                     BOOST_PP_CAT(tlvparserRegistration_, __LINE__);             \
 308         }
 309
 310 }
 311
 312 ///////////////////////////////hh.e////////////////////////////////////////
 313 //#include "GenericTLV.cci"
 314 #include "GenericTLV.ct"
 315 #include "GenericTLV.cti"
 316 #endif
 317
 318 \f
 319 // Local Variables:
 320 // mode: c++
 321 // fill-column: 100
 322 // comment-column: 40
 323 // c-file-style: "senf"
 324 // indent-tabs-mode: nil
 325 // ispell-local-dictionary: "american"
 326 // compile-command: "scons -u test"
 327 // End: