X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Packets%2FPacket.hh;h=dd913d6a59087cddf7e4f40c4b912c6f5097778c;hb=9a988902090d28007578e93bffd809f6bd913155;hp=ef25f14b4002410450d0865cc6a97f03fadd5fb3;hpb=c52cd7d87dbb525c1267aad27391b8b7365dbb57;p=senf.git diff --git a/Packets/Packet.hh b/Packets/Packet.hh index ef25f14..dd913d6 100644 --- a/Packets/Packet.hh +++ b/Packets/Packet.hh @@ -1,6 +1,6 @@ // $Id$ // -// Copyright (C) 2006 +// Copyright (C) 2006 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS) // Kompetenzzentrum fuer Satelitenkommunikation (SatCom) // Stefan Bund @@ -20,102 +20,25 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -// TODO: Implement assign() method akin to reinterpret(). However, -// instead of using the data already present, assign() will replace -// the date of the current packet with the given Packet. - -// TODO: Implement wrapping-constructor. Somehow we want to have a -// constructor, which allows creating a chain of packet interpreters -// with as little overhead as possible. - -// TODO: Document the additional concrete Packet facade requirements -// explicitly and not only within the Parser requirements (check(), -// bytes() and min_bytes() members ...) - -// TODO: Implement special container replacing vector which manages -// some headroom to allow efficient insertion of elements at the -// beginning. This really is just another type of deque -// implementation. - - -/** \mainpage The SatCom Packet Framework - - \section arch Overall Architecture - - The general Architecture of the Packet Framework (pkf for short) - is seperated into two components: The basic packet handling and - the parser framework. - - The basic packet handling implements a packet interpreter - chain. Every packet is represented as a chain of interpreters - where each interpreter is a facade looking into the same - packet. Each interpreter will interpret a specific header of a - packet. For example, an ethernet frame might have an interpreter - chain consisting of EthernetPacket, IPPacket, UDPPacket and - DataPacket. Each of these interpreters will interpret a section of - the raw data bytes. The interpreter ranges overlap since every - packet also includes it's payload. - - The parser framework is used to interpret the raw bytes of a - specific packet and parse the values present in that packet. For - example, Parse_Ethernet will parse the ethernet source MAC, - destination MAC and ethertype given any random access iterator to - the first byte of the ethernet frame. Parsers are extremely light - classes. They are temporary classes passed around by value. In - most cases, they are just comprised of a single pointer adorned - with type information. - - \section handling Packet Handling - - The packet handling is implemented within - satcom::pkf::Packet. This class is the baseclass to all packet - interpreter facades. To implement a new packet type, publically - derive from satcom::pkf::Packet and implement the virtual - interface (see the class documentation for details). - - \section framework Parser Framework - - The parser framework provides an abstract framwork to parse packet - oriented data. A Parser is a template class taking an arbitrary - iterator as input and allowing random access to data elements of - the interpreted type, like source and destination MAC of an - ethernet frame. The parser framework is to be used hierarchically - and recursively, the parser methods should return further parsers - which can return further parsers and so on. - - The parser framework contains some basic parsers to be used to - build up more complex parsers: - - - ParseInt.hh: Lots of parsers for integer numbers like - satcom::pkf::Parse_UInt8, for integer bitfields like - satcom::pkf::Parse_UIntField and satcom::pkf::Parse_Flag to - parse boolean flags. - - - ParseArray.hh: The satcom::pkf::Parse_Array parser to parse - arbitrary fixed-size arrays of fixed-size elements (that is - sub-parsers). - - - ParseVec.hh: The satcom::pkf::Parse_Vector parser to parse - dynamically sized arrays of fixed-size elements (that is - sub-parsers). - - See satcom::pkf::ParserBase for further information. - - \section stuff Other Utilities - - The pkf also comprises some additional utilities to support the - development of packet classes. - - The satcom::pkf::PacketRegistry implements a registry of packets - keyed by an arbitrary type. The registry is used to find a packet - type given some kind of id (like the ethertype value from the - ethernet header). Together with it's support classes (especially - satcom::pkf::PacketRegistryMixin) this class greatly simplifies - implementing the needed table lookups. - */ - /** \file \brief Main packet interface + + \todo Implement assign() method akin to reinterpret(). However, + instead of using the data already present, assign() will replace + the date of the current packet with the given Packet. + + \todo Implement wrapping-constructor. Somehow we want to have a + constructor, which allows creating a chain of packet interpreters + with as little overhead as possible. + + \todo Document the additional concrete Packet facade requirements + explicitly and not only within the Parser requirements (check(), + bytes() and min_bytes() members ...) + + \todo Implement special container replacing vector which manages + some headroom to allow efficient insertion of elements at the + beginning. This really is just another type of dequeue + implementation. */ #ifndef HH_Packet_ @@ -133,20 +56,19 @@ #include "Packet.mpp" // ////////////////////////////hh.p//////////////////////////////////////// -namespace satcom { -namespace pkf { - +namespace senf { + namespace impl { template class PkReg_EntryImpl; } namespace impl { class PacketImpl; } /** \brief Basic interface to all packet facades \section packet_overview Overview - + This class is the base class of all Packets. It implements the generic Packet interface and provides the packet management - framework. satcom::pkf::Packet manages the necessary memory - resources and controlls the chain of packet interpreters. + framework. senf::Packet manages the necessary memory + resources and controls the chain of packet interpreters. The Packet user always interfaces with the pkf via a Packet derived class. This is the only external entity ever held by a @@ -154,16 +76,16 @@ namespace pkf { counted smart pointer, so resource management is quasi automatic. - \image html "../../structure.png" Overview - + \image html structure.png Overview + Internally, every Packet references a PacketImpl instance which manages the raw packet data and the interpreter list. This raw data is interpreted by the concrete Packet derived class - according to the definition of that derived class's packet + according to the definition of that derived classes packet type (i.e. EthernetPacket or UDPPacket). Packet provides several interfaces: - + - Creation of Packet instances: create() - Access to the chain of interpreters: next(), prev(), head(), @@ -193,9 +115,9 @@ namespace pkf { - You must implement a static check() method which validates a byte region as your new Packet - \code - class ExamplePacket - : public satcom::pkf::Packet + \code + class ExamplePacket + : public senf::Packet { public: typedef ptr_t::ptr ptr; @@ -210,7 +132,7 @@ namespace pkf { private: template ExamplePacket(Arg arg [, other args ... ]) - : satcom::pkf::Packet(arg) + : senf::Packet(arg) {} virtual void v_nextInterpreter() const @@ -225,17 +147,17 @@ namespace pkf { // calculate checksum etc } - friend class satcom::pkf::Packet; + friend class senf::Packet; }; \endcode Please do not implement the methods inline to not clutter up the header file. This is done here in the example to simplify it. If a class is to be registered in some - satcom:pkf::PacketRegistry, it must not take any additional + senf:PacketRegistry, it must not take any additional constructor parameters. - After having implemented the bare framework, the most comman + After having implemented the bare framework, the most common way to implement access to the packets specific data is to use the parser framework by additionally inheriting a corresponding parser. This also automatically implements the @@ -246,28 +168,28 @@ namespace pkf { \code class ExamplePacket - : public satcom::pkf::Packet, - public Parse_Example { // check does not need to be implemented here, it is - // inherited from the parser + // inherited from the parser private: template ExamplePacket(InputIterator begin, InputIterator end) - : satcom::pkf::Packet(begin,end) + : senf::Packet(begin,end) {} }; \endcode - See the satcom::pkf::ParserBase Documentation for how to + See the senf::ParserBase Documentation for how to implement Parse_Example. The implementation of v_nextInterpreter most of the time relies on some packet registry. This is simplified using the - satcom::pkf::PacketRegistryMixin class as follows. Again, we + senf::PacketRegistryMixin class as follows. Again, we only show the differences from the preceding Example: \code @@ -276,14 +198,14 @@ namespace pkf { }; class ExamplePacket - : public satcom::pkf::Packet, - public Parse_Example, - public satcom::pkf::PacketRegistryMixin { - using satcom::pkf::Packet::registerInterpreter; - using satcom::pkf::PacketRegsitryMixin::registerInterpreter; + using senf::Packet::registerInterpreter; + using senf::PacketRegsitryMixin::registerInterpreter; private: virtual void v_nextInterpreter() const { @@ -296,18 +218,18 @@ namespace pkf { \endcode For further details on the packet registry, see - satcom::pkf::PacketRegistry. + senf::PacketRegistry. \section packet_impl Implementation details The Packet interface is implemented to minimize overhead as far as possible without getting to complex. One area for - improvement ist the container class used to hold the raw + improvement is the container class used to hold the raw data. This currently is an \a std::vector. This could be - imporved by either allocating some headroom/tailroom in the + improved by either allocating some headroom/tailroom in the vector and using this when inserting data at the beginning or end. Alternatively, a new container class (like the - satcom::lib::deque_list) could be used to support zero-copy + senf::deque_list) could be used to support zero-copy semantics. At the moment, we leave the implementation at @@ -319,7 +241,7 @@ namespace pkf { we cannot construct the \a writev() data structures. The interpreter list managed by Packet is lazy, meaning packet - interpreter facades are added only when requestd by next(), + interpreter facades are added only when requested by next(), last() or find_next(). v_nextInterpreter() is called if necessary by these methods to complete the interpreter chain. @@ -333,11 +255,13 @@ namespace pkf { interpreter list to the Packet facades must not be counted. They are therefore implemented differently ( boost::shared_ptr vs. boost::intrusive_ptr). The choice of - boost::intrusive_ptr for the externaly visible smart pointer + boost::intrusive_ptr for the externally visible smart pointer for all Packet facades is taken to reduce the overhead (an intrusive_ptr is only the size of an ordinary pointer, a smart_ptr has the size of two pointers). + \fixme Make all data mutators protected + \nosubgrouping */ class Packet : boost::noncopyable @@ -358,7 +282,7 @@ namespace pkf { typedef std::vector raw_container; typedef boost::shared_ptr interpreter_list_ptr; - typedef std::list interpreter_list; + typedef std::list interpreter_list; typedef unsigned refcount_t; ///@} @@ -368,9 +292,9 @@ namespace pkf { /////////////////////////////////////////////////////////////////////////// ///\name Types ///@{ - + /** \brief smart pointer template for all Packet classes - + This struct is just a template typedef. It defines the smart pointer used for all Packet classes. */ @@ -380,11 +304,11 @@ namespace pkf { Every derived class \e must redeclare this member for it's derived type: - \code + \code typedef ptr_t::ptr ptr \endcode */ - typedef ptr_t::ptr ptr; + typedef ptr_t::ptr ptr; typedef raw_container::iterator iterator; //!< raw data iterator typedef raw_container::size_type size_type; typedef raw_container::difference_type difference_type; @@ -397,7 +321,7 @@ namespace pkf { ///@{ /** \brief create new Packet - + This method is used to create a new Packet. All Packet instances are created via this method, they are \e never created directly from the Packet derived class. @@ -409,7 +333,7 @@ namespace pkf { \param e corresponding end iterator \return smart pointer to new packet \throws TruncatedPacketException The data cannot be parsed - securely (the data might be trunctated or just + securely (the data might be truncated or just plain invalid) */ template @@ -425,7 +349,7 @@ namespace pkf { ///\name Interpreter chain ///@{ - + /** \brief get next packet from the interpreter chain \return smart pointer to next packet or 0 if last packet */ ptr next() const; @@ -438,7 +362,7 @@ namespace pkf { /** \brief get last packet of the interpreter chain \return smart pointer to last packet */ ptr last() const; - + /** \brief first packet of given type after the current packet \return smart pointer to first following packet of type \a OtherPacket or 0, if no such packet exists */ @@ -457,28 +381,28 @@ namespace pkf { OtherPacket. \e Assert's, that a packet of this type exists */ template typename ptr_t::ptr get_prev() const; - /** \brief check, wether the packet is of the given type - \return true, if packt is of type \a OtherPacket, false + /** \brief check, whether the packet is of the given type + \return true, if packet is of type \a OtherPacket, false otherwise */ - template bool is() const; + template bool is() const; /** \brief cast packet pointer to the given type \return a properly cast smart pointer if packet is of type \a OtherPacket. Otherwise return 0 */ - template typename ptr_t::ptr as(); + template typename ptr_t::ptr as(); /** \brief replace current packet interpreter This method will \e replace the current packet facade in the interpreter list with a new interpreter given by \a - OtherPacket. + OtherPacket. \attention This invalidates the packet instance \e - this. You must ensure, not to use the Packet instance - any further after this call + this. You must ensure, not to use the Packet instance any + further after this call \return smart pointer to a \e new packet facade \throws TruncatedPacketException there is not enough data - to savely interpret the packet as the given type. The + to safely interpret the packet as the given type. The original packet is \e not invalidated */ template @@ -489,8 +413,8 @@ namespace pkf { ///\name Raw packet data ///@{ - /** \brief begin interator of raw packet data - + /** \brief begin iterator of raw packet data + This iterator allows access to the raw data interpreted by the packet facade. This \e includes any header possibly interpreted by the derived packet instance. To access the @@ -500,7 +424,7 @@ namespace pkf { data */ iterator begin() const; /** \brief past-the-end iterator of raw packet data - + This iterator allows access to the raw data interpreted by the packet facade. This \e includes any header possibly interpreted by the derived packet instance. To access the @@ -517,8 +441,6 @@ namespace pkf { // Modifying the raw packet data - // FIXME: Make all data mutators protected - typedef enum { AUTO, BEFORE, INSIDE, OUTSIDE, AFTER } Whence; /** \brief insert single byte \a v before pos @@ -541,7 +463,7 @@ namespace pkf { derived packet instance. This method is mostly to be used by the derived class implementation and their helper classes. */ - template + template void insert(iterator pos, InputIterator f, InputIterator l, Whence whence = AUTO); /** \brief erase single byte @@ -568,7 +490,7 @@ namespace pkf { ///@{ /** \brief create new interpreter facade for an existing packet - + This constructor is called, when a new interpreter is to be added to the interpreter chain. The constructor is called indirectly from registerInterpreter() or @@ -578,7 +500,7 @@ namespace pkf { template Packet(Operation const & arg); virtual ~Packet(); - + private: /** \brief create next packet interpreter @@ -593,7 +515,7 @@ namespace pkf { instance. The new instance is automatically added to the interpreter chain after the current interpreter. - See also satcom::pkf::PacketRegistryMixin on how to + See also senf::PacketRegistryMixin on how to use a Registry to find the next interpreters implementing class. */ @@ -604,10 +526,10 @@ namespace pkf { This method is called by the packet framework to let the interpreter facade do some final calculations/packet cleanup before the packet is sent out or digested in some - other way. This is the place to calcaulate checksums and + other way. This is the place to calculate checksums and such. - This method is autmatically called for all interpreters on + This method is automatically called for all interpreters on the interpreter chain. */ virtual void v_finalize() = 0; @@ -649,16 +571,16 @@ namespace pkf { bool release(); bool unlink(); - struct PacketOp_register; - friend class PacketOp_register; + struct PacketOp_register; + friend class PacketOp_register; void i_registerInterpreter(Packet * p) const; - struct PacketOp_replace; - friend class PacketOp_replace; + struct PacketOp_replace; + friend class PacketOp_replace; void i_replaceInterpreter(Packet * p); - struct PacketOp_set; - friend class PacketOp_set; + struct PacketOp_set; + friend class PacketOp_set; void i_setInterpreter(impl::PacketImpl * i); private: @@ -689,7 +611,7 @@ namespace pkf { struct TruncatedPacketException : public std::exception { virtual char const * what() const throw() { return "truncated packet"; } }; -}} +} // ////////////////////////////hh.e//////////////////////////////////////// #include "Packet.cci" @@ -702,5 +624,8 @@ namespace pkf { // Local Variables: // mode: c++ -// c-file-style: "satcom" +// fill-column: 100 +// c-file-style: "senf" +// indent-tabs-mode: nil +// ispell-local-dictionary: "american" // End: