senf/Packets/80221Bundle/TLVPacket.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   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 TLVPacket public header */
  25
  26 #ifndef HH_SENF_Packets_80221Bundle_TLVPacket_
  27 #define HH_SENF_Packets_80221Bundle_TLVPacket_ 1
  28
  29 // Custom includes
  30 #include <algorithm>
  31 #include "../../Packets/Packets.hh"
  32
  33 //#include "TLVPacket.mpp"
  34 ///////////////////////////////hh.p////////////////////////////////////////
  35
  36 namespace senf {
  37
  38     struct TLVLengthException : public senf::Exception
  39     {
  40         TLVLengthException()
  41           : senf::Exception("TLVLengthException") {}
  42     };
  43
  44
  45     class DynamicTLVLengthParser
  46         : public detail::packet::IntParserOps<DynamicTLVLengthParser, boost::uint32_t>,
  47           public PacketParserBase
  48     {
  49     public:
  50         DynamicTLVLengthParser(data_iterator i, state_type s) : PacketParserBase(i,s) {}
  51
  52         typedef boost::uint32_t value_type;
  53         static const size_type init_bytes = 1;
  54         static value_type const min_value = 0;
  55         static value_type const max_value = 4294967295u;
  56
  57         value_type value() const;
  58         void value(value_type const & v);
  59
  60         DynamicTLVLengthParser const & operator= (value_type other);
  61         size_type bytes() const;
  62         void init() const;
  63
  64 #       include SENF_PARSER()
  65         SENF_PARSER_PRIVATE_FIELD ( length_field, UInt8Parser );
  66         SENF_PARSER_GOTO( length_field );
  67         SENF_PARSER_PRIVATE_BITFIELD ( extended_length_flag, 1,  bool     );
  68         SENF_PARSER_PRIVATE_BITFIELD ( underflow_flag,       1,  bool     );
  69         SENF_PARSER_PRIVATE_BITFIELD ( fixed_length_field,   6,  unsigned );
  70
  71         void finalize();
  72         void maxValue(value_type v);
  73         value_type maxValue() const;
  74     private:
  75         void resize(size_type size);
  76     };
  77
  78
  79     /** \brief Base class for TLV-Packet-Parsers
  80
  81          BaseTLVPacketParser is the abstract base class for TLV-Packet-Parsers. It defines the
  82          \ref type() field as an \ref senf::UInt8Parser and the \ref length() field as a
  83          DynamicTLVLengthParser. The length field is read-only.
  84
  85          To create your own \c TLVParser you have to inherit from BaseTLVPacketParser (don't
  86          forget \ref SENF_PARSER_INHERIT) and define the \c value field. In the following example
  87          the value is a vector of MacAddresses:
  88          \code
  89          struct MacAddressesTLVParser : public BaseTLVPacketParser {
  90          #   include SENF_PARSER()
  91              SENF_PARSER_INHERIT ( BaseTLVPacketParser );
  92              SENF_PARSER_VECTOR  ( value, bytes(length), senf::MACAddressParser );
  93              SENF_PARSER_FINALIZE( MacAddressesTLVParser );
  94          };
  95
  96          struct MacAddressesTLVPacketType : public PacketTypeBase {
  97             typedef MacAddressesTLVParser parser;
  98             ...
  99             static void finalize(ConcretePacket<MacAddressesTLVPacketType> p) {
 100                 p->shrinkLength();
 101             }
 102          };
 103          \endcode
 104
 105          You have to adjust the maximum length value with the \ref maxLengthValue function
 106          before the length value is set. The default maximum value is 127. So, in the above
 107          example adding more than 21 MACAddresses to the vector will throw a TLVLengthException
 108          if you don't call \c macAddressesTLVPacket->maxLengthValue( \e some_value) before.
 109
 110          \see DynamicTLVLengthParser \n
 111            GenericTLVPacketParser \n
 112      */
 113     class BaseTLVPacketParser : public PacketParserBase
 114     {
 115     public:
 116 #       include SENF_PARSER()
 117         SENF_PARSER_FIELD    ( type,   UInt8Parser            );
 118         SENF_PARSER_FIELD_RO ( length, DynamicTLVLengthParser );
 119         SENF_PARSER_FINALIZE ( BaseTLVPacketParser            );
 120
 121         /** \brief set maximum value of length field
 122
 123             The size of the length field will be increased if necessary.
 124             \param v maximum value of length field
 125          */
 126         void maxLengthValue(DynamicTLVLengthParser::value_type v) const {
 127             length_().maxValue(v);
 128         }
 129
 130         /** \brief shrink size of length field to minimum
 131
 132             The size of the length field will be decreased to minimum necessary to hold
 133             the current length value.
 134          */
 135         void finalizeLength() {
 136             length_().finalize();
 137         };
 138
 139     protected:
 140         /// return size of length field
 141         size_type length_bytes() const { return length_().bytes(); };
 142         /// set length field to given value
 143         void length(DynamicTLVLengthParser::value_type &v) { length_() = v; };
 144         /// resize the Packet after the length field to given size
 145         senf::safe_data_iterator resizeValueField(DynamicTLVLengthParser::value_type size);
 146     };
 147
 148
 149     /** \brief Parser for a generic TLV packet
 150
 151         \see GenericTLVPacketType
 152      */
 153     struct GenericTLVPacketParser : public BaseTLVPacketParser
 154     {
 155 #       include SENF_PARSER()
 156         SENF_PARSER_INHERIT  ( BaseTLVPacketParser    );
 157         SENF_PARSER_SKIP     ( length(), 0            );
 158         SENF_PARSER_FINALIZE ( GenericTLVPacketParser );
 159
 160         SENF_PARSER_INIT() {
 161             maxLengthValue( DynamicTLVLengthParser::max_value);
 162         }
 163
 164         senf::PacketInterpreterBase::range value() const;
 165
 166         template <class ForwardReadableRange>
 167         void value(ForwardReadableRange const &range);
 168     };
 169
 170     /** \brief Generic TLV packet
 171
 172         \par Packet type (typedef):
 173             \ref GenericTLVPacket
 174
 175         \image html TLV.png
 176
 177         \ingroup protocolbundle_80221
 178      */
 179     struct GenericTLVPacketType
 180         : public PacketTypeBase,
 181           public PacketTypeMixin<GenericTLVPacketType>
 182     {
 183 #ifndef DOXYGEN
 184         typedef PacketTypeMixin<GenericTLVPacketType> mixin;
 185 #endif
 186         typedef ConcretePacket<GenericTLVPacketType> packet; ///< GenericTLV packet typedef
 187         typedef GenericTLVPacketParser parser;               ///< typedef to the parser of GenericTLV packet
 188
 189         using mixin::nextPacketRange;
 190         using mixin::init;
 191         using mixin::initSize;
 192
 193         /** \brief Dump given GenericTLVPacket in readable form to given output stream */
 194         static void dump(packet p, std::ostream & os);
 195         static void finalize(packet p);  ///< Finalize packet.
 196                                          /**< shrink size of length field to minimum
 197                                               \see BaseTLVPacketParser::shrinkLength() */
 198
 199     };
 200
 201     /** \brief GenericTLV packet typedef */
 202     typedef ConcretePacket<GenericTLVPacketType> GenericTLVPacket;
 203 }
 204
 205
 206 ///////////////////////////////hh.e////////////////////////////////////////
 207 #include "TLVPacket.cci"
 208 #include "TLVPacket.ct"
 209 //#include "TLVPacket.cti"
 210 #endif
 211
 212 \f
 213 // Local Variables:
 214 // mode: c++
 215 // fill-column: 100
 216 // c-file-style: "senf"
 217 // indent-tabs-mode: nil
 218 // ispell-local-dictionary: "american"
 219 // compile-command: "scons -u test"
 220 // comment-column: 40
 221 // End: