X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=senf%2FPackets%2FPacket.hh;h=8b116e6978cf0f0331387c80110b43e30678c369;hb=80550046686fc160f5d7ff076f1b167a13538466;hp=d6dc393f62207e0760d9e0ab083cb115af1860e0;hpb=3a43b572a2c0028b353d47e86fa7546633d6e2cf;p=senf.git diff --git a/senf/Packets/Packet.hh b/senf/Packets/Packet.hh index d6dc393..8b116e6 100644 --- a/senf/Packets/Packet.hh +++ b/senf/Packets/Packet.hh @@ -164,14 +164,15 @@ 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 + 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. */ @@ -196,10 +197,9 @@ namespace senf { 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 */ + /**< \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. @@ -225,10 +225,9 @@ namespace senf { 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 */ + /**< \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. @@ -242,7 +241,7 @@ namespace senf { Packet first() const; ///< Return first packet in chain - template OtherPacket first() const; + 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 */ @@ -289,6 +288,15 @@ namespace senf { 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 @@ -301,6 +309,10 @@ namespace senf { 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 @@ -311,7 +323,6 @@ 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 @@ -374,12 +385,17 @@ 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 ///@{ @@ -397,7 +413,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 @@ -412,7 +428,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 @@ -431,7 +447,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 @@ -484,18 +500,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_; @@ -610,7 +630,7 @@ namespace senf { into the packet representation. The data will \e not be validated in any way. - \param[in] range Boost.Range + \param[in] range Boost.Range of data to construct packet from. */ #endif @@ -672,7 +692,7 @@ namespace senf { header/interpreter after \a packet in that packets interpreter chain. \param[in] packet Packet to append new packet to. - \param[in] range Boost.Range + \param[in] range Boost.Range of data to construct packet from. */ #endif @@ -738,23 +758,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;