Add #ifndef DOXYGEN directives to hide boost::enable/disable_if constructs from doxygen
[senf.git] / Packets / PacketParser.hh
1 // Copyright (C) 2007 
2 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
3 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
4 //     Stefan Bund <g0dil@berlios.be>
5 //
6 // This program is free software; you can redistribute it and/or modify
7 // it under the terms of the GNU General Public License as published by
8 // the Free Software Foundation; either version 2 of the License, or
9 // (at your option) any later version.
10 //
11 // This program is distributed in the hope that it will be useful,
12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14 // GNU General Public License for more details.
15 //
16 // You should have received a copy of the GNU General Public License
17 // along with this program; if not, write to the
18 // Free Software Foundation, Inc.,
19 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
20
21 /** \file
22     \brief PacketParser public header */
23
24 /** \defgroup packetparser The PacketParser facility
25     
26     The PacketParser facility provides a framework to implement very lightweight classes which parse
27     the raw content of a packet into meaningful values. PacketParsers are always passed around
28     <em>by value</em>, they can be understood as pointers into the packet data with added type
29     information providing parsing functions.
30
31     Parsers are built hierarchically. A high-level parser will return other parsers when accessing
32     an element (Example: Asking an EthernetParser for the ethertype field by calling the parsers \c
33     type() member will return an \c UInt16 parser). The lowest level building blocks then return the
34     values. This hierarchical structure greatly simplifies building complex parsers.
35
36     Since parsers are very lightweight and are passed by value, packet fields are accessed using the
37     corresponding accessor method:
38     \code
39       SomePacket p (...)
40       SomePacket q (...)
41
42       // Assign new value to an integer parser
43       p->someField() = 10;
44
45       // Write out above value
46       std::cerr << p->someField() << "\n";
47
48       // Use the generic parser-assignment operator '<<' to copy field values
49       p->someVector()[1].someOtherField() << q->someField();
50       p->someVector() << q->someVector()
51     \endcode
52
53     Here \c someField(), \c someOtherField() and \c someVector() are accessor methods named after
54     the field name. Each returns a parser object. Simple parsers can be used like their
55     corresponding basic type (e.g. a Parse_UInt16 field can be used like an unsigned integer), more
56     complex parsers provide type specific access members. Assigning a value to a parser will change
57     the underlying representation (the packet data). 
58
59     More complex parsers (especially those representing a collection of values) provide an
60     additional wrapper class for mutating access (e.g. Parse_Vector provides a container wrapper
61     with am STL compatible random-access sequence interface). See the documentation of the specific
62     parser for the wrapper specification.
63
64     Every parser is derived from senf::PacketParserBase. This class provides the necessary
65     housekeeping information and provides the parsers with access to the data.
66
67     \warning Parsers are like iterators: They are invalidated <em>whenever the size of the packet's
68     data is changed</em>. You should not store a parser anywhere. If you want to keep a parser
69     reference, use the senf::SafePacketParser wrapper. You still will need to take extra care to
70     ensure the parser is not invalidated.
71  */
72
73 #ifndef HH_PacketParser_
74 #define HH_PacketParser_ 1
75
76 // Custom includes
77 #include <boost/utility/enable_if.hpp>
78 #include <boost/type_traits.hpp>
79 #include <boost/optional.hpp>
80 #include "Utils/SafeBool.hh"
81 #include "PacketTypes.hh"
82 #include "PacketData.hh"
83
84 #include "PacketParser.mpp"
85 ///////////////////////////////hh.p////////////////////////////////////////
86
87 namespace senf {
88     
89     /** \brief Parser Base class
90
91         Parsers come in two favors: fixed and dynamically sized parsers. A <em>fixed size
92         parser</em> has a constant size, it will always parse a fixed number of bytes. The low-level
93         'final'  parsers (like the integer parsers) are fixed size parsers as are composite parsers
94         built up only of fixed-size fields.
95
96         A <em>dynamically sized</em> parser on the other hand infers it's size from the contents of
97         the data parsed. Any parser containing at least one dynamically sized sub-parser will itself
98         be dynamically sized.
99         
100         Both kinds of parser need to derive from PacketParserBase and implement several required
101         members. Which members to implement depends on the parsers flavor. There are two ways how to
102         do this.
103         \li If the parser just consists of a simple sequence of consecutive fields (sub-parsers),
104             the \ref SENF_PACKET_PARSER_DEFINE_FIELDS and \ref
105             SENF_PACKET_PARSER_DEFINE_FIXED_FIELDS macros provide a simple and convenient way to
106             define the packet
107         \li In more complex cases, you need to implement the necessary members manually.
108
109         This documentation is about the manual implementation. You should nevertheless read through
110         this to understand, what above macros are doing.
111
112         The following example documents the interface (which must be) provided by a parser:
113         \code
114           struct FooParser : public PacketParserBase
115           {
116               FooParser(data_iterator i, state_type s) : PacketParserBase(i,s) {}
117
118               // If this parser has a fixed size, you must define this size here This definition
119               // allows the parser to be used within the list, vector and array parsers static
120               static const size_type fixed_bytes = some_constant_size;
121
122               // If the parser does not have a fixed size, you must implement the bytes() member to
123               // return the size. ONLY EVER DEFINE ONE OF fixed_bytes OR bytes().
124               size_type bytes() const;
125
126               // If you define bytes(), you also need to define the init_bytes. This is the number
127               // of bytes to allocate when creating a new object
128               static const size_type init_bytes = some_constant_size;
129
130               // You also may define an init() member. This will be called to initialize a newly
131               // created data object. The default implementation just does nothing.
132               void init() const;
133
134               // ////////////////////////////////////////////////////////////////////////
135
136               // Add here members returning (sub-)parsers for the fields. The 'parse' member is 
137               // used to construct the sub-parsers. This member either takes an iterator to the
138               // data to be parsed or just an offset in bytes.
139
140               senf::Parse_UInt16 type() const { return parse<Parse_UInt16>( 0 ); }
141               senf::Parse_UInt16 size() const { return parse<Parse_UInt16>( 2 ); }
142           };
143         \endcode
144         
145         You should never call the \c bytes() member of a parser directly. Instead you should use the
146         freestanding senf::bytes() function. This function will return the correct size irrespective
147         of the parsers flavor. You may access \c fixed_bytes directly, however be aware that this
148         will restrict your code to fixed size parsers (which depending on the circumstances may be
149         exactly what you want).
150
151         In the same way, don't access \c init_bytes directly, always use the senf::init_bytes
152         meta-function class which correctly supports fixed size parsers.
153
154         \ingroup packetparser
155       */
156     class PacketParserBase
157     {
158     public:
159         ///////////////////////////////////////////////////////////////////////////
160         // Types
161
162         typedef detail::packet::iterator data_iterator; ///< Raw data iterator type
163         typedef detail::packet::size_type size_type; ///< Unsigned integral type
164         typedef detail::packet::difference_type difference_type; ///< Signed integral type
165         typedef detail::packet::byte byte; ///< Unsigned 8bit value, the raw value type
166         typedef PacketData * state_type; ///< Type of the 'state' parameter
167
168         ///////////////////////////////////////////////////////////////////////////
169         ///\name Structors and default members
170         ///@{
171
172         // no default constructor
173         // default copy
174         // default destructor
175         // no conversion constructors
176
177         ///@}
178         ///////////////////////////////////////////////////////////////////////////
179
180         data_iterator i() const;        ///< Return beginning of data to parse
181                                         /**< The parser is expected to interpret the data beginning
182                                              here. The size of the interpreted is given by
183                                              <tt>senf::bytes(</tt><em>parser
184                                              instance</em><tt>)</tt>. */
185         state_type state() const;       ///< Return state of this parser
186                                         /**< The value returned should be interpreted as an opaque
187                                              value provided just to be forwarded to other
188                                              parsers. */
189         PacketData & data() const;      ///< Access the packets raw data container
190                                         /**< This member will return the raw data container holding
191                                              the data which is parsed by \c this parser. */
192
193         void init() const;              ///< Default implementation
194                                         /**< This is just an empty default
195                                              implementation. Re-implement this member in your own
196                                              parsers if needed. */
197
198     protected:
199         PacketParserBase(data_iterator i, state_type s); ///< Standard constructor
200                                         /**< This is the constructor used by most parsers. The
201                                              parameters are just forwarded from the derived classes
202                                              constructor parameters. */
203         PacketParserBase(data_iterator i, state_type s, size_type size); 
204                                         ///< Size checking constructor
205                                         /**< In addition to the standard constructor, this
206                                              constructor will validate, that there is enough data in
207                                              the raw data container to parse \a size bytes after \a
208                                              i.
209
210                                              This constructor is called by all 'final' parsers
211                                              (e.g. the integer parsers) and \e only by those
212                                              parsers. Most parsers do \e not check the validity of
213                                              the iterator, this is delayed until the very last
214                                              parser. This allows to partial parse truncated
215                                              packets.
216
217                                              \throw TruncatedPacketException if the raw data
218                                                  container does not hold at least \a size bytes
219                                                  beginning at \a i. */
220
221         bool check(size_type size);     ///< Check size of data container
222                                         /**< \returns \c true, if the data container holds at least
223                                              \a size beginning at i(), \c false otherwise. */
224         void validate(size_type size);  ///< Validate size of data container
225                                         /**< \throws TruncatedPacketException if the raw data
226                                              container does not hold at least \a size bytes
227                                              beginning at i(). */
228
229         template <class Parser> Parser parse(data_iterator i) const; ///< Create sub-parser
230                                         /**< Creates a new instance of \a Parser to parse data
231                                              beginning at \a i. Automatically passes \a state() to
232                                              the new parser. */
233         template <class Parser> Parser parse(size_type n) const; ///< Create sub-parser
234                                         /**< Creates a new instance of \a Parser to parse data
235                                          * beginning at i()<tt> + </tt>\a n. Automatically passes \a
236                                              state() to the new parser. */
237
238         void defaultInit() const;       ///< Default implementation
239                                         /**< This is just an empty default
240                                              implementation. Re-implement this member in your own
241                                              parsers if needed. */
242
243     private:
244         data_iterator end();
245
246         data_iterator i_;
247         PacketData * data_;
248
249         template <class Parser> friend class SafePacketParser;
250     };
251
252     /** \brief Return raw size parsed by the given parser object
253         
254         This function will either call <tt>p.bytes()</tt> or return <tt>Parser::fixed_bytes</tt>
255         depending on the type of parser.
256
257         The value returned does \e not take into account the amount of data actually available. So
258         you always need to validate this value against the packet size if you directly access the
259         data. The standard low-level parses all do this check automatically to guard against
260         malformed packets.
261
262         \param[in] p Parser object to check
263         \returns number of bytes this parser expects to parser
264         \ingroup packetparser
265      */
266     template <class Parser>
267     PacketParserBase::size_type bytes(Parser p);
268     
269     namespace detail { template <class Parser> class ParserInitBytes; }
270
271     /** \brief Return number of bytes to allocate to new object of given type
272
273         This meta-function is called like
274         \code
275             senf::init_bytes<SomeParser>::value
276         \endcode
277
278         This expression evaluates to a compile-time constant integral expression of type
279         senf::PacketParserBase::size_type. This meta-function will return \c Parser::fixed_bytes or
280         \c Parser::init_bytes depending on the type of parser.
281
282         \param[in] Parser The Parser to return init_bytes for
283         \returns Number of bytes to allocate to the new object
284         \ingroup packetparser
285      */
286     template <class Parser>
287     struct init_bytes : public detail::ParserInitBytes<Parser>
288     {};
289
290     /** \brief Generic parser copying
291
292         This operator allows to copy the values of identical parsers. This operation does \e not
293         depend on the parsers detailed implementation, it will just replace the data bytes of the
294         target parser with those from the source parser. This allows to easily copy around complex
295         packet substructures.
296
297         This operation is different from the ordinary assignment operator: It does not change the \a
298         target parser, it changes the data referenced by the \a target parser.
299
300         \ingroup packetparser
301      */
302 #   ifndef DOXYGEN
303     template <class Parser>
304     typename boost::enable_if< 
305         boost::is_base_of<PacketParserBase, Parser>,
306         Parser >::type
307     operator<<(Parser target, Parser source);
308 #   else
309     template <class Parser>
310     Parser operator<<(Parser target, Parser source);
311 #   endif
312
313     /** \brief Generic parser value assignment
314
315         This operator allows to assign a value to parsers which implement a <tt>value(</tt>\a
316         value<tt>)</tt> member. This operator allows to use a common syntax for assigning values or
317         parsers to a parser. 
318
319         \ingroup packetparser
320      */
321     template <class Parser, class Value>
322     typename boost::enable_if_c < 
323         boost::is_base_of<PacketParserBase, Parser>::value 
324             && ! boost::is_base_of<PacketParserBase, Value>::value,
325         Parser >::type
326     operator<<(Parser target, Value const & value);
327
328     /** \defgroup packetparsermacros Helper macros for defining new packet parsers
329         
330         To simplify the definition of simple packet parsers, several macros are provided. Before
331         using these macros you should familiarize yourself with the packet parser interface as
332         described in senf::PacketParserBase.
333
334         These macros simplify providing the above defined interface. A typical packet declaration
335         using these macros has the following form (This is a concrete example from the definition of
336         the ethernet packet in <tt>DefaultBundle/EthernetPacket.hh</tt>)
337     
338         \dontinclude EthernetPacket.hh
339         \skipline struct Parse_EthVLan : public PacketParserBase
340         \until };
341
342         The macros take care of the following:
343         \li They define the accessor functions returning parsers of the given type.
344         \li They automatically calculate the offset of the fields from the preceding fields.
345         \li The macros provide a definition for \c init() 
346         \li The macros define the \c bytes(), \c fixed_bytes and \c init_bytes members as needed.
347
348         You may define either a fixed or a dynamically sized parser. Fixed size parsers are defined
349         using \ref SENF_PACKET_PARSER_DEFINE_FIXED_FIELDS, dynamically sized parsers are defined
350         using \ref SENF_PACKET_PARSER_DEFINE_FIELDS. The different members are implemented such
351         that:
352         
353         \li The needed parser constructor is defined
354         \li \c init() calls \c defaultInit(). \c defaultInit() is defined to call \c init() on each
355             of the fields.
356         \li \c bytes() (on dynamically sized parser) respectively \c fixed_bytes (on fixed size
357             parsers) is defined to return the sum of the sizes of all fields.
358         \li On dynamically sized parsers, \c init_bytes is defined to return the sum of the
359             \c init_size's of all fields
360
361         The central definition macros are \ref SENF_PACKET_PARSER_DEFINE_FIXED_FIELDS and \ref
362         SENF_PACKET_PARSER_DEFINE_FIELDS. The argument to both has the same structure. It is a
363         (boost preprocessor style) sequence of field definitions where each field definition
364         provides the builder macro to use and the name and type of the field to define:
365         \code
366           SENF_PACKET_PARSER_DEFINE[_FIXED]_FIELDS(
367               (( <builder> )( <name>, <type> ))
368               ...
369           )
370         \endcode
371         
372         For each field, this command will define
373         \li A method \a name() returning an instance of the \a type parser
374         \li \a name<tt>_t</tt> as a typedef for \a type, the fields value
375         \li \a name<tt>_offset</tt> to give the offset of the field from the beginning of the
376             parser. If the parser is a fixed size parser, this will be a static constant, otherwise
377             it will be a method.
378
379         The \a builder argument selects, how the field is defined
380         \li <tt>Field</tt> defines a field and increments the current position by the size of the
381             field
382         \li <tt>OverlayField</tt> defines a field like <tt>Field</tt> but does \e not increment the
383             position. In the above example, this is used to overlay the different bitfield parsers:
384             All overlaying bitfield parser except the last one (the one with the highest bit
385             numbers) is marked as OverlayField.
386
387         The \a name argument defines the name of the accessor method.
388
389         The \a type argument is the parser to return for that field. Since none of the arguments may
390         contain a comma, <em>This argument cannot be a multi-parameter template</em>. Always use
391         typedefs to access templated parsers as shown above.
392
393         The \ref SENF_PACKET_PARSER_INIT macro defines the constructor and the \c init() member. If
394         you want to provide your own \c init() implementation, use \ref
395         SENF_PACKET_PARSER_NO_INIT. The first statement in your init method should probably to call
396         \c defaultInit(). This will call the \c init() member of all the fields. Afterwards you can
397         set up the field values as needed:
398         \code
399           struct SomePacket : public senf::PacketParserBase
400           {
401               SENF_PACKET_PARSER_NO_INIT(SomePacket);
402         
403               typedef senf::Parse_UInt8 Parse_Type;
404               typedef senf::Parse_Vector< senf::Parse_UInt32,
405                                           senf::SimpleVectorSizer<senf::Parse_UInt16>
406                                         > Parse_Elements;
407
408               SENF_PACKET_PARSER_DEFINE_FIELDS(
409                   ((Field)( type,     Parse_Type     ))
410                   ((Field)( elements, Parse_Elements ))
411               );
412
413               void init() const {
414                   defaultInit();
415                   type() = 0x01;
416                   elements().push_back(0x01020304u);
417               }
418           }
419         \endcode
420         
421         \ingroup packetparser
422      */
423
424     /** \brief Define initialization members of a parser
425         
426         This macro defines the packet parser constructor and the \c init() member. \c init() is
427         defined to just call \c defaultInit() which is defined by the other macros to call \c init()
428         on each of the parsers fields.
429
430         \ingroup packetparsermacros
431         \hideinitializer
432      */
433 #   define SENF_PACKET_PARSER_INIT(name)                                                          \
434     name(data_iterator i, state_type s) : senf::PacketParserBase(i,s) {}                          \
435     void init() const { defaultInit(); }
436
437     /** \brief Define initialization members of a parser except init()
438         
439         This macro is like SENF_PACKET_PARSER_INIT but does \e not define \c init(). This allows you
440         to provide your own implementation. You should call \c defaultInit() first before
441         initializing your data fields.
442
443         \ingroup packetparsermacros
444         \hideinitializer
445      */
446 #   define SENF_PACKET_PARSER_NO_INIT(name)                                                       \
447     name(data_iterator i, state_type s) : senf::PacketParserBase(i,s) {}
448
449     /** \brief Define fields for a dynamically sized parser
450
451         Define the fields as specified in \a fields. This macro supports dynamically sized
452         subfields, the resulting parser will be dynamically sized.
453
454         \ingroup packetparsermacros
455         \hideinitializer
456      */
457 #   define SENF_PACKET_PARSER_DEFINE_FIELDS(fields)                                               \
458     SENF_PACKET_PARSER_I_DEFINE_FIELDS(0,fields)
459         
460     /** \brief Define fields for a dynamically sized parser (with offset)
461
462         Define the fields as specified in \a fields. This macro supports dynamically sized
463         subfields, the resulting parser will be dynamically sized.
464
465         The \a offset argument gives the byte offset at which to start parsing the fields. This
466         helps defining extended parser deriving from a base parser:
467         \code
468            struct ExtendedParser : public BaseParser
469            {
470                ExtendedParser(data_iterator i, state_type s) : BaseParser(i,s) {}
471         
472                SENF_PACKET_PARSER_DEFINE_FIELDS_OFFSET(senf::bytes(BaseParser(*this)),
473                  ( ... fields ... ) );
474
475                void init() {
476                    BaseParser::init();
477                    defaultInit();
478                    // other init code
479                }
480            }
481         \endcode
482
483         \ingroup packetparsermacros
484         \hideinitializer
485      */
486 #   define SENF_PACKET_PARSER_DEFINE_FIELDS_OFFSET(offset,fields)                                 \
487     SENF_PACKET_PARSER_I_DEFINE_FIELDS(offset,fields)
488
489     /** \brief Define fields for a fixed size parser
490
491         Define the fields as specified in \a fields. This macro only supports fixed size
492         subfields, the resulting parser will also be a fixed size parser.
493
494         \ingroup packetparsermacros
495         \hideinitializer
496      */
497 #   define SENF_PACKET_PARSER_DEFINE_FIXED_FIELDS(fields)                                         \
498     SENF_PACKET_PARSER_I_DEFINE_FIXED_FIELDS(0,fields)
499
500     /** \brief Define fields for a fixed size parser
501
502         Define the fields as specified in \a fields. This macro only supports fixed size
503         subfields, the resulting parser will also be a fixed size parser.
504
505         The \a offset argument gives the byte offset at which to start parsing the fields. This
506         helps defining extended parser deriving from a base parser:
507         \code
508            struct ExtendedParser : public BaseParser
509            {
510                ExtendedParser(data_iterator i, state_type s) : BaseParser(i,s) {}
511
512                SENF_PACKET_PARSER_DEFINE_FIXED_FIELDS_OFFSET(BaseParser::fixed_bytes,
513                  ( ... fields ... ) );
514
515                void init() {
516                    BaseParser::init();
517                    defaultInit();
518                    // other init code
519                }
520            }
521         \endcode
522
523         \ingroup packetparsermacros
524         \hideinitializer
525      */
526 #   define SENF_PACKET_PARSER_DEFINE_FIXED_FIELDS_OFFSET(offset,fields)                           \
527     SENF_PACKET_PARSER_I_DEFINE_FIXED_FIELDS(offset,fields)
528
529     /** \brief Default parser parsing nothing
530      */
531     struct VoidPacketParser 
532         : public PacketParserBase
533     {
534         SENF_PACKET_PARSER_INIT(VoidPacketParser);
535     };
536
537     /** \brief Iterator re-validating Parser wrapper
538
539         An ordinary parser will be invalidated whenever the raw data container's size is
540         changed. This can complicate some algorithms considerably.
541
542         This wrapper will update the parsers iterator (the value returned by the i() member) on
543         every access. This ensures that the iterator will stay valid.
544
545         \attention Beware however, if you insert or remove data before the safe wrapper, the
546             location will \e not be updated accordingly and therefore the parser will be
547             invalid.
548
549         Additionally a SafePacketParser has an uninitialized state. The only allowed operations in
550         this state are the boolean test for validity and assigning another parser.
551
552         \ingroup packetparser
553       */
554     template <class Parser>
555     class SafePacketParser
556         : public SafeBool< SafePacketParser<Parser> >
557     {
558     public:
559         ///////////////////////////////////////////////////////////////////////////
560         // Types
561
562         ///////////////////////////////////////////////////////////////////////////
563         ///\name Structors and default members
564         ///@{
565
566         // default copy constructor
567         // default copy assignment
568         // default destructor
569         SafePacketParser();             ///< Create an empty uninitialized SafePacketParser
570
571         // conversion constructors
572         SafePacketParser(Parser parser); ///< Initialize SafePacketParser from \a parser
573
574         SafePacketParser & operator=(Parser parser); ///< Assign \a parser to \c this
575
576         ///@}
577         ///////////////////////////////////////////////////////////////////////////
578
579         Parser operator*() const;       ///< Access the stored parser
580                                         /**< On every access, the stored parsers iterator will be
581                                              updated / re-validated. */
582         Parser const * operator->() const; ///< Access the stored parser
583                                         /**< On every access, the stored parsers iterator will be
584                                              updated / re-validated. */
585         bool boolean_test() const;      ///< Check validity
586
587     protected:
588
589     private:
590         mutable boost::optional<Parser> parser_;
591         senf::safe_data_iterator i_;
592     };
593
594 }
595
596 ///////////////////////////////hh.e////////////////////////////////////////
597 #endif
598 #if !defined(SENF_PACKETS_DECL_ONLY) && !defined(HH_PacketParser_i_)
599 #define HH_PacketParser_i_
600 #include "PacketParser.cci"
601 #include "PacketParser.ct"
602 #include "PacketParser.cti"
603 #endif
604
605 \f
606 // Local Variables:
607 // mode: c++
608 // fill-column: 100
609 // c-file-style: "senf"
610 // indent-tabs-mode: nil
611 // ispell-local-dictionary: "american"
612 // compile-command: "scons -u test"
613 // comment-column: 40
614 // End:
615