From: g0dil Date: Mon, 23 Jul 2007 13:07:34 +0000 (+0000) Subject: Packets: Document Parse_List, Parse_ListB and Parse_ListN X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=e21a814c84efb8ba3a6a978c6907f3c401c649ff;p=senf.git Packets: Document Parse_List, Parse_ListB and Parse_ListN git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@337 270642c3-0616-0410-b53a-bc976706d245 --- diff --git a/Packets/PacketRegistry.ih b/Packets/PacketRegistry.ih index 0511d6f..0c83b8e 100644 --- a/Packets/PacketRegistry.ih +++ b/Packets/PacketRegistry.ih @@ -35,7 +35,8 @@ namespace senf { namespace detail { - /** \brief Internal + /** \brief Internal: Registry entry implementation for a specific packet type + \internal */ template diff --git a/Packets/ParseArray.cti b/Packets/ParseArray.cti index 901b51a..14d99cb 100644 --- a/Packets/ParseArray.cti +++ b/Packets/ParseArray.cti @@ -20,7 +20,8 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -// Definition of inline template functions +/** \file + \brief ParseArray inline template implementation */ #include "ParseArray.ih" diff --git a/Packets/ParseArray.hh b/Packets/ParseArray.hh index ad10cca..8dfca23 100644 --- a/Packets/ParseArray.hh +++ b/Packets/ParseArray.hh @@ -20,6 +20,9 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +/** \file + \brief ParseArray public header */ + #ifndef HH_ParseArray_ #define HH_ParseArray_ 1 diff --git a/Packets/ParseArray.ih b/Packets/ParseArray.ih index c5db831..d07c26f 100644 --- a/Packets/ParseArray.ih +++ b/Packets/ParseArray.ih @@ -20,6 +20,9 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +/** \file + \brief ParseArray internal header */ + #ifndef IH_ParseArray_ #define IH_ParseArray_ 1 diff --git a/Packets/ParseInt.hh b/Packets/ParseInt.hh index a54a056..ee97811 100644 --- a/Packets/ParseInt.hh +++ b/Packets/ParseInt.hh @@ -20,6 +20,9 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +/** \file + \brief ParseInt public header */ + #ifndef HH_ParseInt_ #define HH_ParseInt_ 1 diff --git a/Packets/ParseInt.ih b/Packets/ParseInt.ih index 1cacbd6..80b8d7f 100644 --- a/Packets/ParseInt.ih +++ b/Packets/ParseInt.ih @@ -20,6 +20,9 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +/** \file + \brief ParseInt internal header */ + #ifndef IH_ParseInt_ #define IH_ParseInt_ 1 diff --git a/Packets/ParseList.hh b/Packets/ParseList.hh index 80a5d89..8e82f06 100644 --- a/Packets/ParseList.hh +++ b/Packets/ParseList.hh @@ -39,7 +39,23 @@ namespace senf { template class Parse_List_Container; - /** \brief + /** \brief Arbitrary sequential element collection + + A List is a sequential collection of elements. The element type is given as an arbitrary + parser. The list is more flexible than a vector: It is not limited to fixed-size elements + and it might not have direct access to the size of the collection. + + The cost is however, that a List is only a model of an STL forward sequence. The parser + provides a reduced interface to this sequence, the container wrapper provides the complete + interface. + + Pare_List makes use of a policy template argument, \a ListPolicy, to customize the way the + list is laid out. This policy is given quite some freedom in the list + implementation. It is however important, that list elements always follow each other + without padding (if padding is needed, it needs to be part of the element parser). + + \see ExampleListPolicy + \ingroup parsecollection */ template class Parse_List @@ -49,6 +65,9 @@ namespace senf { public: Parse_List(data_iterator i, state_type s); Parse_List(ListPolicy policy, data_iterator i, state_type s); + ///< Additional policy specific constructor + /**< This constructor may be used, if the policy needs + additional parameters. */ size_type bytes() const; void init() const; @@ -84,7 +103,7 @@ namespace senf { template friend class Parse_List_Container; }; - /** \brief Exmaple of a list policy. ONLY FOR EXPOSITION. + /** \brief Example of a list policy. ONLY FOR EXPOSITION. 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: @@ -125,7 +144,7 @@ namespace senf { \endcode If necessary, you may use a different policy in the container_type. The ListPolicy must - define the elements bytes(), size() and init(), the container policy needs all theese and + define the elements bytes(), size() and init(), the container policy needs all these and additionally needs erase() and insert(). The container policy will also need the element_type, parser_type and container_type typedefs. @@ -156,7 +175,7 @@ namespace senf { size_type bytes(iterator i, state_type s) const; ///< Size of list in bytes /**< Return the complete size of the list in - bytes. Depending on the type of list, thie call may + bytes. Depending on the type of list, this call may need to completely traverse the list ... */ size_type size(iterator i, state_type s) const; ///< Number of elements in list @@ -173,13 +192,13 @@ namespace senf { void erase(iterator i, state_type s, iterator p) const; ///< Erase element from list /**< Delete the list element at p from the List (i,s). When this operation is called, the element is still part of - the list. This call must update the metadata as + the list. This call must update the meta-data as needed. The data will be removed after this call returns. */ void insert(iterator i, state_type s, iterator p) const; ///< Insert element into list /**< This is called after an element has been inserted at p - into the List (i,s) to update the metadata. */ + into the List (i,s) to update the meta-data. */ /** \brief Example of a list iterator policy. ONLY FOR EXPOSITION. @@ -234,6 +253,24 @@ namespace senf { }; }; + /** \brief Parse_List container wrapper + + This is the container wrapper used for list 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::aListCollection_t::container c (p->aListCollection()); + c.insert(c.begin(), ... ); + \endcode + + \see Parse_List + */ template class Parse_List_Container : private ListPolicy diff --git a/Packets/ParseList.ih b/Packets/ParseList.ih index b005b6b..83f1009 100644 --- a/Packets/ParseList.ih +++ b/Packets/ParseList.ih @@ -32,6 +32,10 @@ namespace senf { namespace detail { + /** \brief Internal: Iterator used by Parse_List + + \internal + */ template class Parse_List_Iterator : public boost::iterator_facade< Parse_List_Iterator, diff --git a/Packets/ParseListB.hh b/Packets/ParseListB.hh index 72b5159..f3506c5 100644 --- a/Packets/ParseListB.hh +++ b/Packets/ParseListB.hh @@ -38,10 +38,10 @@ namespace senf { /** \brief List parser with size-field in bytes This list parser will parse a list which size is given by a preceding field containing the - lenght of the list in bytes. This struct is just a template typedef: + length of the list in bytes. This struct is just a template typedef: \code - typedef senf::Parse_VectorN< Parser_UInt32, Parser_UInt16 >::parser Parse_MyVector; - typedef senf::Parse_ListB< Parse_MyVector, Parse_UInt16 >::parser Parse_MyList; + typedef senf::Parse_VectorN< Parser_UInt32, Parser_UInt16 >::parser Parse_MyVector; + typedef senf::Parse_ListB< Parse_MyVector, Parse_UInt16 >::parser Parse_MyList; \endcode This first defines a Vector of 32 bit unsigned integers with 16 bit length counter. Then it defines a list of such vectors with a 16 bit bytes field. @@ -49,13 +49,16 @@ namespace senf { \warning There are some caveats when working with this kind of list \li You may only change the size of a contained element from a container wrapper. \li While you hold a container wrapper, only access the packet through this wrapper - or a nested wrepper either for reading or writing. + or a nested wrapper either for reading or writing. If lists are nested, you need to allocate a container wrapper for each level and may only access the packet through the lowest-level active container wrapper. \implementation These restrictions are necessary to ensure correct recalculation of the bytes field. For more info, see the comments in \ref ParseListB.ih + + \see Parse_List + \ingroup parsecollection */ template struct Parse_ListB { diff --git a/Packets/ParseListB.ih b/Packets/ParseListB.ih index 3a44d7c..081e3d3 100644 --- a/Packets/ParseListB.ih +++ b/Packets/ParseListB.ih @@ -31,7 +31,7 @@ namespace senf { namespace detail { - /** \brief ListPolicy defing the Parse_ListB parser + /** \brief Internal: ListPolicy defing the Parse_ListB parser \internal \see \ref Parse_ListB */ @@ -76,7 +76,10 @@ namespace detail { size_type bytes (iterator i, state_type s) const; size_type size (iterator i, state_type s) const; void init (iterator i, state_type s) const; - + + /** \brief Internal: Parse_ListB_Policy's iterator policy + \internal + */ struct iterator_policy { iterator setBegin (iterator i, state_type s); @@ -86,6 +89,9 @@ namespace detail { iterator raw (iterator i, state_type s) const; }; + /** \brief Internal: Parse_ListB_Policy's container policy + \internal + */ struct container_policy { typedef typename Parse_ListB_Policy< diff --git a/Packets/ParseListN.hh b/Packets/ParseListN.hh index 8dc2243..9151a61 100644 --- a/Packets/ParseListN.hh +++ b/Packets/ParseListN.hh @@ -1,3 +1,4 @@ + // Copyright (C) 2007 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS) // Kompetenzzentrum fuer Satelitenkommunikation (SatCom) @@ -35,6 +36,20 @@ namespace senf { namespace detail { template class Parse_ListN_Policy; } + /** \brief List parser with size-field giving number of list elements + + This parser will parse a list which size is giving by a preceding field containing the + number of list elements. This struct is just a 'template typedef': + \code + senf::Parse_VectorN< Parser_UInt32, Parser_UInt16 >::parser Parse_MyVector; + senf::Parse_ListN< Parse_MyVector, Parse_UInt16 >::parser Parse_MyList; + \endcode + This first defines a Vector of 32 bit unsigned integers with 16 bit length counter. Then it + defines a list of such vectors with a 16 bit size field. + + \see Parse_List + \ingroup parsecollection + */ template struct Parse_ListN { typedef Parse_List< detail::Parse_ListN_Policy > parser; diff --git a/Packets/ParseListN.ih b/Packets/ParseListN.ih index e6da33a..57a5cb4 100644 --- a/Packets/ParseListN.ih +++ b/Packets/ParseListN.ih @@ -31,6 +31,10 @@ namespace senf { namespace detail { + /** \brief Internal: ListPolicy defining the Parse_ListN parser + \internal + \see \ref Parse_ListN + */ template struct Parse_ListN_Policy { @@ -50,6 +54,9 @@ namespace detail { void insert (iterator i, state_type s, iterator p) const; void update (iterator i, state_type s) const; + /** \brief Iternal: Parse_ListN_Policy's iterator policy + \internal + */ struct iterator_policy { iterator setBegin (iterator i, state_type s); diff --git a/Packets/ParseVec.ct b/Packets/ParseVec.ct index de1f131..64493eb 100644 --- a/Packets/ParseVec.ct +++ b/Packets/ParseVec.ct @@ -20,7 +20,8 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -// Definition of non-inline template funPacketRegistry.ons +/** \file + \brief ParseVec non-inline template implementation */ #include "ParseVec.ih" diff --git a/Packets/ParseVec.cti b/Packets/ParseVec.cti index b50e50b..14ac2d6 100644 --- a/Packets/ParseVec.cti +++ b/Packets/ParseVec.cti @@ -20,7 +20,8 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -// Definition of inline template functions +/** \file + \brief ParseVec inline template implementation */ #include "ParseVec.ih" diff --git a/Packets/ParseVec.hh b/Packets/ParseVec.hh index b9ee51b..f979f42 100644 --- a/Packets/ParseVec.hh +++ b/Packets/ParseVec.hh @@ -20,6 +20,9 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +/** \file + \brief ParseVec public header */ + #ifndef HH_ParseVec_ #define HH_ParseVec_ 1 @@ -47,7 +50,7 @@ namespace senf { 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 + 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. @@ -203,6 +206,8 @@ namespace senf { SomePacket::aVectorCollection_t::container c (p->aVectorCollection()); c.insert(c.begin(), ... ); \endcode + + \see Parse_Vector */ template class Parse_Vector_Container diff --git a/senf.dict b/senf.dict index 7830258..d3b22f4 100644 --- a/senf.dict +++ b/senf.dict @@ -1,5 +1,6 @@ accessor addtogroup +aListCollection aVectorCollection BaseParser berlios @@ -28,6 +29,7 @@ EthernetPacketType EthernetParser ethertype EthVLan +ExampleListPolicy ExampleVectorPolicy ExtendedParser findNext @@ -41,6 +43,7 @@ hideinitializer href html http +ih impl INet ingroup @@ -58,9 +61,13 @@ key Kommunikationssysteme Kompetenzzentrum li +ListB +ListN +ListPolicy MACAddress mainpage mixin +MyList MyVector namespace NextPacket @@ -98,6 +105,9 @@ ParseArray parsecollection parseint ParseInt +ParseList +ParseListB +ParseListN parseNextAs ParseVec png @@ -114,6 +124,9 @@ SafePacketParser SatCom Satelitenkommunikation senf +setBegin +setEnd +setFromPosition SimplePacketType SimpleVectorSizer SizeParser diff --git a/senfscons/SENFSCons.py b/senfscons/SENFSCons.py index 4b32ae2..13be755 100644 --- a/senfscons/SENFSCons.py +++ b/senfscons/SENFSCons.py @@ -408,7 +408,8 @@ def Doxygen(env, doxyfile = "Doxyfile", extra_sources = []): " --stringparam module $MODULE" + " --stringparam type $TYPE" + " ${SOURCES[1]} $SOURCE || touch $TARGET" ], - MODULE = xmlnode.dir.dir.dir.name, + MODULE = xmlnode.dir.dir.dir.abspath[ + len(env.Dir('#').abspath)+1:], TYPE = type) env.SideEffect(xref, xmlnode) env.AddPreAction(docs, "rm -f %s" % (xref,))