From: g0dil Date: Mon, 23 Jul 2007 12:05:21 +0000 (+0000) Subject: Socket: BUGFIX: Explicitly copy image X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=a3d3979b7daaf22ea63ca356edbfa8047dff7b78;p=senf.git Socket: BUGFIX: Explicitly copy image Packets: Move typeidvalue to Utils/TypeIdValue Packets: Add integer parser documentation Packets: Fix ExampleListPolicy documentation Packets: Document Parse_Vector git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@335 270642c3-0616-0410-b53a-bc976706d245 --- diff --git a/Packets/PacketInterpreter.hh b/Packets/PacketInterpreter.hh index 2cf35d9..9c6e5bf 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 631bf10..db7a32f 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 whenever the size of the packet's + data is changed. 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 SafePacketParser diff --git a/Packets/PacketRegistry.ih b/Packets/PacketRegistry.ih index 77d7598..0511d6f 100644 --- a/Packets/PacketRegistry.ih +++ b/Packets/PacketRegistry.ih @@ -28,7 +28,7 @@ // Custom includes #include -#include "typeidvalue.hh" +#include "Utils/TypeIdValue.hh" ///////////////////////////////ih.p//////////////////////////////////////// diff --git a/Packets/ParseArray.hh b/Packets/ParseArray.hh index 2914c86..ad10cca 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 a1e961c..1cacbd6 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 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 struct parse_bitfield : public parse_bitfield_i diff --git a/Packets/ParseList.hh b/Packets/ParseList.hh index 945f72e..80a5d89 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 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. senf::Parse_List. */ + typedef void container_type; ///< Type of container wrapper + /**< This is the container wrapper of the list, e.g. + Parse_List_Container. 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 157b061..b9ee51b 100644 --- a/Packets/ParseVec.hh +++ b/Packets/ParseVec.hh @@ -38,15 +38,33 @@ namespace senf { template 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 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 Parse_VectorN_Sizer; } + /** \brief Vector with prefix sizing + + This is a 'template typedef'. It defines a vector with a directly preceding 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::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 struct Parse_VectorN { @@ -99,9 +134,75 @@ namespace senf { detail::Parse_VectorN_Sizer > 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 Parse_Vector_Container diff --git a/Packets/ParseVec.ih b/Packets/ParseVec.ih index f400db4..339b8f4 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 struct Parse_VectorN_Sizer { diff --git a/Socket/BufferingPolicy.hh b/Socket/BufferingPolicy.hh index 8f4b2d8..02d6142 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 56ae5d4..15e931a 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 7fd6f59..474b40f 100644 --- a/Utils/Mainpage.dox +++ b/Utils/Mainpage.dox @@ -36,6 +36,9 @@ namespace senf {
\ref contiguous_storage_iterator
traits class to check iterator type for raw pointer accessibility
+
\ref TypeIdValue
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.
+ */ diff --git a/Packets/typeidvalue.cci b/Utils/TypeIdValue.cci similarity index 98% rename from Packets/typeidvalue.cci rename to Utils/TypeIdValue.cci index 1d65269..94cb5de 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 ebebe47..5cb61a7 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 a212051..61bcdd1 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 @@ -29,7 +29,7 @@ #include #include -//#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 476f44f..9af2059 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 e0e04c4..7830258 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