diff --git a/Packets/PacketInterpreter.hh b/Packets/PacketInterpreter.hh
index 2cf35d90603521a0993c990ddfbb7fa7f19e9eb4..9c6e5bfce10378bf1ce6a295bf48869bdb9aa581 100644
--- a/Packets/PacketInterpreter.hh
+++ b/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////////////////////////////////////////
diff --git a/Packets/PacketParser.hh b/Packets/PacketParser.hh
index 631bf10f915736700f0796cabcbba485d9f8b80b..db7a32fbca119361570d012e26c9afcee227aa9a 100644
--- a/Packets/PacketParser.hh
+++ b/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
diff --git a/Packets/PacketRegistry.ih b/Packets/PacketRegistry.ih
index 77d75981835fbb323637666c4b6835f25f30af5f..0511d6fe416514e8d81d439214c147fd5c6f0fc9 100644
--- a/Packets/PacketRegistry.ih
+++ b/Packets/PacketRegistry.ih
@@ -28,7 +28,7 @@
// Custom includes
#include <boost/intrusive_ptr.hpp>
-#include "typeidvalue.hh"
+#include "Utils/TypeIdValue.hh"
///////////////////////////////ih.p////////////////////////////////////////
diff --git a/Packets/ParseArray.hh b/Packets/ParseArray.hh
index 2914c86577e9bb36e117be6910476020072e9027..ad10ccaee55a97e743f5d636aef96f764c50bbe8 100644
--- a/Packets/ParseArray.hh
+++ b/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
diff --git a/Packets/ParseInt.ih b/Packets/ParseInt.ih
index a1e961c97a096f5bde6121a5c0291e935dca2fdf..1cacbd6c14c4ade7367f556484705fc47e5ec96e 100644
--- a/Packets/ParseInt.ih
+++ b/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)>
diff --git a/Packets/ParseList.hh b/Packets/ParseList.hh
index 945f72e8098782e78f3c831beca8691558f80574..80a5d89c4d8d113fd4c864e5f3959cc613df5a8f 100644
--- a/Packets/ParseList.hh
+++ b/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 */
diff --git a/Packets/ParseVec.hh b/Packets/ParseVec.hh
index 157b061bf7e0de9a68d321972aaa17822cc83e4b..b9ee51bc51f913794a2c7c067cf30add988d5ae8 100644
--- a/Packets/ParseVec.hh
+++ b/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
diff --git a/Packets/ParseVec.ih b/Packets/ParseVec.ih
index f400db4fd2ad58e263723dc6457bdca67d8646b1..339b8f4184f79eb9b9c487e92b595bb54aafb93c 100644
--- a/Packets/ParseVec.ih
+++ b/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
{
diff --git a/Socket/BufferingPolicy.hh b/Socket/BufferingPolicy.hh
index 8f4b2d8dd019b6b5a5bd618d59b5d0bde595ac62..02d61425929e5ab2c15cf5749781583e240b53be 100644
--- a/Socket/BufferingPolicy.hh
+++ b/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.
diff --git a/Socket/SConscript b/Socket/SConscript
index 56ae5d479ccd32e8bb08a6894f4b6784d25a0086..15e931ab35bed0f3534a8a935cd885c03974f4b9 100644
--- a/Socket/SConscript
+++ b/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'),
])
diff --git a/Utils/Mainpage.dox b/Utils/Mainpage.dox
index 7fd6f5919b530ecd39330815580201f2b7cc1132..474b40ff1e12eca24150aa3f3e47c646e253f896 100644
--- a/Utils/Mainpage.dox
+++ b/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>
*/
diff --git a/Packets/typeidvalue.cci b/Utils/TypeIdValue.cci
similarity index 98%
rename from Packets/typeidvalue.cci
rename to Utils/TypeIdValue.cci
index 1d65269115a0b26dffd15777b543bcfe8c47c096..94cb5deaf847b51e5c6ee183b3872f02cc7f1ae0 100644
--- a/Packets/typeidvalue.cci
+++ b/Utils/TypeIdValue.cci
@@ -22,7 +22,7 @@
// Definition of inline non-template functions
-//#include "typeidvalue.ih"
+//#include "TypeIdValue.ih"
// Custom includes
diff --git a/Packets/typeidvalue.cti b/Utils/TypeIdValue.cti
similarity index 98%
rename from Packets/typeidvalue.cti
rename to Utils/TypeIdValue.cti
index ebebe47e1729d7cc7ed9cc71a21ea1f47fd6bf27..5cb61a7e58846e595b6c3717e1a0d3c66b5d7fef 100644
--- a/Packets/typeidvalue.cti
+++ b/Utils/TypeIdValue.cti
@@ -22,7 +22,7 @@
// Definition of inline template functions
-//#include "typeidvalue.ih"
+//#include "TypeIdValue.ih"
// Custom includes
diff --git a/Packets/typeidvalue.hh b/Utils/TypeIdValue.hh
similarity index 94%
rename from Packets/typeidvalue.hh
rename to Utils/TypeIdValue.hh
index a212051b51b126273b53318390623d531ca732e1..61bcdd1d63a842d248dd9d8a99fa7a13f4b1aad9 100644
--- a/Packets/typeidvalue.hh
+++ b/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
diff --git a/doclib/senf.css b/doclib/senf.css
index 476f44f9e7514c16eac52753cb730181804dc5e1..9af205925ca804152575ee8f7e6765368e8259f2 100644
--- a/doclib/senf.css
+++ b/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,
diff --git a/senf.dict b/senf.dict
index e0e04c4ab88d7b253e740efcbeca592c77799643..7830258f1b85435e7094ec69f74379b4928c85c8 100644
--- a/senf.dict
+++ b/senf.dict
@@ -1,5 +1,7 @@
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