X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Packets%2FPacket.hh;h=ff3daa83920569ad2cd9aee959191b4ebe745dcb;hb=1a29b75bf774444ec182dfff8480a0c53597bf85;hp=8cff10857a46c82e42f7a77eea63618064f50500;hpb=1a02a61e1e1515dca27577013cc7300ea5133fd5;p=senf.git diff --git a/Packets/Packet.hh b/Packets/Packet.hh index 8cff108..ff3daa8 100644 --- a/Packets/Packet.hh +++ b/Packets/Packet.hh @@ -59,7 +59,7 @@ namespace senf { (This is, why we call the data structure interpreter and not header: The interpreter is responsible for interpreting a range of the packet according to a specific protocol), the packet interpreters are nested inside each other. - + For each interpreter, this structure automatically divides the packet into three areas (each of which are optional): The header, the payload and the trailer. Every packet will have either a header or a payload section while most don't have a trailer. @@ -98,7 +98,7 @@ namespace senf { ///\addtogroup packet_module ///@{ - + /** \brief Main %Packet class %Packet is the main externally visible class of the packet library. %Packet is a handle into @@ -111,12 +111,12 @@ namespace senf { class extending %Packet is provided. \section packet_semantics Semantics - + All operations accessing the data of \c this packet in some way will ignore any preceding packets/headers/interpreters in the chain. It does not matter, whether a given packet is taken from the middle or the beginning of the chain, all operations (except those explicitly accessing the chain of course) should work the same. - + This especially includes members like clone() or append(): clone() will clone \e only from \c this packet until the end of the chain, append() will append the given packet \e ignoring any possibly preceding packets/headers/interpreters. @@ -133,7 +133,7 @@ namespace senf { instantiations (Example: \ref EthernetPacket is a typedef for \ref ConcretePacket < \ref EthernetPacketType >). - \see + \see \ref ConcretePacket for the %type specific interface\n \ref PacketData for the sequence interface\n \ref packetparser for a specification of the parser interface @@ -145,7 +145,7 @@ namespace senf { public: /////////////////////////////////////////////////////////////////////////// // Types - + typedef void type; ///< Type of the packet. typedef senf::detail::packet::size_type size_type; ///< Unsigned type to represent packet size @@ -158,7 +158,7 @@ namespace senf { // default copy constructor // default copy assignment // default destructor - + Packet(); ///< Create uninitialized packet handle /**< An uninitialized handle is in - valid(). It does not allow any operation except assignment and checking for @@ -171,7 +171,7 @@ namespace senf { // conversion constructors - template + template Packet(ConcretePacket packet); ///< Copy-construct Packet from ConcretePacket /**< This constructor allows to convert an arbitrary ConcretePacket into a general Packet, loosing the @@ -183,21 +183,21 @@ namespace senf { ///\name Interpreter chain access ///@{ - Packet next() const; + Packet next() const; ///< Get next packet in chain - /**< \throws InvalidPacketChainException if no next packet + /**< \throws InvalidPacketChainException if no next packet exists */ - Packet next(NoThrow_t) const; + Packet next(NoThrow_t) const; ///< Get next packet in chain - /**< \returns in - valid() packet if no next packet + /**< \returns in - valid() packet if no next packet exists */ - template OtherPacket next() const; + template OtherPacket next() const; ///< Get next packet in chain and cast to \a OtherPacket /**< \throws std::bad_cast if the next() packet is not of type \a OtherPacket \throws InvalidPacketChainException if no next packet exists */ - template OtherPacket next(NoThrow_t) const; + template OtherPacket next(NoThrow_t) const; ///< Get next packet in chain and cast to \a OtherPacket /**< \throws std::bad_cast if the next() packet is not of type \a OtherPacket @@ -213,26 +213,26 @@ namespace senf { /**< The search will start with the current packet. \returns in - valid() packet if no packet of type \a OtherPacket can be found. */ - - Packet prev() const; + + Packet prev() const; ///< Get previous packet in chain /**< \throws InvalidPacketChainException if no previous packet exists */ - Packet prev(NoThrow_t) const; + Packet prev(NoThrow_t) const; ///< Get previous packet in chain /**< \returns in - valid() packet if no previous packet exists */ - template OtherPacket prev() const; + template OtherPacket prev() const; ///< Get previous packet in chain and cast to \a OtherPacket /**< \throws std::bad_cast, if the previous packet is not of type \a OtherPacket \throws InvalidPacketChainException if no previous packet exists */ - template OtherPacket prev(NoThrow_t) const; + template OtherPacket prev(NoThrow_t) const; ///< Get previous packet in chain and cast to \a OtherPacket /**< \throws std::bad_cast, if the previous packet is not of type \a OtherPacket - \returns in - valid() packet if no previous packet + \returns in - valid() packet if no previous packet exists */ template OtherPacket rfind() const; ///< Search chain backwards for packet of type \a OtherPacket @@ -269,7 +269,10 @@ namespace senf { OtherPacket. The new packet is added to the chain after \c this. \returns new packet instance sharing the same data and - placed after \c this packet in the chain. */ + placed after \c this packet in the chain. + \throws InvalidPacketChainException if no next + packet header is allowed (viz. nextPacketRange() of the the current + PacketType returns no_range() ) */ Packet parseNextAs(factory_t factory) const; ///< Interpret payload of \c this as \a factory type packet /**< parseNextAs() will throw away the packet chain after @@ -278,15 +281,18 @@ namespace senf { factory. The new packet is added to the chain after \c this. \returns new packet instance sharing the same data and - placed after \c this packet in the chain. */ + placed after \c this packet in the chain. + \throws InvalidPacketChainException if no next + packet header is allowed (viz. nextPacketRange() of the the current + PacketType returns no_range() ) */ template bool is() const; ///< Check, whether \c this packet is of the given type template OtherPacket as() const; ///< Cast current packet to the given type /**< This operations returns a handle to the same packet - header/interpreter however cast to the given - ConcretePacket type. + header/interpreter however upcast to the given + ConcretePacket type which have been instantiated before. \throws std::bad_cast if the current packet is not of type \a OtherPacket */ @@ -311,7 +317,7 @@ namespace senf { /**< This size does \e not include the size of any preceding headers/packets/interpreters. It does however include \c this packets payload. */ - + ///@} ///\name Annotations @@ -330,10 +336,10 @@ namespace senf { }; senf::Packet p (...); - + p.annotation().value = 1; \endcode - + Annotations are shared by all headers / interpreters within a single packet chain. @@ -362,7 +368,7 @@ namespace senf { used). Additionally, non-complex small annotations require no additional memory management (\c new / \c delete). - + \idea Pool the annotation vectors: In the destructor swap the vector into a vector graveyard (swapping two vectors is an O(1) no allocation operation). In @@ -384,15 +390,15 @@ namespace senf { ///@{ bool operator==(Packet const & other) const; ///< Check for packet identity - /**< Two packet handles compare equal if they really are the - same packet header in the same packet chain. */ + /**< Two packet handles compare equal if they really are the + same packet header in the same packet chain. */ bool boolean_test() const; ///< Check, whether the packet is valid() /**< \see valid() */ bool valid() const; ///< Check, whether the packet is valid() /**< An in - valid() packet does not allow any operation except checking for validity and assignment. in - - valid() packets serve the same role as 0-pointers. - + valid() packets serve the same role as 0-pointers. + This is an alias for boolean_test() which is called when using a packet in a boolean context. */ @@ -423,24 +429,24 @@ namespace senf { packets/headers/interpreters from the \e first occurrence of packet type \a Other (beginning at \c this packet searching forward towards deeper nested - packets) backwards up to \c this. - + packets) backwards up to \c this. + This call is equivalent to \code p.finalizeTo(p.next()) \endcode */ void finalizeTo(Packet const & other); ///< Update calculated fields - /**< The finalize() fammily of members will update - calculated packet fields: checksums, size fields and so - on. This includes any field, which can be set from - other information in the packet. Each concrete packet - type should document, which fields are set by - finalize(). + /**< The finalize() fammily of members will update + calculated packet fields: checksums, size fields and so + on. This includes any field, which can be set from + other information in the packet. Each concrete packet + type should document, which fields are set by + finalize(). - finalizeTo(other) will automatically process all - packets/headers/interpreters beginning at \a other - backwards towards outer packets up to \c this. */ + finalizeTo(other) will automatically process all + packets/headers/interpreters beginning at \a other + backwards towards outer packets up to \c this. */ void finalizeAll(); ///< Update calculated fields /**< The finalize() fammily of members will update @@ -452,35 +458,39 @@ namespace senf { finalizeAll() will automatically process all packets/headers/interpreters from the end of the chain - (the most inner packet) backwards up to \c this. + (the most inner packet) backwards up to \c this. This call is equivalent to \code p.finalizeTo(p.last()) - \endcode + \endcode Beware, that finalizeAll() will \e not finalize any headers before \c this, it will \e only process inner headers. */ void dump(std::ostream & os) const; ///< Write out a printable packet representation - /**< This method is provided mostly to help debugging packet - problems. Each concrete packet should implement a dump - method writing out all fields of the packet in a - readable representation. dump() will call this member - for each packet/header/interpreter in the chain from \c - this packet up to the end of the chain. */ - - TypeIdValue typeId() const; ///< Get id of \c this packet - /**< This value is used e.g. in the packet registry to - associate packet types with other information. - \returns A type holding the same information as a - type_info object, albeit assignable */ + /**< This method is provided mostly to help debugging packet + problems. Each concrete packet should implement a dump + method writing out all fields of the packet in a + readable representation. dump() will call this member + for each packet/header/interpreter in the chain from \c + this packet up to the end of the chain. */ + + TypeIdValue typeId() const; ///< Get type of \c this packet + /**< This value is used e.g. in the packet registry to + associate packet types with other information. + \returns A type holding the same information as a + type_info object, albeit assignable */ factory_t factory() const; ///< Return factory instance of \c this packet - /**< The returned factory instance can be used to create new - packets of the given type without knowing the concrete - type of the packet. The value may be stored away for - later use if needed. */ + /**< The returned factory instance can be used to create new + packets of the given type without knowing the concrete + type of the packet. The value may be stored away for + later use if needed. */ + + unsigned long id() const; ///< Unique packet id + /**< Get a unique packet id. If two packets have the same + id, they share the internal data representation.. */ ///@} @@ -523,7 +533,7 @@ namespace senf { createAfter() and createBefore() extend a packet with additional headers/interpreters. createAfter() will set the payload of the given packet to the new packet whereas createBefore() will create a new packet with the existing packet as it's - payload. + payload. createAfter() differs from Packet::parseNextAs() in that the former creates a new packet \e replacing any possibly existing data whereas the latter will interpret the already \e @@ -533,7 +543,7 @@ namespace senf { PacketType policy class. */ template - class ConcretePacket + class ConcretePacket : public Packet { public: @@ -580,10 +590,10 @@ namespace senf { \throws TruncatedPacketException if \a size is smaller than the smallest permissible size for this type of packet. */ - static ConcretePacket create(size_type size, senf::NoInit_t); + static ConcretePacket create(size_type size, senf::NoInit_t); ///< Create uninitialized packet /**< Creates an uninitialized (all-zero) packet of the exact - given size. + given size. \param[in] size Size of the packet to create in bytes \param[in] senf::noinit This parameter must always have the value \c senf::noinit. */ @@ -591,23 +601,23 @@ namespace senf { template static ConcretePacket create( ForwardReadableRange const & range, - typename boost::disable_if< boost::is_integral >::type * = 0); + typename boost::disable_if< boost::is_integral >::type * = 0); #else template - static ConcretePacket create(ForwardReadableRange const & range); + static ConcretePacket create(ForwardReadableRange const & range); ///< Create packet from given data /**< The packet will be created from a copy of the given data. The data from the range will be copied directly into the packet representation. The data will \e not be validated in any way. \param[in] range Boost.Range + href="http://www.boost.org/libs/range/index.html">Boost.Range of data to construct packet from. */ #endif // Create packet as new packet after a given packet - static ConcretePacket createAfter(Packet const & packet); + static ConcretePacket createAfter(Packet const & packet); ///< Create default initialized packet after \a packet /**< The packet will be initialized to it's default empty state. It will be appended as next header/interpreter @@ -648,12 +658,12 @@ namespace senf { #ifndef DOXYGEN template static ConcretePacket createAfter( - Packet const & packet, + Packet const & packet, ForwardReadableRange const & range, typename boost::disable_if< boost::is_integral >::type * = 0); #else template - static ConcretePacket createAfter(Packet const & packet, + static ConcretePacket createAfter(Packet const & packet, ForwardReadableRange const & range); ///< Create packet from given data after \a packet /**< The packet will be created from a copy of the given @@ -664,13 +674,13 @@ namespace senf { interpreter chain. \param[in] packet Packet to append new packet to. \param[in] range Boost.Range + href="http://www.boost.org/libs/range/index.html">Boost.Range of data to construct packet from. */ #endif // Create packet as new packet (header) before a given packet - static ConcretePacket createBefore(Packet const & packet); + static ConcretePacket createBefore(Packet const & packet); ///< Create default initialized packet before \a packet /**< The packet will be initialized to it's default empty state. It will be prepended as previous @@ -683,17 +693,17 @@ namespace senf { will be prepended as previous header/interpreter before \a packet in that packets interpreter chain. \param[in] packet Packet to prepend new packet to. */ - + // Create a clone of the current packet ConcretePacket clone() const; - + ///@} /////////////////////////////////////////////////////////////////////////// - + // Field access - - struct ParserProxy + + struct ParserProxy { ParserProxy(Parser const & p) : p_ (p) {} Parser * operator->() { return &p_; } @@ -704,7 +714,7 @@ namespace senf { /**< This operator allows to access the parsed fields of the packet using the notation packet->field(). The fields of the packet are specified by the PacketType's - \c parser member. + \c parser member. The members are not strictly restricted to simple field access. The parser class may have any member which is @@ -725,7 +735,7 @@ namespace senf { typedef PacketInterpreter interpreter; ConcretePacket(typename interpreter::ptr packet_); - + typename interpreter::ptr ptr() const; friend class Packet; @@ -754,7 +764,7 @@ namespace senf { #include "Packet.cti" #endif - + // Local Variables: // mode: c++ // fill-column: 100