PPI: Checkin of first compiling (yet not working) version

[senf.git] / Packets / PacketData.hh

diff --git a/Packets/PacketData.hh b/Packets/PacketData.hh
index 8d94d9c..2f8a521 100644 (file)
--- a/Packets/PacketData.hh
+++ b/Packets/PacketData.hh
@@ -95,10 +95,16 @@ namespace senf {
         ///\name Sequence interface to raw data
         ///@{
 
-        iterator begin() const;
-        iterator end() const;
-        size_type size() const;
-        bool empty() const;
+        iterator begin() const; /**< Returns an <em>random access iterator</em> referring
+                                     to the first byte of the packet data. */
+        iterator end() const; /**< Returns an <em>random access iterator</em> referring to the 
+                                   element past the end of the packet data. */
+        size_type size() const; ///< Returns the number of bytes in the packet data.
+        bool empty() const; ///< Test whether the packet data is empty.
+                                        /**< Returns whether the packet data is empty, i.e. 
+                                             whether its size is 0. This function does not modify
+                                             the content of the packet data in any way. To clear
+                                             the content use clear() */        
         byte operator[](size_type n) const;
         byte & operator[](size_type n);
 
@@ -109,13 +115,19 @@ namespace senf {
         // only academic since what should an empty packet be good for ?
         void insert(iterator pos, byte v);
         void insert(iterator pos, size_type n, byte v);
+#       ifndef DOXYGEN
         template <class InputIterator>
         void insert(iterator pos, InputIterator f, InputIterator l,
                     typename boost::disable_if< boost::is_convertible<InputIterator,size_type> >::type * = 0);
+#       else
+        template <class InputIterator>
+        void insert(iterator pos, InputIterator f, InputIterator l);
+#       endif
 
         void erase(iterator pos);
         void erase(iterator first, iterator last);
-        void clear();
+        void clear(); /**< All bytes of the packet data dropped, 
+                           leaving the container with a size of 0. */
         
         void resize(size_type n, byte v=0);
 
@@ -140,9 +152,25 @@ namespace senf {
 
     class PacketParserBase;
 
+    /** \brief Invalid packet data access
+
+        This exception is signaled whenever an operation tries to access an out-of-bounds data
+        byte. If the packet has been implemented correctly, this signals a malformed packet.
+     */
     struct TruncatedPacketException : public std::exception
     { virtual char const * what() const throw() { return "truncated packet"; } };
 
+    /** \brief Re-validating data iterator
+
+        This class is a wrapper around a PacketData::iterator instance. It will revalidate the
+        iterator on every access. This keeps the iterator valid even when the data container is
+        resized and thereby possibly relocated. The iterator will always point to the byte at the
+        same offset from the packets beginning. If data is inserted before this iterators position,
+        the data pointed to will of course change.
+
+        For this to work, the safe_data_iterator must be initialized with the container to which the
+        iterator belongs. After this initialization it can be used like any other iterator.
+     */
     class safe_data_iterator
         : public boost::iterator_facade< safe_data_iterator,
                                          PacketData::value_type,
@@ -152,18 +180,29 @@ namespace senf {
     public:
         typedef PacketData::size_type size_type;
 
-        safe_data_iterator();
-        explicit safe_data_iterator(PacketData & data);
+        safe_data_iterator(); ///< Make uninitialized iterator
+        explicit safe_data_iterator(PacketData & data); 
+                                        ///< Construct iterator only setting the data container
         safe_data_iterator(PacketData & data, PacketData::iterator i);
+                                        ///< Initialize iterator to given position
         explicit safe_data_iterator(PacketParserBase const & parser);
+                                        ///< Initialize iterator from parser
+                                        /**< The iterator will point to the parsers start
+                                             position. */
 
-        safe_data_iterator & operator=(PacketData::iterator i);
+        safe_data_iterator & operator=(PacketData::iterator i); ///< Assign iterator
+                                        /**< The iteator \a i must be from the container wo which \c
+                                             this iterator has been initialized. */
         safe_data_iterator & operator=(PacketParserBase const & parser);
-        operator PacketData::iterator() const;
+                                        ///< Assign iterator from parser
+                                        /**< The iterator will point to the parser start
+                                             position. */
+
+        operator PacketData::iterator() const; ///< Convert to iterator
 
-        bool boolean_test() const;
+        bool boolean_test() const;      ///< Check, if iterator is initialized
 
-        PacketData & data() const;
+        PacketData & data() const;      ///< Access data container
 
     private:
         friend class boost::iterator_core_access;
@@ -204,7 +243,3 @@ namespace senf {
 // comment-column: 40
 // End:
 
-//  LocalWords:  Fraunhofer Institut fuer offene Kommunikationssysteme FOKUS de
-//  LocalWords:  Kompetenzzentrum Satelitenkommunikation SatCom Bund berlios dil
-//  LocalWords:  PacketData hh STL PacketInterpreterBase PacketInterpreter
-//  LocalWords:  ingroup Structors