From 9fab5072fefabadaec1b0a54df7635a54def3974 Mon Sep 17 00:00:00 2001
From: g0dil <g0dil@wiback.org>
Date: Mon, 23 Jul 2007 12:05:21 +0000
Subject: [PATCH] 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 | 2 +-
Packets/PacketParser.hh | 9 +-
Packets/PacketRegistry.ih | 2 +-
Packets/ParseArray.hh | 7 +-
Packets/ParseInt.ih | 42 +++++++
Packets/ParseList.hh | 14 ++-
Packets/ParseVec.hh | 109 +++++++++++++++++-
Packets/ParseVec.ih | 6 +
Socket/BufferingPolicy.hh | 6 -
Socket/SConscript | 3 +-
Utils/Mainpage.dox | 3 +
.../typeidvalue.cci => Utils/TypeIdValue.cci | 2 +-
.../typeidvalue.cti => Utils/TypeIdValue.cti | 2 +-
.../typeidvalue.hh => Utils/TypeIdValue.hh | 12 +-
doclib/senf.css | 1 +
senf.dict | 13 +++
16 files changed, 209 insertions(+), 24 deletions(-)
rename Packets/typeidvalue.cci => Utils/TypeIdValue.cci (98%)
rename Packets/typeidvalue.cti => Utils/TypeIdValue.cti (98%)
rename Packets/typeidvalue.hh => Utils/TypeIdValue.hh (94%)
diff --git a/Packets/PacketInterpreter.hh b/Packets/PacketInterpreter.hh
index 2cf35d906..9c6e5bfce 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 631bf10f9..db7a32fbc 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 77d759818..0511d6fe4 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 2914c8657..ad10ccaee 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 a1e961c97..1cacbd6c1 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 945f72e80..80a5d89c4 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 157b061bf..b9ee51bc5 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 f400db4fd..339b8f418 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 8f4b2d8dd..02d614259 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 56ae5d479..15e931ab3 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 7fd6f5919..474b40ff1 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 1d6526911..94cb5deaf 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 ebebe47e1..5cb61a7e5 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 a212051b5..61bcdd1d6 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 476f44f9e..9af205925 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 e0e04c4ab..7830258f1 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
--
GitLab