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 PacketData public header */
26 #ifndef HH_PacketData_
27 #define HH_PacketData_ 1
30 #include <boost/utility.hpp>
31 #include <boost/type_traits.hpp>
32 #include <boost/iterator/iterator_facade.hpp>
33 #include "../Utils/safe_bool.hh"
34 #include "../Utils/Exception.hh"
35 #include "PacketTypes.hh"
37 //#include "PacketData.mpp"
38 ///////////////////////////////hh.p////////////////////////////////////////
42 /** \brief Packet data STL-sequence view
44 The PacketData class provides an STL-sequence compatible view of the raw packet data. Each
45 packet/header/interpreter in the chain references the same storage area, presenting a
46 different (but nested/overlapping) section of the data.
48 Whenever the data is manipulated through PacketData, the change is assumed to be within the
49 data range of that packet: All insertions take place \e inside \c this packet and \e outside
50 any following packets in the packet chain.
52 \warning It is not permissible to change data belonging to a following
53 packet/header/interpreter even though this data is part of \c this sequence. Doing so
54 will corrupt the packet data.
58 \warning When accessing packet data via the PacketData interface you are on your own: The
59 packet is not validated in any way, you bypass all parsers.
61 All public members are those of an STL random-access sequence.
63 \implementation This class is very tightly integrated with PacketInterpreterBase /
64 PacketInterpreter. It is separated out of those classes primarily to provide a clean
65 sequence interface to the library user and not for implementation reasons (it would have
66 been simpler to implement all these members in PacketInterpreterBase).
68 \ingroup packet_module
74 ///////////////////////////////////////////////////////////////////////////
77 typedef senf::detail::packet::iterator iterator;
78 typedef senf::detail::packet::const_iterator const_iterator;
79 typedef senf::detail::packet::size_type size_type;
80 typedef senf::detail::packet::difference_type difference_type;
81 typedef senf::detail::packet::byte byte;
82 typedef byte value_type;
83 typedef byte & reference;
84 typedef byte const & const_reference;
85 typedef byte * pointer;
86 typedef byte const * const_pointer;
88 ///////////////////////////////////////////////////////////////////////////
89 ///\name Structors and default members
92 // no public constructors
93 // no conversion constructors
96 ///////////////////////////////////////////////////////////////////////////
98 ///\name Sequence interface to raw data
101 iterator begin() const; ///< Return iterator to beginning
102 /**< Returns an <em>random access iterator</em> referring to the
103 first byte of the packet data. */
104 iterator end() const; ///< Return iterator to end
105 /**< Returns an <em>random access iterator</em> referring to the
106 byte past the end of the packet data. */
107 size_type size() const; ///< Returns the number of bytes in the packet data.
108 bool empty() const; ///< Test whether the packet data is empty.
109 /**< Returns whether the packet data is empty, i.e. whether its size
110 is 0. This function does not modify the content of the packet
111 data in any way. To clear the content use clear() */
112 byte operator[](size_type n) const; ///< Access byte in the packet data
113 byte & operator[](size_type n); ///< Access byte in the packet data
115 // Modifying the raw packet data
117 // IMPORTANT NOTE: It is not possible to insert data AFTER an empty packet
118 // since for an empty packet begin() == end(). However, I hope this problem is
119 // only academic since what should an empty packet be good for ?
120 void insert(iterator pos, byte v);
121 void insert(iterator pos, size_type n, byte v);
123 template <class InputIterator>
124 void insert(iterator pos, InputIterator f, InputIterator l,
125 typename boost::disable_if< boost::is_convertible<InputIterator,size_type> >::type * = 0);
127 template <class InputIterator>
128 void insert(iterator pos, InputIterator f, InputIterator l);
131 void erase(iterator pos);
132 void erase(iterator first, iterator last);
133 void clear(); ///< All bytes of the packet data dropped, leaving the container with a size of 0. */
135 void resize(size_type n, byte v=0);
140 PacketData(size_type b, size_type e);
142 /// Need to make this protected so we can change it in the derived class
143 detail::PacketImpl * impl_;
145 detail::PacketImpl & impl() const;
153 friend class detail::PacketImpl;
156 class PacketParserBase;
158 /** \brief Invalid packet data access
160 This exception is signaled whenever an operation tries to access an out-of-bounds data
161 byte. If the packet has been implemented correctly, this signals a malformed packet.
163 struct TruncatedPacketException : public senf::Exception
164 { TruncatedPacketException() : senf::Exception("truncated packet"){} };
166 /** \brief Re-validating data iterator
168 This class is a wrapper around a PacketData::iterator instance. It will revalidate the
169 iterator on every access. This keeps the iterator valid even when the data container is
170 resized and thereby possibly relocated. The iterator will always point to the byte at the
171 same offset from the packets beginning. If data is inserted before this iterators position,
172 the data pointed to will of course change.
174 For this to work, the safe_data_iterator must be initialized with the container to which the
175 iterator belongs. After this initialization it can be used like any other iterator.
177 class safe_data_iterator
178 : public boost::iterator_facade< safe_data_iterator,
179 PacketData::value_type,
180 boost::random_access_traversal_tag >,
181 public comparable_safe_bool<safe_data_iterator>
184 typedef PacketData::size_type size_type;
186 safe_data_iterator(); ///< Make uninitialized iterator
187 explicit safe_data_iterator(PacketData & data);
188 ///< Construct iterator only setting the data container
189 safe_data_iterator(PacketData & data, PacketData::iterator i);
190 ///< Initialize iterator to given position
191 explicit safe_data_iterator(PacketParserBase const & parser);
192 ///< Initialize iterator from parser
193 /**< The iterator will point to the parsers start
196 safe_data_iterator & operator=(PacketData::iterator i); ///< Assign iterator
197 /**< The iteator \a i must be from the container wo which \c
198 this iterator has been initialized. */
199 safe_data_iterator & operator=(PacketParserBase const & parser);
200 ///< Assign iterator from parser
201 /**< The iterator will point to the parser start
204 operator PacketData::iterator() const; ///< Convert to iterator
206 bool boolean_test() const; ///< Check, if iterator is initialized
208 PacketData & data() const; ///< Access data container
211 friend class boost::iterator_core_access;
213 // iterator_facade interface
215 value_type & dereference() const;
216 bool equal(safe_data_iterator const & other) const;
217 difference_type distance_to(safe_data_iterator const & other) const;
220 void advance(difference_type n);
222 PacketData::iterator i() const;
229 ///////////////////////////////hh.e////////////////////////////////////////
231 #if !defined(HH_Packets__decls_) && !defined(HH_PacketData_i_)
232 #define HH_PacketData_i_
233 #include "PacketData.cci"
234 //#include "PacketData.ct"
235 #include "PacketData.cti"
242 // c-file-style: "senf"
243 // indent-tabs-mode: nil
244 // ispell-local-dictionary: "american"
245 // compile-command: "scons -u test"
246 // comment-column: 40