4 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
5 // Kompetenzzentrum fuer NETwork research (NET)
6 // Stefan Bund <g0dil@berlios.de>
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.
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.
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.
24 \brief ParseVariant public header */
26 #ifndef HH_ParseVariant_
27 #define HH_ParseVariant_ 1
30 #error "Don't include 'ParseVariant.hh' directly, include 'Packets.hh'"
34 #include <boost/mpl/vector.hpp>
35 #include <boost/mpl/at.hpp>
36 #include <boost/preprocessor/repetition/enum_params_with_a_default.hpp>
37 #include <boost/preprocessor/repetition/enum_params.hpp>
38 #include <boost/preprocessor/seq/for_each.hpp>
39 #include "PacketParser.hh"
41 //#include "ParseVariant.mpp"
42 #include "ParseVariant.ih"
43 ///////////////////////////////hh.p////////////////////////////////////////
47 # ifndef SENF_LIMIT_PARSE_VARIANT
48 /** \brief Maximum number of senf::Parse_Variant sub-parsers.
50 This number defines the maximum number of parser arguments senf::Parse_Variant takes.
52 # define SENF_LIMIT_PARSE_VARIANT 6
55 /** \brief Variant parser
57 This is not really a collection parser (it does not provide a collection
58 interface). However, it is not a composite parser or value parser either.
60 A variant parser will parse any number of sub-parsers discriminated by an arbitrary, policy
61 defined condition. This is the parser to use, if the type and/or number of fields of a
62 packet change depending on some condition.
64 typedef senf::Parse_Variant<
66 senf::VoidPacketParser, Parse_TypeA, Parse_TypeB> MyVariant;
68 This typedef defines a variant parser choosing one of three sub
69 parsers. senf::VoidPacketParser is an empty parser, it effectively makes this parser
72 When creating a new packet containing a variant parser, the variant parser will always be
73 initialized to the first sub-parser.
76 ExampleVariantPolicy on how to implement the \a VariantPolicy \n
77 \ref SENF_PARSER_VARIANT() on how to integrate the parser into another parser
78 \ingroup parsecollection
80 template <class VariantPolicy, SENF_PARSE_VARIANT_TPL_ARGS_DFL(class P)>
82 : public PacketParserBase, private VariantPolicy
84 typedef boost::mpl::vector< SENF_PARSE_VARIANT_TPL_ARGS(P) > parsers;
87 ///\name Parser interface
90 Parse_Variant(data_iterator i, state_type s);
91 Parse_Variant(VariantPolicy policy, data_iterator i, state_type s);
93 size_type bytes() const;
96 static const size_type init_bytes =
97 senf::init_bytes<P0>::value + VariantPolicy::init_bytes;
100 ///////////////////////////////////////////////////////////////////////////
102 unsigned variant() const; ///< Get current variant
103 /**< Get the currently selected variant index. The returned
104 number directly indexes the list of sub parsers.
105 \returns Index of currently selected variant. Integer
106 in the range from 0 to (number-of-sub-parsers - 1)
109 template <unsigned N>
110 typename boost::mpl::at< parsers, boost::mpl::int_<N> >::type get() const;
111 ///< Access sub-parser
112 /**< This call will return the sub-parser at index \a
113 N. This call will fail, if the currently active
114 variant() is not \a N.
115 \pre variant() == \a N
116 \returns sub-parser at index \a N */
118 template <unsigned N>
119 void init(); ///< Re-initialize field
120 /**< This will reinitialize the field to the variant
121 sub-parser at index \a N changing the currently
123 \post variant() == \a N */
126 /** \brief Variant with direct, fixed distance type field
128 This struct is a template typedef defining a senf::Parser_Variant instantiation. It defines
129 a variant parser which interprets the value returned by some other parser directly as index
130 into the list of sub parsers (the numeric template argument to senf::Parse_Variant::get()
131 and senf::Parser_Variant::init()).
134 // Define a variant choosing between Parse_Foo and Parse_Bar depending on the directly
135 // preceding 1-byte 8bit uint value
136 typedef senf::Parse_Variant_Direct< senf::Parse_UInt8, 1u,
137 Parse_Foo, Parse_Bar >::parser MyVariant;
140 \a ChooserType defines the type of the field used to choose the sub parser. This must be a
141 fixed-size value parser. \a Distance gives the \e fixed distance of this field \e before the
142 currently defined field.
144 It is best to define a field of this type using \ref SENF_PARSER_VARIANT() or \ref
145 SENF_PARSER_PRIVATE_VARIANT().
147 \param[in] ChooserType type of chooser field (a value parser)
148 \param[in] Distance fixed distance of the chooser field before the current field
149 \param[in] P any number of sub parsers
151 \see senf::Parser_Variant
152 \ingroup parsecollection
154 template <class ChooserType, unsigned Distance, SENF_PARSE_VARIANT_TPL_ARGS_DFL(class P)>
155 struct Parse_Variant_Direct
157 typedef Parse_Variant< detail::Parse_Variant_Direct<ChooserType, Distance>,
158 SENF_PARSE_VARIANT_TPL_ARGS(P) > parser;
161 /** \brief Define Parse_Variant_Direct field
163 This macro is a special helper to define a senf::Parse_Variant_Direct type field. This is a
164 variant field which chooses the sub-type by directly taking the value of some other field.
166 This is a dynamically sized parser. Nevertheless, the chooser field \e must have a \e fixed
167 distance to this field, the \a chooser must be a fixed-size value parser.
170 struct SomeParser : public PacketParserBase
172 # include SENF_PARSER()
174 SENF_PARSER_PRIVATE_FIELD( type, senf::Parse_UInt8 );
175 SENF_PARSER_PRIVATE_VARIANT( content, type,
176 (senf::VoidPacketParser)
180 (senf::Parse_UInt32) );
182 senf::Parse_UInt8 uint8() const { return content().get<1>(); }
183 senf::Parse_UInt16 uint16() const { return content().get<2>(); }
184 senf::Parse_UInt24 uint24() const { return content().get<3>(); }
185 senf::Parse_UInt32 uint32() const { return content().get<4>(); }
187 void disable() const { content().init<0>(); }
188 void set_uint8() const { content().init<1>(); }
189 void set_uint16() const { content().init<2>(); }
190 void set_uint24) const { content().init<3>(); }
191 void set_uint23() const { content().init<4>(); }
193 SENF_PARSER_FINALIZE(SomeParser);
197 The variant \c content chooses one of the sub parsers depending on the \c type field. If \c
198 type is 0, senf::VoidPacketParser is selected, if it is 1, senf::Parse_UInt8 and so on.
200 It is customary, to hide the variant parser (by defining it private) and provide more
201 conveniently named accessors.
203 \param[in] name name of the field
204 \param[in] chooser name of the field choosing the variant to use
205 \param[in] types a Boost.Preprocessor style sequence of sub-parser types
208 senf::Parse_Variant \n
209 \ref SENF_PARSER_PRIVATE_VARIANT()
211 \ingroup packetparsermacros
213 # define SENF_PARSER_VARIANT(name, chooser, types) \
214 SENF_PARSER_VARIANT_I(SENF_PARSER_FIELD, name, chooser, types)
216 /** \brief Define Parse_Variant_Direct field (private)
218 \see \ref SENF_PARSER_VARIANT()
220 \ingroup packetparsermacros
222 # define SENF_PARSER_PRIVATE_VARIANT(name, chooser, types) \
223 SENF_PARSER_VARIANT_I(SENF_PARSER_PRIVATE_FIELD, name, chooser, types)
227 ///////////////////////////////hh.e////////////////////////////////////////
229 #if !defined(HH_Packets__decls_) && !defined(HH_ParseVariant_i_)
230 #define HH_ParseVariant_i_
231 //#include "ParseVariant.cci"
232 #include "ParseVariant.ct"
233 #include "ParseVariant.cti"
240 // comment-column: 40
241 // c-file-style: "senf"
242 // indent-tabs-mode: nil
243 // ispell-local-dictionary: "american"
244 // compile-command: "scons -u test"