// $Id$
//
-// Copyright (C) 2006
+// Copyright (C) 2006
// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
// Stefan Bund <stefan.bund@fokus.fraunhofer.de>
// 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.
+/** \file
+ \brief Main packet interface
-// 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 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: Document the additional concrete Packet facade requirements
-// explicitly and not only within the Parser requirements (check(),
-// bytes() and min_bytes() members ...)
+ \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: 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.
+ \todo Document the additional concrete Packet facade requirements
+ explicitly and not only within the Parser requirements (check(),
+ bytes() and min_bytes() members ...)
-/** \file
- \brief Main packet interface
+ \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_
// ////////////////////////////hh.p////////////////////////////////////////
namespace senf {
-
+
namespace impl { template <class OtherPacket> 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. senf::Packet manages the necessary memory
- resources and controlls the chain of packet interpreters.
+ 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
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(),
- You must implement a static check() method which validates
a byte region as your new Packet
- \code
- class ExamplePacket
+ \code
+ class ExamplePacket
: public senf::Packet
{
public:
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
{
// check does not need to be implemented here, it is
- // inherited from the parser
+ // inherited from the parser
private:
template <class InputIterator>
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
senf::deque_list) could be used to support zero-copy
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.
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).
///////////////////////////////////////////////////////////////////////////
///\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.
*/
Every derived class \e must redeclare this member for it's
derived type:
- \code
+ \code
typedef ptr_t<DerivedClass>::ptr ptr
\endcode
*/
- typedef ptr_t<Packet>::ptr ptr;
+ typedef ptr_t<Packet>::ptr ptr;
typedef raw_container::iterator iterator; //!< raw data iterator
typedef raw_container::size_type size_type;
typedef raw_container::difference_type difference_type;
///@{
/** \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.
\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 <class OtherPacket, class InputIterator>
///\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;
/** \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 */
OtherPacket. \e Assert's, that a packet of this type exists */
template <class OtherPacket> typename ptr_t<OtherPacket>::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 <class OtherPacket> bool is() const;
+ template <class OtherPacket> 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 <class OtherPacket> typename ptr_t<OtherPacket>::ptr as();
+ template <class OtherPacket> typename ptr_t<OtherPacket>::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</b>. 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 <class OtherPacket>
///\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
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
// 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
derived packet instance. This method is mostly to be used
by the derived class implementation and their helper
classes. */
- template <class InputIterator>
+ template <class InputIterator>
void insert(iterator pos, InputIterator f, InputIterator l, Whence whence = AUTO);
/** \brief erase single byte
///@{
/** \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
template <class Operation>
Packet(Operation const & arg);
virtual ~Packet();
-
+
private:
/** \brief create next packet interpreter
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;
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:
\f
// Local Variables:
// mode: c++
+// fill-column: 100
// c-file-style: "senf"
+// indent-tabs-mode: nil
+// ispell-local-dictionary: "american"
// End: