// conversion constructors
template <class PacketType>
- Packet(ConcretePacket<PacketType> packet); ///< Copy-construct Packet from ConcretePacket
+ Packet(ConcretePacket<PacketType> const & packet);
+ ///< Copy-construct Packet from ConcretePacket
/**< This constructor allows to convert an arbitrary
ConcretePacket into a general Packet, loosing the
protocol specific interface. */
exists */
template <class OtherPacket> 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 */
+ /**< \returns in - valid() packet if no next packet
+ exists or if next() packet is not of
+ type \a OtherPacket */
template <class OtherPacket> OtherPacket find() const;
///< Search chain forward for packet of type \a OtherPacket
/**< The search will start with the current packet.
packet exists */
template <class OtherPacket> 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 */
+ /**< \returns in - valid() packet if no previous packet
+ exists or if the previous packet is not of
+ type \a OtherPacket */
template <class OtherPacket> OtherPacket rfind() const;
///< Search chain backwards for packet of type \a OtherPacket
/**< The search will start with the current packet.
Packet first() const; ///< Return first packet in chain
- template <class OtherPacket> OtherPacket first() const;
+ template <class OtherPacket> OtherPacket first() const;
///< Return first packet in chain and cast
/**< \throws std::bad_cast if the first() packet is not of
type \a OtherPacket */
before.
\throws std::bad_cast if the current packet is not of
type \a OtherPacket */
+ template <class OtherPacket> 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
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.
+ 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
/**< This size does \e not include the size of any preceding
headers/packets/interpreters. It does however include
\c this packets payload. */
-
///@}
///\name Annotations
considering that the packetimpl itself uses a pool.
*/
- ///@}
-
template <class Annotation>
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
///@{
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
template <class Other>
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
\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
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_;
\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 <em>thereby destroying and overwriting any
+ possibly existing packets and data after the given packet</em>.
+ \li The createBefore() family of constructors will create new packets (again with new data)
+ \e before a given existing packet <em>thereby destroying and overwriting any possibly
+ existing packets and data before the given packet</em>.
+ \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
into the packet representation. The data will \e not be
validated in any way.
- \param[in] range <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a>
+ \param[in] range <a href="http://www.boost.org/doc/libs/release/libs/range/index.html">Boost.Range</a>
of data to construct packet from. */
#endif
header/interpreter after \a packet in that packets
interpreter chain.
\param[in] packet Packet to append new packet to.
- \param[in] range <a href="http://www.boost.org/libs/range/index.html">Boost.Range</a>
+ \param[in] range <a href="http://www.boost.org/doc/libs/release/libs/range/index.html">Boost.Range</a>
of data to construct packet from. */
#endif
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.
+ \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
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<PacketType> 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<PacketType>;