4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
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 SafeIterator public header */
26 #ifndef HH_SafeIterator_
27 #define HH_SafeIterator_ 1
30 #error "Don't include 'SafeIterator.hh' directly, include 'Packets.hh'"
34 #include <boost/iterator/iterator_facade.hpp>
36 //#include "SafeIterator.mpp"
37 ///////////////////////////////hh.p////////////////////////////////////////
41 /** \brief Re-validating data iterator
43 This class is a wrapper around a PacketData::iterator instance. It will revalidate the
44 iterator on every access. This keeps the iterator valid even when the data container is
45 resized and thereby possibly relocated. The iterator will always point to the byte at the
46 same offset from the packets beginning. If data is inserted before this iterators position,
47 the data pointed to will of course change.
49 For this to work, the safe_data_iterator must be initialized with the container to which the
50 iterator belongs. After this initialization it can be used like any other iterator.
52 class safe_data_iterator
53 : public boost::iterator_facade< safe_data_iterator,
54 PacketData::value_type,
55 boost::random_access_traversal_tag >,
56 public comparable_safe_bool<safe_data_iterator>
59 typedef PacketData::size_type size_type;
61 safe_data_iterator(); ///< Make uninitialized iterator
62 explicit safe_data_iterator(PacketData & data);
63 ///< Construct iterator only setting the data container
64 safe_data_iterator(PacketData & data, PacketData::iterator i);
65 ///< Initialize iterator to given position
66 explicit safe_data_iterator(PacketParserBase const & parser);
67 ///< Initialize iterator from parser
68 /**< The iterator will point to the parsers start
71 safe_data_iterator & operator=(PacketData::iterator i); ///< Assign iterator
72 /**< The iteator \a i must be from the container wo which \c
73 this iterator has been initialized. */
74 safe_data_iterator & operator=(PacketParserBase const & parser);
75 ///< Assign iterator from parser
76 /**< The iterator will point to the parser start
79 operator PacketData::iterator() const; ///< Convert to iterator
81 bool boolean_test() const; ///< Check, if iterator is initialized
83 PacketData & data() const; ///< Access data container
86 friend class boost::iterator_core_access;
88 // iterator_facade interface
90 value_type & dereference() const;
91 bool equal(safe_data_iterator const & other) const;
92 difference_type distance_to(safe_data_iterator const & other) const;
95 void advance(difference_type n);
97 PacketData::iterator i() const;
103 /** \brief Iterator re-validating Parser wrapper
105 An ordinary parser will be invalidated whenever the raw data container's size is
106 changed. This can complicate some algorithms considerably.
108 This wrapper will update the parsers iterator (the value returned by the i() member) on
109 every access. This ensures that the iterator will stay valid.
111 \attention Beware however, if you insert or remove data before the safe wrapper, the
112 location will \e not be updated accordingly and therefore the parser will be
115 Additionally a SafePacketParserWrapper has an uninitialized state. The only allowed operations in
116 this state are the boolean test for validity and assigning another parser.
118 \ingroup packetparser
120 template <class Parser>
121 class SafePacketParserWrapper
122 : public safe_bool< SafePacketParserWrapper<Parser> >
125 ///////////////////////////////////////////////////////////////////////////
128 ///////////////////////////////////////////////////////////////////////////
129 ///\name Structors and default members
132 // default copy constructor
133 // default copy assignment
134 // default destructor
135 SafePacketParserWrapper(); ///< Create an empty uninitialized SafePacketParserWrapper
137 // conversion constructors
138 SafePacketParserWrapper(Parser parser); ///< Initialize SafePacketParserWrapper from \a parser
140 SafePacketParserWrapper & operator=(Parser parser); ///< Assign \a parser to \c this
143 ///////////////////////////////////////////////////////////////////////////
145 Parser operator*() const; ///< Access the stored parser
146 /**< On every access, the stored parsers iterator will be
147 updated / re-validated. */
148 Parser const * operator->() const; ///< Access the stored parser
149 /**< On every access, the stored parsers iterator will be
150 updated / re-validated. */
151 bool boolean_test() const; ///< Check validity
156 mutable boost::optional<Parser> parser_;
157 senf::safe_data_iterator i_;
162 ///////////////////////////////hh.e////////////////////////////////////////
164 #if !defined(HH_Packets__decls_) && !defined(HH_SafeIterator_i_)
165 #define HH_SafeIterator_i_
166 #include "SafeIterator.cci"
167 //#include "SafeIterator.ct"
168 #include "SafeIterator.cti"
175 // comment-column: 40
176 // c-file-style: "senf"
177 // indent-tabs-mode: nil
178 // ispell-local-dictionary: "american"
179 // compile-command: "scons -u test"