X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=senf%2FPackets%2FPacket.hh;h=4e6147f0d75f007cac2b2f37389eed10736f2f76;hb=ddb2132be4265f8a0d7d4c954c7c9401e59d027c;hp=57a0f218e621648e07fc4715e883c552ef88ca63;hpb=26610f603ebdd465307b9621f532c1fe19fd5571;p=senf.git diff --git a/senf/Packets/Packet.hh b/senf/Packets/Packet.hh index 57a0f21..4e6147f 100644 --- a/senf/Packets/Packet.hh +++ b/senf/Packets/Packet.hh @@ -2,23 +2,28 @@ // // Copyright (C) 2007 // Fraunhofer Institute for Open Communication Systems (FOKUS) -// Competence Center NETwork research (NET), St. Augustin, GERMANY -// Stefan Bund // -// This program is free software; you can redistribute it and/or modify -// it under the terms of the GNU General Public License as published by -// the Free Software Foundation; either version 2 of the License, or -// (at your option) any later version. +// The contents of this file are subject to the Fraunhofer FOKUS Public License +// Version 1.0 (the "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// http://senf.berlios.de/license.html // -// This program is distributed in the hope that it will be useful, -// but WITHOUT ANY WARRANTY; without even the implied warranty of -// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -// GNU General Public License for more details. +// The Fraunhofer FOKUS Public License Version 1.0 is based on, +// but modifies the Mozilla Public License Version 1.1. +// See the full license text for the amendments. // -// You should have received a copy of the GNU General Public License -// along with this program; if not, write to the -// Free Software Foundation, Inc., -// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +// Software distributed under the License is distributed on an "AS IS" basis, +// WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License +// for the specific language governing rights and limitations under the License. +// +// The Original Code is Fraunhofer FOKUS code. +// +// The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V. +// (registered association), Hansastraße 27 c, 80686 Munich, Germany. +// All Rights Reserved. +// +// Contributor(s): +// Stefan Bund /** \file \brief Packet public header */ @@ -30,13 +35,12 @@ #include #include #include -#include #include #include #include "PacketInterpreter.hh" //#include "Packet.mpp" -///////////////////////////////hh.p//////////////////////////////////////// +//-///////////////////////////////////////////////////////////////////////////////////////////////// namespace senf { @@ -97,7 +101,7 @@ namespace senf { template class ConcretePacket; ///\addtogroup packet_module - ///@{ + //\{ /** \brief Main %Packet class @@ -143,7 +147,7 @@ namespace senf { public boost::equality_comparable { public: - /////////////////////////////////////////////////////////////////////////// + //-//////////////////////////////////////////////////////////////////////// // Types typedef void type; ///< Type of the packet. @@ -151,9 +155,9 @@ namespace senf { ///< Unsigned type to represent packet size typedef PacketInterpreterBase::factory_t factory_t; ///< Packet factory type (see below) - /////////////////////////////////////////////////////////////////////////// + //-//////////////////////////////////////////////////////////////////////// ///\name Structors and default members - ///@{ + //\{ // default copy constructor // default copy assignment @@ -165,163 +169,169 @@ namespace senf { validity. */ Packet clone() const; ///< Create copy packet /**< clone() will create a complete copy of \c this - packet. The returned packet will have the same data and - packet chain. It does however not share any data with - the original packet. */ + packet. The returned packet will have the same data, + annotations and packet chain. It does however not + share any data with the original packet. */ // 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. */ - ///@} - /////////////////////////////////////////////////////////////////////////// + //\} + //-//////////////////////////////////////////////////////////////////////// ///\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 + /**< \returns in - valid() packet if no next packet + exists or if next() packet is not of + type \a OtherPacket */ 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 + /**< \returns in - valid() packet if no previous packet + exists or if the previous packet is not of + type \a OtherPacket */ 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 */ + template OtherPacket as(NoThrow_t) 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. + \warning You must make absolutely sure that the packet + is of the given type. If not, calling this member + crashes your program in a unkindly way. */ 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. */ + + void reparse() const; ///< Reparse the payload the packet + /**< This member will throw away the packet chain after the + current packet. The payload will be reparsed + automatically when calling next() */ + //\} ///\name Data access - ///@{ + //\{ PacketData & data() const; ///< Access the packets raw data container size_type size() const; ///< Return size of packet in bytes /**< This size does \e not include the size of any preceding headers/packets/interpreters. It does however include \c this packets payload. */ - - ///@} + //\} ///\name Annotations - ///@{ + //\{ template Annotation & annotation(); ///< Get packet annotation @@ -331,9 +341,9 @@ namespace senf { struct. \code - struct MyAnnotation { + struct MyAnnotation { int value; - }; + }; senf::Packet p (...); @@ -352,11 +362,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 @@ -380,14 +390,19 @@ namespace senf { considering that the packetimpl itself uses a pool. */ - ///@} - template Annotation const & annotation() const; ///< Get packet annotation /**< \see annotation() */ + void clearAnnotations(); ///< Clear all packet annotations + /**< All packet annotations will be cleared. Afterwards + the annotations equates to a new created %packet. + \warning all references to existing complex + annotations become invalid. */ + //\} + ///\name Other methods - ///@{ + //\{ bool operator==(Packet const & other) const; ///< Check for packet identity /**< Two packet handles compare equal if they really are the @@ -403,7 +418,7 @@ namespace senf { when using a packet in a boolean context. */ void finalizeThis(); ///< Update calculated fields - /**< The finalize() fammily of members will update + /**< The finalize() family 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 @@ -418,7 +433,7 @@ namespace senf { template void finalizeTo(); ///< Update calculated fields - /**< The finalize() fammily of members will update + /**< The finalize() family 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 @@ -437,7 +452,7 @@ namespace senf { \endcode */ void finalizeTo(Packet const & other); ///< Update calculated fields - /**< The finalize() fammily of members will update + /**< The finalize() family 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 @@ -449,7 +464,7 @@ namespace senf { backwards towards outer packets up to \c this. */ void finalizeAll(); ///< Update calculated fields - /**< The finalize() fammily of members will update + /**< The finalize() family 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 @@ -490,18 +505,22 @@ namespace senf { 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.. */ + id, they share the internal data representation. */ + + bool is_shared() const; ///< check if this packet shares data with any another packet handle. + /**< This method returns true if there is any other packet + handle pointing to any header in the packet chain. */ - ///@} + //\} 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; - Packet checkLast() const; + Packet getNext() const; + Packet getLast() const; PacketInterpreterBase::ptr packet_; @@ -525,15 +544,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 @@ -547,15 +571,15 @@ namespace senf { : public Packet { public: - /////////////////////////////////////////////////////////////////////////// + //-//////////////////////////////////////////////////////////////////////// // Types typedef PacketType type; typedef typename PacketType::parser Parser; - /////////////////////////////////////////////////////////////////////////// + //-//////////////////////////////////////////////////////////////////////// ///\name Structors and default members - ///@{ + //\{ // default copy constructor // default copy assignment @@ -563,40 +587,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 +629,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,41 +689,60 @@ 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 uninitialized 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 ConcretePacket clone() const; - ///@} - /////////////////////////////////////////////////////////////////////////// + //\} + //-//////////////////////////////////////////////////////////////////////// // Field access @@ -720,23 +763,23 @@ namespace senf { access. The parser class may have any member which is needed for full packet access (e.g. checksum validation / recreation ...) - \see \ref packetparser for the parser interface. */ + \see \ref packetparser for the %parser interface. */ Parser parser() const; ///< Access packet field parser directly /**< Access the parser of the packet. This is the same object returned by the operator->() operator. The operator however does not allow to access this object itself, only it's members. - \see \ref packetparser for the parser interface */ + \see \ref packetparser for the %parser interface */ protected: private: typedef PacketInterpreter interpreter; - ConcretePacket(typename interpreter::ptr packet_); + ConcretePacket(typename interpreter::ptr const & packet_); - typename interpreter::ptr ptr() const; + interpreter * ptr() const; friend class Packet; friend class PacketInterpreter; @@ -751,11 +794,11 @@ namespace senf { template Parser operator<<(Parser target, ConcretePacket const & packet); - ///@} + //\} } -///////////////////////////////hh.e//////////////////////////////////////// +//-///////////////////////////////////////////////////////////////////////////////////////////////// #endif #if !defined(HH_SENF_Packets_Packets__decls_) && !defined(HH_SENF_Packets_Packet_i_) #define HH_SENF_Packets_Packet_i_ @@ -764,7 +807,7 @@ namespace senf { #include "Packet.cti" #endif - + // Local Variables: // mode: c++ // fill-column: 100