Socket: BUGFIX: Explicitly copy image

Packets: Move typeidvalue to Utils/TypeIdValue
Packets: Add integer parser documentation
Packets: Fix ExampleListPolicy documentation
Packets: Document Parse_Vector

Packets/PacketInterpreter.hh

@@ -33,7 +33,7 @@
 #include "Utils/intrusive_refcount.hh"
 #include "Utils/pool_alloc_mixin.hh"
 #include "PacketData.hh"
-#include "typeidvalue.hh"
+#include "Utils/TypeIdValue.hh"
 
 //#include "PacketInterpreter.mpp"
 ///////////////////////////////hh.p////////////////////////////////////////

Packets/PacketParser.hh

@@ -63,6 +63,11 @@
 
     Every parser is derived from senf::PacketParserBase. This class provides the necessary
     housekeeping information and provides the parsers with access to the data.
+
+    \warning Parsers are like iterators: They are invalidated <em>whenever the size of the packet's
+    data is changed</em>. You should not store a parser anywhere. If you want to keep a parser
+    reference, use the senf::SafePacketParser wrapper. You still will need to take extra care to
+    ensure the parser is not invalidated.
  */
 
 #ifndef HH_PacketParser_
@@ -536,8 +541,10 @@ namespace senf {
             location will \e not be updated accordingly and therefore the parser will be
             invalid.
 
-        Additionally a SafePacketparser has an uninitialized state. The only allowed operations in
+        Additionally a SafePacketParser has an uninitialized state. The only allowed operations in
         this state are the boolean test for validity and assigning another parser.
+
+        \ingroup packetparser
       */
     template <class Parser>
     class SafePacketParser

Packets/PacketRegistry.ih

@@ -28,7 +28,7 @@
 
 // Custom includes
 #include <boost/intrusive_ptr.hpp>
-#include "typeidvalue.hh"
+#include "Utils/TypeIdValue.hh"
 
 ///////////////////////////////ih.p////////////////////////////////////////
 

Packets/ParseArray.hh

@@ -32,7 +32,12 @@
     collection parser, what kind of sequence is modelled (e.g. random access sequence, forward
     sequence etc). Most collections will also provide a kind of container wrapper to allow extensive
     manipulations of the collection contents. A container wrapper is initialized with the collection
-    parser and then provides a more complete sequence interface.
+    parser and then provides a more complete sequence interface. Additionally, the collection
+    wrapper has a longer lifetime than an ordinary parser: While a parser will be invalidated
+    whenever the collection is changed, the container wrapper will stay valid as long as the
+    collection is changed through the wrapper (directly or indirectly, where indirectly means that a
+    sub-field or sub-collection of the collection is changed). Some collections may provide even
+    more lifetime guarantees but this guarantee should be met by all collection wrappers.
 
     \important Parser lifetime has to be tightly checked when working with collection parsers since
     \e every change of the collections size will invalidate \e all parsers and iterators referencing

Packets/ParseInt.ih

@@ -35,6 +35,13 @@ namespace packet {
     ///////////////////////////////////////////////////////////////////////////
     // Integer operators
 
+    /** \brief Internal: Integer operation mixin for integer parsers
+
+        \internal
+
+        This class contains all the integer operations supported by the integer parsers. It is
+        inherited by each integer parser.
+     */
     template <class Derived, class Value>
     class ParseIntOps
     {
@@ -85,22 +92,38 @@ namespace packet {
     ///////////////////////////////////////////////////////////////////////////
     // Network byte order integer extraction
 
+    /** \brief Internal: Extract 16bit network byte order value
+        
+        \internal
+     */
     inline boost::uint16_t parse_uint16(iterator i)
     {
         return i[1] | i[0]<<8;
     }
 
+    /** \brief Internal: Write 16bit network byte order value
+        
+        \internal
+     */
     inline void write_uint16(iterator i, boost::uint16_t v)
     {
         i[0] = ( v >>  8 ) & 0xff;
         i[1] = ( v       ) & 0xff;
     }
 
+    /** \brief Internal: Extract 24bit network byte order value
+        
+        \internal
+     */
     inline boost::uint32_t parse_uint24(iterator i)
     {
         return i[2] | i[1]<<8 | i[0]<<16;
     }
 
+    /** \brief Internal: Write 24bit network byte order value
+        
+        \internal
+     */
     inline void write_uint24(iterator i, boost::uint32_t v)
     {
         i[0] = ( v >> 16 ) & 0xff;
@@ -108,11 +131,19 @@ namespace packet {
         i[2] = ( v       ) & 0xff;
     }
 
+    /** \brief Internal: Extract 32bit network byte order value
+        
+        \internal
+     */
     inline boost::uint32_t parse_uint32(iterator i)
     {
         return i[3] | i[2]<<8 | i[1]<<16 | i[0]<<24;
     }
 
+    /** \brief Internal: Write 32bit network byte order value
+        
+        \internal
+     */
     inline void write_uint32(iterator i, boost::uint32_t v)
     {
         i[0] = ( v >> 24 ) & 0xff;
@@ -208,6 +239,17 @@ namespace packet {
 
 #   endif
 
+    /** \brief Internal: Bitfield read/write helper
+
+        \internal
+        
+        Using template specializations, this class provides optimized bitfield parsers and
+        writers. For each number of bytes the bitfield covers (from 1 to 5 bytes), a template
+        specialization is provided in \c parse_bitfield_i.
+
+        This helper always processes unsigned values. For signed values sign extension still needs
+        to be performed.
+     */
     template <unsigned start, unsigned end>
     struct parse_bitfield
         : public parse_bitfield_i<start/8,(end-1)/8-start/8,start%8,end-8*(start/8)>

Packets/ParseList.hh

@@ -89,7 +89,6 @@ namespace senf {
         This class shows the interface which must be implemented by a list policy. It is not a list
         policy only a declaration of the interface:
         \code
-        tempalte <class ElementParser>
         struct ExampleListPolicy
         {
             // optional typedefs used to simplify all other declarations
@@ -138,6 +137,19 @@ namespace senf {
         typedef PacketParserBase::state_type state_type;
         typedef PacketParserBase::size_type size_type;
 
+        typedef void element_type;      ///< Type of list elements
+                                        /**< This is the parser used to parse the list elements. */
+        typedef void parser_type;       ///< List parser type
+                                        /**< parser_type is the list parser used to parse a list of
+                                             this type,
+                                             e.g. <tt>senf::Parse_List<ExampleListPolicy></tt>. */
+        typedef void container_type;    ///< Type of container wrapper
+                                        /**< This is the container wrapper of the list, e.g.
+                                             <tt>Parse_List_Container<ExampleListPolicy></tt>. The
+                                             container may however use a \e different policy, as
+                                             long as that policy is constructible from the parser
+                                             policy. */
+
         static const size_type init_bytes = 0; ///< Size of a new list of this type
                                         /**< Initial size which needs to be allocated to this type
                                              of list */

Packets/ParseVec.hh

@@ -38,15 +38,33 @@ namespace senf {
 
     template <class ElementParser, class Sizer> class Parse_Vector_Container;
 
-    /** \brief
+    /** \brief Collection of fixed-size elements
+
+        A Vector is a collection of fixed-size elements of which the size of the collection can be
+        determined directly (that is without traversing the collection). This allows very efficient
+        random access to the elements of the collection.
+        
+        A vector is a model of an STL random-access sequence. The parser only provides a reduced
+        interface, the container wrapper however completes this interface.
+
+        Parse_Vector makes use of a policy template argument, \a Sizer to customize the way the
+        containers size is obtained. You will normally not instantiate Parser_Vector directly, you
+        will use one of the 'template typedefs' (which are templated structures since C++ does not
+        provide real template typedefs) provided with the policy implementations.
         
-        \todo Make the sizer a private baseclass to profit from the empty-base-class optimization
+        \todo Make the sizer a private base-class to profit from the empty-base-class optimization
+
+        \see ExampleVectorPolicy
+        \ingroup parsecollection
      */
     template <class ElementParser, class Sizer>
     struct Parse_Vector : public PacketParserBase
     {
         Parse_Vector(data_iterator i, state_type s);
         Parse_Vector(Sizer sizer, data_iterator i, state_type s);
+                                        ///< Additional sizer specific constructor
+                                        /**< This constructor may be used, if the sizer needs
+                                             additional parameters. */
 
         size_type bytes() const;
         void init() const;
@@ -92,6 +110,23 @@ namespace senf {
 
     namespace detail { template <class SizeParser> class Parse_VectorN_Sizer; }
 
+    /** \brief Vector with prefix sizing
+        
+        This is a 'template typedef'. It defines a vector with a <em>directly preceding</em> size
+        field holding the number of vector elements. The size field is considered part of the
+        vector.
+        \code
+        // Define MyVector as a vector of 16bit unsigned elements with a directly preceding
+        // 8bit unsigned size field
+        typedef senf::Parse_VectorN<senf::Parse_UInt16, senf::Parse_UInt8>::parser MyVector;
+        \endcode
+
+        \param ElementParser \e fixed-size parser for parsing the vector elements
+        \param SizeParser parser for parsing the vector size (number of elements)
+
+        \see Parse_Vector
+        \ingroup parsecollection
+     */
     template <class ElementParser, class SizeParser>
     struct Parse_VectorN
     {
@@ -99,9 +134,75 @@ namespace senf {
                               detail::Parse_VectorN_Sizer<SizeParser> > parser;
     };
 
-    /** \brief
+    /** \brief Example vector sizer. ONLY FOR EXPOSITION
+
+        This class shows the interface which must be implemented by a vector sizer policy. It is not
+        a vector sizer, it is only a declaration of the interface:
+        \code
+        struct ExampleVectorPolicy
+        {
+            // optional typedefs used to simplify all other declarations
+            typedef PacketParserBase::size_type size_type;
+            typedef PacketParserBase::data_iterator iterator;
+            typedef PacketParserBase::state_type state_type;
+
+            // mandatory members
+            static const size_type init_bytes = 0;
+            size_type  size  (iterator i, state_type s) const;
+            void       size  (iterator i, state_type s, size_type v) const;
+            iterator   begin (iterator i, state_type s) const;
+            size_type  bytes (iterator i, state_type s) const;
+            void       init  (iterator i, state_type s) const;
+        };
+        \endcode
+
+        A sizer may if needed define additional data members.
+     */
+    struct ExampleVectorPolicy
+    {
+        typedef PacketParserBase::size_type size_type;
+        typedef PacketParserBase::data_iterator iterator;
+        typedef PacketParserBase::state_type state_type;
+
+        static const size_type init_bytes = 0; ///< Size of a new vector of this size
+                                        /**< Initial size which needs to be allocated to this type
+                                             of list */
+
+        size_type  size  (iterator i, state_type s) const; ///< Get current vector size
+                                        /**< Return the current number of elements in the 
+                                             vector. */
+        void       size  (iterator i, state_type s, size_type v) const; ///< Change vector size
+                                        /**< Set the size of the vector to \a v. */
+        iterator   begin (iterator i, state_type s) const; 
+                                        ///< Return data_iterator to first element
+                                        /**< The returned data_iterator must point to the beginning
+                                             of the first vector element. The last iterator can than
+                                             automatically be calculated from the fixed element size
+                                             and the number of vector elements. */
+        size_type  bytes (iterator i, state_type s) const; ///< Size of vector parser
+                                        /**< Return the size of the complete vector in bytes. This
+                                             is not necessarily the same as \c size() * \e
+                                             fixed_element_bytes. */
+        void       init  (iterator i, state_type s) const; ///< Initialize new vector
+                                        /** Called to initialize a new vector after allocating
+                                            init_bytes number of bytes for the vector. */
+    };
 
-        Holds a reference to the container !
+    /** \brief Parse_Vector container wrapper
+
+        This is the container wrapper used for vector parsers. The container wrapper will stay valid
+        after changing the collection. However the container still depends on the packet and will be
+        invalidated if the Packet is deallocated or if the packet size is changed from without the
+        container wrapper (more precisely, it is invalided if the insertion/deletion happens before
+        the vector in the packet data).
+
+        The vector container wrapper provides a complete STL random-access sequence interface.
+        
+        \code
+        SomePacket p (...);
+        SomePacket::aVectorCollection_t::container c (p->aVectorCollection());
+        c.insert(c.begin(), ... );
+        \endcode
       */
     template <class ElementParser, class Sizer>
     class Parse_Vector_Container

Packets/ParseVec.ih

@@ -31,6 +31,12 @@
 namespace senf {
 namespace detail {
 
+    /** \brief Internal: Sizer implementing prefix sizing
+
+        \internal
+
+        This is the sizer policy used by Parse_VectorN
+     */
     template <class SizeParser>
     struct Parse_VectorN_Sizer
     {

Socket/BufferingPolicy.hh

@@ -49,12 +49,6 @@ namespace senf {
     struct NoBufferingPolicy : public BufferingPolicyBase
     {};
     
-    /// @}
-
-    
-    /// \addtogroup policy_impl_group
-    /// @{
-
     /** \brief BufferingPolicy implementing standard socket buffering
 
         This policy class implements standard BSD socket buffering.

Socket/SConscript

@@ -17,7 +17,8 @@ SENFSCons.Lib(env,
 SENFSCons.Doxygen(env, extra_sources = [
     env.Dia2Png('SocketLibrary-classes.dia'),
     env.Dia2Png('FhHierarchy.dia'),
-    env.Dia2Png('SocketPolicy.dia'),
+    env.Command('doc/html/SocketPolicy.png', env.Dia2Png('SocketPolicy.dia'),
+                Copy('$TARGET','$SOURCE')),
     env.Dia2Png('Protocols.dia'),
     env.Dia2Png('Handle.dia'),
 ])

Utils/Mainpage.dox

@@ -36,6 +36,9 @@ namespace senf {
     <dt>\ref contiguous_storage_iterator</dt><dd>traits class to check iterator type for raw pointer
     accessibility</dd>
 
+    <dt>\ref TypeIdValue</dt><dd>class wrapping a typeid in a way that it can be used like any other
+    value type, e.g. as the key in a map.</dd>
+
     </dl>
  */
 

Packets/typeidvalue.cci → Utils/TypeIdValue.cci

@@ -22,7 +22,7 @@
 
 // Definition of inline non-template functions
 
-//#include "typeidvalue.ih"
+//#include "TypeIdValue.ih"
 
 // Custom includes
 

Packets/typeidvalue.cti → Utils/TypeIdValue.cti

@@ -22,7 +22,7 @@
 
 // Definition of inline template functions
 
-//#include "typeidvalue.ih"
+//#include "TypeIdValue.ih"
 
 // Custom includes
 

Packets/typeidvalue.hh → Utils/TypeIdValue.hh

@@ -20,8 +20,8 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
-#ifndef HH_typeidvalue_
-#define HH_typeidvalue_ 1
+#ifndef HH_TypeIdValue_
+#define HH_TypeIdValue_ 1
 
 // Custom includes
 #include <typeinfo>
@@ -29,7 +29,7 @@
 #include <boost/scoped_ptr.hpp>
 #include <boost/operators.hpp>
 
-//#include "typeidvalue.mpp"
+//#include "TypeIdValue.mpp"
 ///////////////////////////////hh.p////////////////////////////////////////
 
 namespace senf {
@@ -92,9 +92,9 @@ namespace senf {
 }
 
 ///////////////////////////////hh.e////////////////////////////////////////
-#include "typeidvalue.cci"
-//#include "typeidvalue.ct"
-#include "typeidvalue.cti"
+#include "TypeIdValue.cci"
+//#include "TypeIdValue.ct"
+#include "TypeIdValue.cti"
 #endif
 
 

doclib/senf.css

@@ -322,6 +322,7 @@ p.memtitle {
         color: #1a41a8;
         font-weight: bold;
         margin-right: 14px;
+        border-bottom: 1px solid #84b0c7;
 }
 
 p.sourceline, p.references, p.referencedby, p.reimplementedfrom, p.reimplementedin, 

senf.dict

 accessor
 addtogroup
+aVectorCollection
+BaseParser
 berlios
 bitfield
 bund
@@ -16,6 +18,7 @@ DefaultBundle
 defaultInit
 defgroup
 dil
+dontinclude
 ElementParser
 endcode
 eth
@@ -25,6 +28,8 @@ EthernetPacketType
 EthernetParser
 ethertype
 EthVLan
+ExampleVectorPolicy
+ExtendedParser
 findNext
 findPrev
 fokus
@@ -48,6 +53,7 @@ IntField
 InvalidPacketChainException
 ip
 IpV
+iterator
 key
 Kommunikationssysteme
 Kompetenzzentrum
@@ -55,6 +61,7 @@ li
 MACAddress
 mainpage
 mixin
+MyVector
 namespace
 NextPacket
 nextPacketKey
@@ -92,6 +99,7 @@ parsecollection
 parseint
 ParseInt
 parseNextAs
+ParseVec
 png
 prev
 protocolbundle
@@ -102,11 +110,14 @@ registerPacketType
 registerSomePacket
 RegistrationProxy
 rerference
+SafePacketParser
 SatCom
 Satelitenkommunikation
 senf
 SimplePacketType
 SimpleVectorSizer
+SizeParser
+skipline
 someField
 someOtherField
 SomePacket
@@ -122,6 +133,7 @@ STL
 struct
 structors
 templated
+todo
 TruncatedPacketException
 tt
 ttl
@@ -130,6 +142,7 @@ udp
 UDPPacket
 UInt
 UIntField
+VectorN
 vlanId
 VLanId
 VoidPacketParser