X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=senf%2FPackets%2FPacket.hh;h=af001a5f34dbcdc92b3e94832c495e7dfa0d29f2;hb=51b24c3227717ce5ad8111a99c2d7eea5fa0bd8d;hp=25d0f56a4227934fee280876819e9a9e2f25c329;hpb=a0b6f53e5c464c6b84fed30a67fcce32da81012d;p=senf.git diff --git a/senf/Packets/Packet.hh b/senf/Packets/Packet.hh index 25d0f56..af001a5 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 */ @@ -35,7 +40,7 @@ #include "PacketInterpreter.hh" //#include "Packet.mpp" -///////////////////////////////hh.p//////////////////////////////////////// +//-///////////////////////////////////////////////////////////////////////////////////////////////// namespace senf { @@ -96,7 +101,7 @@ namespace senf { template class ConcretePacket; ///\addtogroup packet_module - ///@{ + //\{ /** \brief Main %Packet class @@ -142,7 +147,7 @@ namespace senf { public boost::equality_comparable { public: - /////////////////////////////////////////////////////////////////////////// + //-//////////////////////////////////////////////////////////////////////// // Types typedef void type; ///< Type of the packet. @@ -150,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 @@ -164,9 +169,9 @@ 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 @@ -177,11 +182,11 @@ namespace senf { 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 @@ -197,10 +202,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. @@ -226,10 +230,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. @@ -290,6 +293,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 @@ -302,21 +314,24 @@ 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 - ///@{ + //\{ 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 @@ -375,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 @@ -398,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 @@ -413,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 @@ -432,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 @@ -444,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 @@ -485,19 +505,24 @@ 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 const & packet); PacketInterpreterBase::ptr const & ptr() const; - private: - Packet checkNext() const; - Packet checkLast() const; + Packet parseNextAs(factory_t factory, PacketInterpreterBase::optional_range const & range) const; + Packet getNext(PacketInterpreterBase::optional_range const & range) const; + Packet getLast() const; + private: PacketInterpreterBase::ptr packet_; template @@ -547,15 +572,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 @@ -611,7 +636,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 @@ -673,7 +698,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 @@ -708,7 +733,7 @@ namespace senf { packet */ static ConcretePacket createInsertBefore(Packet const & packet, senf::NoInit_t); ///< Insert uninitialized empty packet before \a packet - /**< Inserts a completely empty and unitialized 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 */ @@ -717,8 +742,8 @@ namespace senf { ConcretePacket clone() const; - ///@} - /////////////////////////////////////////////////////////////////////////// + //\} + //-//////////////////////////////////////////////////////////////////////// // Field access @@ -739,23 +764,27 @@ 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: +#ifndef DOXYGEN + using Packet::next; + + Packet next(NoThrow_t) const; +#endif private: typedef PacketInterpreter interpreter; ConcretePacket(typename interpreter::ptr const & packet_); - typename interpreter::ptr ptr() const; + interpreter * ptr() const; friend class Packet; friend class PacketInterpreter; @@ -770,11 +799,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_