cPacket Class Reference

#include <cpacket.h>

Description

A subclass of cMessage to represent packets, frames, datagrams, application messages, and similar data.

cPacket adds length (measured in bits or bytes), bit error flag, and encapsulation capability to cMessage. Length and bit error flag are significant when the packet travels through a cDatarateChannel or another channel that supports data rate and/or error modelling.

cPacket is rarely used "as is". Typically the user wants to subclass it to create specific packet types for various protocols being modelled. The most convenient way to do that are via message declaration files (.msg), which are translated into C++ classes. An example message declaration:

packet Datagram
{
    int destAddr = -1; // destination address
    int srcAddr = -1;  // source address
    int ttl =  32;     // time to live
}

See also

cSimpleModule, cDatarateChannel, cPacketQueue

Inheritance diagram for cPacket:

Public Member Functions
Constructors, destructor, assignment
	cPacket (const cPacket &packet)
	cPacket (const char *name=nullptr, short kind=0, int64_t bitLength=0)
virtual	~cPacket ()
cPacket &	operator= (const cPacket &packet)
Redefined cObject/cMessage member functions.
virtual cPacket *	dup () const override
virtual std::string	str () const override
virtual void	forEachChild (cVisitor *v) override
virtual void	parsimPack (cCommBuffer *buffer) const override
virtual void	parsimUnpack (cCommBuffer *buffer) override
virtual bool	isPacket () const override
virtual const char *	getDisplayString () const override
Length and bit error flag
virtual void	setBitLength (int64_t l)
void	setByteLength (int64_t l)
virtual void	addBitLength (int64_t delta)
void	addByteLength (int64_t delta)
virtual int64_t	getBitLength () const
int64_t	getByteLength () const
virtual void	setBitError (bool e)
virtual bool	hasBitError () const
Message encapsulation.
virtual void	encapsulate (cPacket *packet)
virtual cPacket *	decapsulate ()
virtual cPacket *	getEncapsulatedPacket () const
virtual bool	hasEncapsulatedPacket () const
Transmission state
simtime_t_cref	getDuration () const
bool	isReceptionStart () const
Public Member Functions inherited from cMessage
	cMessage (const cMessage &msg)
	cMessage (const char *name=nullptr, short kind=0)
virtual	~cMessage ()
cMessage &	operator= (const cMessage &msg)
void	setKind (short k)
void	setTimestamp ()
void	setTimestamp (simtime_t t)
void	setContextPointer (void *p)
virtual void	setControlInfo (cObject *p)
cObject *	removeControlInfo ()
short	getKind () const
simtime_t_cref	getTimestamp () const
void *	getContextPointer () const
cObject *	getControlInfo () const
virtual cArray &	getParList ()
virtual cMsgPar &	addPar (const char *name)
virtual cMsgPar &	addPar (cMsgPar *par)
virtual cMsgPar &	par (int index)
virtual cMsgPar &	par (const char *name)
virtual int	findPar (const char *name) const
virtual bool	hasPar (const char *name) const
virtual cObject *	addObject (cObject *par)
virtual cObject *	getObject (const char *name)
virtual bool	hasObject (const char *name)
virtual cObject *	removeObject (const char *name)
virtual cObject *	removeObject (cObject *par)
bool	isSelfMessage () const
cModule *	getSenderModule () const
cGate *	getSenderGate () const
cModule *	getArrivalModule () const
cGate *	getArrivalGate () const
int	getSenderModuleId () const
int	getSenderGateId () const
int	getArrivalModuleId () const
int	getArrivalGateId () const
simtime_t_cref	getCreationTime () const
simtime_t_cref	getSendingTime () const
simtime_t_cref	getArrivalTime () const
bool	arrivedOn (int gateId) const
bool	arrivedOn (const char *gateName) const
bool	arrivedOn (const char *gateName, int gateIndex) const
long	getId () const
long	getTreeId () const
void	setArrival (int moduleId, int gateId)
void	setArrival (int moduleId, int gateId, simtime_t_cref t)
Public Member Functions inherited from cEvent
	cEvent (const cEvent &event)
	cEvent (const char *name)
virtual	~cEvent ()
cEvent &	operator= (const cEvent &event)
void	setSchedulingPriority (short p)
short	getSchedulingPriority () const
bool	isScheduled () const
simtime_t_cref	getArrivalTime () const
bool	shouldPrecede (const cEvent *event) const
Public Member Functions inherited from cOwnedObject
	cOwnedObject ()
	cOwnedObject (const char *name, bool namepooling=true)
	cOwnedObject (const cOwnedObject &obj)
virtual	~cOwnedObject ()
cOwnedObject &	operator= (const cOwnedObject &o)
virtual cObject *	getOwner () const override
virtual bool	isOwnedObject () const override
virtual bool	isSoftOwner () const
Public Member Functions inherited from cNamedObject
	cNamedObject ()
	cNamedObject (const char *name, bool namepooling=true)
	cNamedObject (const cNamedObject &obj)
virtual	~cNamedObject ()
cNamedObject &	operator= (const cNamedObject &o)
virtual void	setName (const char *s)
virtual const char *	getName () const override
virtual void	setNamePooling (bool b)
virtual bool	getNamePooling ()
Public Member Functions inherited from cObject
	cObject ()
	cObject (const cObject &other)
virtual	~cObject ()
virtual const char *	getClassName () const
bool	isName (const char *s) const
virtual const char *	getFullName () const
virtual std::string	getFullPath () const
const cObject *	getThisPtr () const
virtual _OPPDEPRECATED std::string	info () const
virtual _OPPDEPRECATED std::string	detailedInfo () const
cObject *	findObject (const char *name, bool deep=true)
void	copyNotSupported () const

Additional Inherited Members
Static Public Member Functions inherited from cMessage
static long	getTotalMessageCount ()
static long	getLiveMessageCount ()
static void	resetMessageCounters ()
Static Public Member Functions inherited from cOwnedObject
static long	getTotalObjectCount ()
static long	getLiveObjectCount ()
static void	resetObjectCounters ()
static cDefaultList *	getDefaultOwner ()
Protected Member Functions inherited from cObject
virtual void	take (cOwnedObject *obj)
virtual void	drop (cOwnedObject *obj)
void	dropAndDelete (cOwnedObject *obj)

Constructor & Destructor Documentation

cPacket() [1/2]

cPacket

(

const cPacket &

packet

)

Copy constructor.

cPacket() [2/2]

cPacket ( const char *  name = nullptr, short  kind = 0, int64_t  bitLength = 0  )

explicit

Constructor. It takes the packet name, message kind value, and the packet length in bits; all optional.

~cPacket()

virtual ~cPacket ( )

virtual

Destructor

Member Function Documentation

operator=()

cPacket& operator=

(

const cPacket &

packet

)

Assignment operator. Duplication and the assignment operator work all right with cPacket. The name member is not copied; see cNamedObject's operator=() for more details.

dup()

virtual cPacket* dup ( ) const

inlineoverridevirtual

Creates and returns an exact copy of this object. See cObject for more details.

Reimplemented from cMessage.

str()

virtual std::string str ( ) const

overridevirtual

Produces a one-line description of the object's contents. See cObject for more details.

Reimplemented from cMessage.

forEachChild()

virtual void forEachChild ( cVisitor *  v )

overridevirtual

Calls v->visit(this) for each contained object. See cObject for more details.

Reimplemented from cMessage.

parsimPack()

virtual void parsimPack ( cCommBuffer *  buffer ) const

overridevirtual

Serializes the object into an MPI send buffer Used by the simulation kernel for parallel execution. See cObject for more details.

Reimplemented from cMessage.

parsimUnpack()

virtual void parsimUnpack ( cCommBuffer *  buffer )

overridevirtual

Deserializes the object from an MPI receive buffer Used by the simulation kernel for parallel execution. See cObject for more details.

Reimplemented from cMessage.

isPacket()

virtual bool isPacket ( ) const

inlineoverridevirtual

Returns true.

Reimplemented from cMessage.

getDisplayString()

virtual const char* getDisplayString ( ) const

overridevirtual

Returns the encapsulated packet's display string if it has one, otherwise returns the empty string. Override as needed.

Reimplemented from cMessage.

setBitLength()

virtual void setBitLength ( int64_t  l )

virtual

Sets packet length (in bits). When the packet is sent through a channel, packet length affects the transmission duration and the probability of setting the bit error flag.

setByteLength()

void setByteLength ( int64_t  l )

inline

Sets packet length (bytes). This is just a convenience function which invokes setBitLength() with 8*l as argument. The caller must take care that the result does not overflow (i.e. fits into an int64_t).

addBitLength()

virtual void addBitLength ( int64_t  delta )

virtual

Changes packet length by the given value (bits). This is useful for modeling encapsulation/decapsulation. (See also encapsulate() and decapsulate().) The caller must take care that the result does not overflow (i.e. fits into an int64_t).

The value may be negative (packet length may be decreased too). If the resulting length would be negative, the method throws a cRuntimeError.

addByteLength()

void addByteLength ( int64_t  delta )

inline

Changes packet length by the given value (bytes). This is just a convenience function which invokes addBitLength() with 8*l as argument. The caller must take care that the result does not overflow (i.e. fits into an int64_t).

getBitLength()

virtual int64_t getBitLength ( ) const

inlinevirtual

Returns the packet length (in bits).

getByteLength()

int64_t getByteLength ( ) const

inline

Returns the packet length in bytes, that is, bitlength/8. If bitlength is not a multiple of 8, the result is rounded up.

setBitError()

virtual void setBitError ( bool  e )

inlinevirtual

Sets the bit error flag.

hasBitError()

virtual bool hasBitError ( ) const

inlinevirtual

Returns the bit error flag.

encapsulate()

virtual void encapsulate ( cPacket *  packet )

virtual

Encapsulates packet in the packet. The packet length gets increased by the length of the encapsulated packet.

IMPORTANT NOTE: IT IS FORBIDDEN TO KEEP A POINTER TO A MESSAGE AFTER IT WAS ENCAPSULATED. For performance reasons, encapsulated packets are reference counted, meaning that the encapsulated packet is not duplicated when you duplicate a packet, but rather, both (all) copies share the same packet instance. Any change done to the encapsulated packet would affect other packets as well. Decapsulation (and even calling getEncapsulatedPacket()) will create an own (non-shared) copy of the packet.

decapsulate()

virtual cPacket* decapsulate ( )

virtual

Decapsulates a packet from the packet object. The length of this packet will be decreased by the length of the encapsulated packet, except if it was zero. If the length would become negative, cRuntimeError is thrown. If there is no encapsulated packet, the method returns nullptr.

getEncapsulatedPacket()

virtual cPacket* getEncapsulatedPacket ( ) const

virtual

Returns a pointer to the encapsulated packet, or nullptr if there is no encapsulated packet.

IMPORTANT: see notes at encapsulate() about reference counting of encapsulated packets.

hasEncapsulatedPacket()

virtual bool hasEncapsulatedPacket ( ) const

virtual

Returns true if the packet contains an encapsulated packet, and false otherwise. This method is potentially more efficient than getEncapsulatedPacket()!=nullptr, because it does not need to unshare a shared encapsulated packet (see note at encapsulate()).

getDuration()

simtime_t_cref getDuration ( ) const

inline

Returns the transmission duration after the packet was sent through a channel with data rate.

See also

isReceptionStart(), getArrivalTime(), cDatarateChannel

isReceptionStart()

bool isReceptionStart ( ) const

inline

Tells whether this packet represents the start or the end of the reception, provided the packet has nonzero length and it travelled through a channel with nonzero data rate. This can be configured on the receiving gate (see cGate::setDeliverOnReceptionStart()).

See also

getArrivalTime(), getDuration(), cDatarateChannel

---

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

• cpacket.h