Packet Class Reference
[Network Data Structures]

A datagram of some sort. More...

#include <Packet.h>

Inheritance diagram for Packet:

List of all members.

Public Member Functions
	Packet (const Packet &toCopy) throw ( UnseatedPacketUseException )
	Packet (const Timeval &time, uint32_t pktLen, uint32_t capLen, const u_char *data)
virtual Packet *	clone () const
Packet *	ghost ()
const Timeval &	getTimestamp (void) const
	get the timestamp of the packet
Timeval	getTimeDelta (void) const throw ( UnknownAttributeException )
	get the difference in timestamps between this packet and the previous one in the packet's context
uint32_t	getPacketLength (void) const
	get the length of the packet on the wire
uint32_t	getCapturedLength (void) const
	get the number of bytes of the packet captured
uint32_t	getDataLength (void) const
	get the number of contiguous bytes of packet data returned by getPacketData
const u_char *	getPacketData (void) const
TraceIterator	getPrevPacket (void) const throw ( IndexOutOfBoundsException )
	get the next packet in this packet's context
TraceIterator	getNextPacket (void) const throw ( IndexOutOfBoundsException )
	get the previous packet in this packet's context
const std::vector< TraceIterator > &	getAncestors (void) const
	get a reference to the ancestors list
const std::vector< TraceIterator > &	getDescendants (void) const
	get a reference to the descendants list
const TraceIterator &	getContext (void) const
const PacketAttributeValue &	getAttrib (const PacketAttribute &attrib) const throw ( UnknownAttributeException )
	get the value of an attribute
const PacketAttributeValue &	getAttrib (const PacketAttribute &attrib, int direction) const throw ( UnknownAttributeException, InsufficientDataException )
	get the value of an attribute
virtual std::string	toString (void) const
u_char	operator[] (int index) const throw ( IndexOutOfBoundsException )
TraceIterator &	getRealPacket (void)
const TraceIterator &	getRealPacket (void) const
const u_char *	getData (uint32_t offset, uint32_t length) const throw ( IndexOutOfBoundsException )
virtual uint32_t	getPayloadOffset (void) const throw ( InsufficientDataException )
virtual uint32_t	getPayloadLength (void) const throw ( InsufficientDataException )
virtual uint32_t	getCapturedPayloadLength (void) const throw ( InsufficientDataException )
bool	addAncestor (const TraceIterator &it) throw ( UnseatedPacketUseException )
bool	addDescendant (const TraceIterator &it) throw ( UnseatedPacketUseException )
void	removeAncestor (const TraceIterator &it)
void	removeDescendant (const TraceIterator &it)
void	setContext (const TraceIterator &it)
bool	setData (const TraceIterator &it, uint32_t offset, uint32_t length)
bool	setData (const u_char *pktData, uint32_t length)
Static Public Attributes
static const int	ATTRIB_SEARCH_FORWARD = 1
static const int	ATTRIB_SEARCH_BACKWARD = 2
static const int	ATTRIB_SEARCH_BOTH = 3
Protected Member Functions
virtual const PacketAttributeValue &	getAttribLocal (const PacketAttribute &attrib) const throw ( UnknownAttributeException, InsufficientDataException )

---

Detailed Description

A datagram of some sort.

At the moment, Packet is being used as both a superclass for other packet types, and as a basic "raw packet" datatype. It may be useful to seperate out the latter functionality, though it doesn't appear necessary at this time.

Packets are tightly coupled with Aggregates; a Packet should not generally be constructed without an Aggregate to contain it.

---

Constructor & Destructor Documentation

Packet::Packet (  const Packet &  toCopy  )  throw ( UnseatedPacketUseException )

For Packet, the copy c-tor is a little funky. If the packet is being ghosted, the 'ghosting' flag will be set in toCopy, and the ctor should behave appropriately. Otherwise, the copy ctor assumes that a new packet is being spawned, and will link it in to the parent packet as a descendant. The reason it is done in such an awkward way is to make it transparent to subclasses; the subclass' clone() method should just call the copy ctor, and not worry about ghosting. Note that this ctor will not set the new packet as a descendant of the original packet; that will have to be done manually or by setData(). Parameters: [in]  toCopy  Packet to copy/ghost Exceptions: UnseatedPacketUseException  - attempt to ghost a packet which has not been added to a trace (see the description of UnseatedPacketUseException for more explanation)

Packet::Packet (  const Timeval &  time, uint32_t  pktLen, uint32_t  capLen, const u_char *  data )

Create a new Packet with the specified fields. It will be assumed that this is a brand new packet, not derived from another one; if that is not the case, use one of the constructors that takes a TraceIterator of the original packet from which the new one will be a derivative. Parameters: [in]  time  Timestamp of the new packet [in]  pktLen  Length of the packet on the wire (or best guess) [in]  capLen  Number of bytes of the packet that were captured [in]  data  actual data of the packet

---

Member Function Documentation

bool Packet::addAncestor (  const TraceIterator &  it  )  throw ( UnseatedPacketUseException )

add a reference to an ancestor packet from which this packet was derived Parameters: it  TraceIterator pointing to the ancestor to be added Note: will automatically fetch the 'real' packet for the ancestor, in case 'it' is a ghost packet

bool Packet::addDescendant (  const TraceIterator &  it  )  throw ( UnseatedPacketUseException )

add a reference to a descendant packet derived from this one Parameters: it  TraceIterator pointing to the ancestor to be added Note: will automatically fetch the 'real' packet for the descendant and for the current packet, in case 'it' or this are ghost packets

Packet * Packet::clone (   )  const [virtual]

clone() creates a copy of this packet NOTE: packet relationships are not copied Reimplemented in CHDLCPacket, EthernetPacket, IPv4Packet, LLCPacket, NullPacket, TCPPacket, and UDPPacket.

const PacketAttributeValue & Packet::getAttrib (  const PacketAttribute &  attrib, int  direction )  const throw ( UnknownAttributeException, InsufficientDataException )

get the value of an attribute If the attribute is not found locally, attempt to obtain it from the packet's ancestors.

const PacketAttributeValue & Packet::getAttrib (  const PacketAttribute &  attrib  )  const throw ( UnknownAttributeException )

get the value of an attribute If the attribute is not found locally, attempt to obtain it from the packet's ancestors. Exceptions: UnknownAttributeException  if either the attribute could not be found or if there was not enough data in the packet to compute it. Warning: The return value from getAttrib references a static local variable; this means that calling getAttrib more than once in a statement can cause nasty $#!+ to happen

const PacketAttributeValue & Packet::getAttribLocal (  const PacketAttribute &  attrib  )  const throw ( UnknownAttributeException, InsufficientDataException ) [protected, virtual]

get attributes specific to this particular type of Packet. For Packet, this does nothing, it's a placeholder for subclasses to override. For fans of the gang of four, this corresponds to the "template method" design pattern, IIRC. Parameters: attrib  PacketAttribute specifying what information is requested Reimplemented in CHDLCPacket, EthernetPacket, IPv4Packet, LLCPacket, NullPacket, TCPPacket, and UDPPacket.

uint32_t Packet::getCapturedPayloadLength (  void   )  const throw ( InsufficientDataException ) [virtual]

return the length of the actual payload part of the packet, i.e. captured packet length less the current layer's header Exceptions: InsufficientDataException  if there was not enough data captured to compute the value

const u_char * Packet::getData (  uint32_t  offset, uint32_t  length )  const throw ( IndexOutOfBoundsException )

get a pointer to the raw data of the packet. Parameters: [in]  offset  - start of requested data relative to the start of this packet [in]  length  - number of bytes requested Throws an IndexOutOfBoundsException if either offset or offset+length are out of bounds for this packet. Notes: DO NOT keep this pointer hanging around, it may point into the packet data which may be swapped out to disk without warning. DO NOT try to access data beyond what you've requested, there's no guarantee it'll be what you expect it to be.

TraceIterator Packet::getNextPacket (  void   )  const throw ( IndexOutOfBoundsException )

get the previous packet in this packet's context Exceptions: IndexOutOfBoundsException  if there is no previous packet

uint32_t Packet::getPayloadLength (  void   )  const throw ( InsufficientDataException ) [virtual]

return the length of the payload part of the packet, i.e. packet length on the wire less the current layer's header Exceptions: InsufficientDataException  if there was not enough data captured to compute the value

uint32_t Packet::getPayloadOffset (  void   )  const throw ( InsufficientDataException ) [virtual]

return the offset of the payload part of the packet, i.e. less the current layer's header Exceptions: InsufficientDataException  if there was not enough data captured to compute the value Reimplemented in CHDLCPacket, EthernetPacket, IPv4Packet, LLCPacket, NullPacket, TCPPacket, and UDPPacket.

TraceIterator Packet::getPrevPacket (  void   )  const throw ( IndexOutOfBoundsException )

get the next packet in this packet's context Exceptions: IndexOutOfBoundsException  if there is no next packet

TraceIterator & Packet::getRealPacket (  void   )

Obtain a reference to a TraceIterator over the real Packet represented by this Packet. That may be this packet itself, or it may be another packet if this one is a ghost.

Timeval Packet::getTimeDelta (  void   )  const throw ( UnknownAttributeException )

get the difference in timestamps between this packet and the previous one in the packet's context Exceptions: UnknownAttributeException  thrown if there is no previous packet

Packet * Packet::ghost (   )

ghost() creates a ghost copy of this packet NOTE: Should be const, but cannot be, with the current implementation of ghosting.

u_char Packet::operator[] (  int  index  )  const throw ( IndexOutOfBoundsException )

the public operator[] does not allow modifications Parameters: [in]  index  index of byte requested Throws an IndexOutOfBoundsException if index is out of bounds for this packet.

void Packet::removeAncestor (  const TraceIterator &  it  )

remove a specified ancestor from this packet's family tree. Notes: AKA historical revisionism. Intended to be called during destruction to tidy up references between traces, just in case.

void Packet::removeDescendant (  const TraceIterator &  it  )

remove a specified descendant from this packet's family. Notes: AKA changing the will. Intended to be called during destruction to tidy up references between traces, just in case.

void Packet::setContext (  const TraceIterator &  it  )

set the 'context' of the packet - i.e. where it lives Notes: generally set to the return value of Trace::addPacket() when this is added to a Trace

bool Packet::setData (  const u_char *  pktData, uint32_t  length )

set the data of the packet (i.e. including the header) to the given data; forces a copy. This is the preferred form for reassembled packets.

bool Packet::setData (  const TraceIterator &  it, uint32_t  offset, uint32_t  length )

set the data of the packet (i.e. including the header) to the given substring of another packet. Notes: This mechanism should allow us to make real packets that function as overlays on the data of other packets, without having to copy the data repeatedly. e.g. have a TCPPacket that refers to a substring of an IPv4Packet, which itself refers to a substring of an EthernetPacket, so that all three Packets refer to segments of the same byte array. Currently just makes a copy, however

---

Member Data Documentation

const int Packet::ATTRIB_SEARCH_BACKWARD = 2 [static]

Attribute search is to be performed backwards in the hierarchy - called by a descendant

const int Packet::ATTRIB_SEARCH_BOTH = 3 [static]

Attribute search is to be performed both forward and backwards in the hierarchy

const int Packet::ATTRIB_SEARCH_FORWARD = 1 [static]

Attribute search is to be performed forward in the hierarchy - called by an ancestor

---

The documentation for this class was generated from the following files:

• data_structures/Packet.h
• data_structures/Packet.cc

---