X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=senf%2FPackets%2FPacket.hh;h=4698dd349457e975c904b34cac2ff97dc2ee44b9;hb=9bc655e14d2d8c204ed835896cb51e42d49bd68f;hp=57a0f218e621648e07fc4715e883c552ef88ca63;hpb=26610f603ebdd465307b9621f532c1fe19fd5571;p=senf.git diff --git a/senf/Packets/Packet.hh b/senf/Packets/Packet.hh index 57a0f21..4698dd3 100644 --- a/senf/Packets/Packet.hh +++ b/senf/Packets/Packet.hh @@ -30,7 +30,6 @@ #include #include #include -#include #include #include #include "PacketInterpreter.hh" @@ -172,10 +171,11 @@ namespace senf { // conversion constructors template - Packet(ConcretePacket packet); ///< Copy-construct Packet from ConcretePacket - /**< This constructor allows to convert an arbitrary - ConcretePacket into a general Packet, loosing the - protocol specific interface. */ + Packet(ConcretePacket const & packet); + ///< Copy-construct Packet from ConcretePacket + /**< This constructor allows to convert an arbitrary + ConcretePacket into a general Packet, loosing the + protocol specific interface. */ ///@} /////////////////////////////////////////////////////////////////////////// @@ -183,129 +183,124 @@ namespace senf { ///\name Interpreter chain access ///@{ - Packet next() const; - ///< Get next packet in chain - /**< \throws InvalidPacketChainException if no next packet - exists */ - Packet next(NoThrow_t) const; - ///< Get next packet in chain - /**< \returns in - valid() packet if no next packet - exists */ + Packet next() const; ///< Get next packet in chain + /**< \throws InvalidPacketChainException if no next packet + exists */ + Packet next(NoThrow_t) const; ///< Get next packet in chain + /**< \returns in - valid() packet if no next packet + exists */ 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 */ + ///< 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; - ///< Get next packet in chain and cast to \a OtherPacket - /**< \throws std::bad_cast if the next() packet is not of - type \a OtherPacket - \returns in - valid() packet if no next packet - exists */ + ///< Get next packet in chain and cast to \a OtherPacket + /**< \throws std::bad_cast if the next() packet is not of + type \a OtherPacket + \returns in - valid() packet if no next packet + exists */ template OtherPacket find() const; - ///< Search chain forward for packet of type \a OtherPacket - /**< The search will start with the current packet. - \throws InvalidPacketChainException if no packet of - type \a OtherPacket can be found. */ + ///< Search chain forward for packet of type \a OtherPacket + /**< The search will start with the current packet. + \throws InvalidPacketChainException if no packet of + type \a OtherPacket can be found. */ template OtherPacket find(NoThrow_t) const; - ///< Search chain forward for packet of type \a OtherPacket - /**< 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; - ///< Get previous packet in chain - /**< \throws InvalidPacketChainException if no previous - packet exists */ - Packet prev(NoThrow_t) const; - ///< Get previous packet in chain - /**< \returns in - valid() packet if no previous packet - exists */ + ///< Search chain forward for packet of type \a OtherPacket + /**< 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; ///< Get previous packet in chain + /**< \throws InvalidPacketChainException if no previous + packet exists */ + Packet prev(NoThrow_t) const; ///< Get previous packet in chain + /**< \returns in - valid() packet if no previous packet + exists */ 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 */ + ///< 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; - ///< 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 - exists */ + ///< 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 + exists */ template OtherPacket rfind() const; - ///< Search chain backwards for packet of type \a OtherPacket - /**< The search will start with the current packet. - \throws InvalidPacketChainException if no packet of - type \a OtherPacket can be found. */ + ///< Search chain backwards for packet of type \a OtherPacket + /**< The search will start with the current packet. + \throws InvalidPacketChainException if no packet of + type \a OtherPacket can be found. */ template OtherPacket rfind(NoThrow_t) const; - ///< Search chain backwards for packet of type \a OtherPacket - /**< The search will start with the current packet. - \returns in - valid() packet if no packet of type \a - OtherPacket can be found. */ + ///< Search chain backwards for packet of type \a OtherPacket + /**< The search will start with the current packet. + \returns in - valid() packet if no packet of type \a + OtherPacket can be found. */ - Packet first() const; - ///< Return first packet in chain + Packet first() const; ///< Return first packet in chain template OtherPacket first() const; - ///< Return first packet in chain and cast - /**< \throws std::bad_cast if the first() packet is not of - type \a OtherPacket */ + ///< Return first packet in chain and cast + /**< \throws std::bad_cast if the first() packet is not of + type \a OtherPacket */ - Packet last() const; - ///< Return last packet in chain + Packet last() const; ///< Return last packet in chain template OtherPacket last() const; - ///< Return last packet in chain and cast - /**< \throws std::bad_cast if the last() packet is not of - type \a OtherPacket */ + ///< Return last packet in chain and cast + /**< \throws std::bad_cast if the last() packet is not of + type \a OtherPacket */ template OtherPacket parseNextAs() const; - ///< Interpret payload of \c this as \a OtherPacket - /**< parseNextAs() will throw away the packet chain after - the current packet if necessary. It will then parse the - payload section of \c this packet as given by \a - 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. - \throws InvalidPacketChainException if no next - packet header is allowed (viz. nextPacketRange() of the the current - PacketType returns no_range() ) */ + ///< Interpret payload of \c this as \a OtherPacket + /**< parseNextAs() will throw away the packet chain after + the current packet if necessary. It will then parse the + payload section of \c this packet as given by \a + 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. + \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 - the current packet if necessary. It will then parse the - payload section of \c this packet as given by \a - 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. - \throws InvalidPacketChainException if no next - packet header is allowed (viz. nextPacketRange() of the the current - PacketType returns no_range() ) */ + ///< Interpret payload of \c this as \a factory type packet + /**< parseNextAs() will throw away the packet chain after + the current packet if necessary. It will then parse the + payload section of \c this packet as given by \a + 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. + \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 + ///< 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 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 */ + ///< Cast current packet to the given type + /**< This operations returns a handle to the same packet + 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 */ Packet append(Packet const & packet) const; ///< Append the given packet to \c this packet - /**< This operation will replace the payload section of \c - this packet with \a packet. This operation will replace - the packet chain after \c this packet with a clone of - \a packet and will replace the raw data of the payload - of \c this with the raw data of \a packet. \c this - packet will not share any date with \a packet. - \returns Packet handle to the cloned \a packet, placed - after \c this in the packet/header/interpreter - chain. */ + /**< This operation will replace the payload section of \c + this packet with \a packet. This operation will replace + the packet chain after \c this packet with a clone of + \a packet and will replace the raw data of the payload + of \c this with the raw data of \a packet. \c this + packet will not share any data with \a packet. + \returns Packet handle to the cloned \a packet, placed + after \c this in the packet/header/interpreter + chain. */ ///@} @@ -331,9 +326,9 @@ namespace senf { struct. \code - struct MyAnnotation { + struct MyAnnotation { int value; - }; + }; senf::Packet p (...); @@ -352,11 +347,11 @@ namespace senf { lead to a program crash. \code - struct MyStringAnnotation : senf::ComplexAnnotation { + struct MyStringAnnotation : senf::ComplexAnnotation { std::string value; - }; + }; \endcode - (This type is not POD since \c std::string is not POD) + (This type is not POD since \c std::string is not POD) \see \ref packet_usage_annotation @@ -495,9 +490,9 @@ namespace senf { ///@} protected: - explicit Packet(PacketInterpreterBase::ptr packet); + explicit Packet(PacketInterpreterBase::ptr const & packet); - PacketInterpreterBase::ptr ptr() const; + PacketInterpreterBase::ptr const & ptr() const; private: Packet checkNext() const; @@ -525,15 +520,20 @@ namespace senf { \li The create() family of constructors will create completely new packets. \li The createAfter() family of constructors will create new packets (with new data for the - packet) \e after a given existing packet. - \li The createBefore() family of constructors will create new packets (again with new data) - \e before a given existing packet. + packet) \e after a given existing packet thereby destroying and overwriting any + possibly existing packets and data after the given packet. + \li The createBefore() family of constructors will create new packets (again with new data) + \e before a given existing packet thereby destroying and overwriting any possibly + existing packets and data before the given packet. + \li The createInsertBefore() family of constructors will create new packets \e before a + given packet \e inserting them into the packet chain after any existing packets before + the given packet. Whereas create() will create a completely new packet with it's own chain and data storage, - createAfter() and createBefore() extend a packet with additional + createAfter(), createBefore() and createInsertBefore() 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. + packet whereas createBefore() and createInsertBefore() will create a new packet with the + existing packet as it's 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 @@ -563,40 +563,40 @@ namespace senf { // no conversion constructors ConcretePacket(); ///< Create uninitialized packet handle - /**< An uninitialized handle is not valid(). It does not - allow any operation except assignment and checking for - validity. */ + /**< An uninitialized handle is not valid(). It does not + allow any operation except assignment and checking for + validity. */ static factory_t factory(); ///< Return factory for packets of specific type - /**< This \e static member is like Packet::factory() for a - specific packet of type \a PacketType */ + /**< This \e static member is like Packet::factory() for a + specific packet of type \a PacketType */ // Create completely new packet static ConcretePacket create(); ///< Create default initialized packet - /**< The packet will be initialized to it's default empty - state. */ + /**< The packet will be initialized to it's default empty + state. */ static ConcretePacket create(senf::NoInit_t); ///< Create uninitialized empty packet - /**< This will create a completely empty and uninitialized - packet with size() == 0. - \param[in] senf::noinit This parameter must always have the - value \c senf::noinit. */ + /**< This will create a completely empty and uninitialized + packet with size() == 0. + \param[in] senf::noinit This parameter must always have + the value \c senf::noinit. */ static ConcretePacket create(size_type size); ///< Create default initialized packet - /**< This member will create a default initialized packet - with the given size. If the size parameter is smaller - than the minimum allowed packet size an exception will - be thrown. - \param[in] size Size of the packet to create in bytes. - \throws TruncatedPacketException if \a size is smaller - than the smallest permissible size for this type of - packet. */ + /**< This member will create a default initialized packet + with the given size. If the size parameter is smaller + than the minimum allowed packet size an exception will + be thrown. + \param[in] size Size of the packet to create in bytes. + \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); - ///< Create uninitialized packet - /**< Creates an uninitialized (all-zero) packet of the exact - 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. */ + ///< Create uninitialized packet + /**< Creates an uninitialized (all-zero) packet of the exact + 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. */ #ifndef DOXYGEN template static ConcretePacket create( @@ -605,56 +605,56 @@ namespace senf { #else template 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 - of data to construct packet from. */ + ///< 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 + of data to construct packet from. */ #endif // Create packet as new packet after a given 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 - after \a packet in that packets interpreter chain. - \param[in] packet Packet to append new packet to. */ + ///< 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 + after \a packet in that packets interpreter chain. + \param[in] packet Packet to append new packet to. */ static ConcretePacket createAfter(Packet const & packet, senf::NoInit_t); - ///< Create uninitialized empty packet after\a packet - /**< This will create a completely empty and uninitialized - packet with size() == 0. It will be appended - as next header/interpreter after \a packet in that - packets interpreter chain. - \param[in] packet Packet to append new packet to. - \param[in] senf::noinit This parameter must always have the - value \c senf::noinit. */ + ///< Create uninitialized empty packet after\a packet + /**< This will create a completely empty and uninitialized + packet with size() == 0. It will be appended + as next header/interpreter after \a packet in that + packets interpreter chain. + \param[in] packet Packet to append new packet to. + \param[in] senf::noinit This parameter must always have + the value \c senf::noinit. */ static ConcretePacket createAfter(Packet const & packet, size_type size); - ///< Create default initialized packet after \a packet - /**< This member will create a default initialized packet - with the given size. If the size parameter is smaller - than the minimum allowed packet size an exception will - be thrown. It will be appended as next - header/interpreter after \a packet in that packets - interpreter chain. - \param[in] packet Packet to append new packet to. - \param[in] size Size of the packet to create in bytes. - \throws TruncatedPacketException if \a size is smaller - than the smallest permissible size for this type of - packet. */ + ///< Create default initialized packet after \a packet + /**< This member will create a default initialized packet + with the given size. If the size parameter is smaller + than the minimum allowed packet size an exception will + be thrown. It will be appended as next + header/interpreter after \a packet in that packets + interpreter chain. + \param[in] packet Packet to append new packet to. + \param[in] size Size of the packet to create in bytes. + \throws TruncatedPacketException if \a size is smaller + than the smallest permissible size for this type of + packet. */ static ConcretePacket createAfter(Packet const & packet, size_type size, senf::NoInit_t); - ///< Create uninitialized packet after \a packet - /**< Creates an uninitialized (all-zero) packet of the exact - given size. It will be appended as next - header/interpreter after \a packet in that packets - interpreter chain. - \param[in] packet Packet to append new packet to. - \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. */ + ///< Create uninitialized packet after \a packet + /**< Creates an uninitialized (all-zero) packet of the exact + given size. It will be appended as next + header/interpreter after \a packet in that packets + interpreter chain. + \param[in] packet Packet to append new packet to. + \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. */ #ifndef DOXYGEN template static ConcretePacket createAfter( @@ -665,34 +665,53 @@ namespace senf { template 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 - data. The data from the range will be copied directly - into the packet representation. The data will \e not be - validated in any way. It will be appended as next - header/interpreter after \a packet in that packets - interpreter chain. - \param[in] packet Packet to append new packet to. - \param[in] range Boost.Range - of data to construct packet from. */ + ///< Create packet from given data after \a packet + /**< 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. It will be appended as next + header/interpreter after \a packet in that packets + interpreter chain. + \param[in] packet Packet to append new packet to. + \param[in] range 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); - ///< Create default initialized packet before \a packet - /**< The packet will be initialized to it's default empty - state. It 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 default initialized packet before \a packet + /**< The packet will be initialized to it's default empty + state. It will be prepended as previous + header/interpreter before \a packet in that packets + interpreter chain. + \warning This constructor will destroy any existing + headers before \a packet and replace them with the + new header. + \param[in] packet Packet to prepend new packet to. */ static ConcretePacket createBefore(Packet const & packet, senf::NoInit_t); - ///< Create uninitialized empty packet before \a packet - /**< Creates a completely empty and uninitialized packet. It - 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 uninitialized empty packet before \a packet + /**< Creates a completely empty and uninitialized packet. It + will be prepended as previous header/interpreter before + \a packet in that packets interpreter chain. + \warning This constructor will destroy any existing + headers before \a packet and replace them with the + new header. + \param[in] packet Packet to prepend new packet to. */ + + static ConcretePacket createInsertBefore(Packet const & packet); + ///< Insert default initialized packet before \a packet + /**< The new packet header will be initialized to it' s + default empty state. It will be inserted into the + packet chain before \a packet. + \param[in] packet Packet before which to insert the new + packet */ + static ConcretePacket createInsertBefore(Packet const & packet, senf::NoInit_t); + ///< Insert uninitialized empty packet before \a packet + /**< Inserts a completely empty and unitialized packet + before \a packet into the header/interpreter chain. + \param[in] packet Packet before which to insert the new + packet */ // Create a clone of the current packet @@ -734,7 +753,7 @@ namespace senf { private: typedef PacketInterpreter interpreter; - ConcretePacket(typename interpreter::ptr packet_); + ConcretePacket(typename interpreter::ptr const & packet_); typename interpreter::ptr ptr() const; @@ -764,7 +783,7 @@ namespace senf { #include "Packet.cti" #endif - + // Local Variables: // mode: c++ // fill-column: 100