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
bool	isUpdate () const
txid_t	getTransmissionId () const
simtime_t_cref	getDuration () const
simtime_t_cref	getRemainingDuration () const
bool	isReceptionStart () const
bool	isReceptionEnd () 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
msgid_t	getId () const
msgid_t	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
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)=default
virtual	~cObject ()
virtual const char *	getClassName () const
bool	isName (const char *s) const
virtual const char *	getFullName () const
virtual std::string	getFullPath () const
virtual std::string	getClassAndFullName () const
virtual std::string	getClassAndFullPath () const
const cObject *	getThisPtr () const
virtual std::ostream &	printOn (std::ostream &os) const
virtual bool	isSoftOwner () const
cObject *	findObject (const char *name, bool deep=true)
virtual cClassDescriptor *	getDescriptor () const
void	copyNotSupported () const

Additional Inherited Members
Static Public Member Functions inherited from cMessage
static uint64_t	getTotalMessageCount ()
static uint64_t	getLiveMessageCount ()
static void	resetMessageCounters ()
Static Public Member Functions inherited from cOwnedObject
static long	getTotalObjectCount ()
static long	getLiveObjectCount ()
static void	resetObjectCounters ()
static cSoftOwner *	getOwningContext ()
Protected Member Functions inherited from cMessage
virtual bool	isMessage () const override
virtual bool	isStale () override
virtual cObject *	getTargetObject () const override
virtual void	execute () override
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. The name member is not copied; see cNamedObject::operator=() for 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()).

isUpdate()

bool isUpdate ( ) const

inline

Returns true if this packet is a transmission update, and false otherwise. Transmission updates are packets sent with the SendOptions::updateTx() or SendOptions::finishTx() option.

See also

getRemainingDuration(), cSimpleModule::send(), cSimpleModule::sendDirect(), SendOptions

getTransmissionId()

txid_t getTransmissionId ( ) const

inline

If the packet is a transmission update (isUpdate() would return true), this method returns the original packet ID supplied in the send call.

See also

cSimpleModule::send(), cSimpleModule::sendDirect(), SendOptions

getDuration()

simtime_t_cref getDuration ( ) const

inline

Returns the transmission duration of the whole packet after the packet was sent through a transmission channel such as cDatarateChannel.

Contrast that with getRemainingDuration() which, when called on transmission update packets, returns the remaining transmission time for the packet. Naturally, remainingDuration <= duration.

After a sending not involving a transmission channel, the duration is set to zero.

See also

getRemainingDuration(), isReceptionStart(), getArrivalTime(), cDatarateChannel

getRemainingDuration()

simtime_t_cref getRemainingDuration ( ) const

inline

Returns the remaining transmission time for the packet after the packet was sent through a transmission channel such as cDatarateChannel.

For packets delivered to a gate with the default (at-end) delivery mode, the remaining transmission time is zero.

For packets delivered to a gate with the immediate delivery mode, the remaining duration is the full transmission duration if the packet is a normal (i.e. non-update) packet. If the packet is a transmission update (isUpdate() would return true), the remaining transmission time is determined by the send options passed the send call.

After a sending not involving a transmission channel, the remaining duration will be zero.

See also

isUpdate(), getDuration(), getArrivalTime(), cDatarateChannel, cGate::setDeliverImmediately(), cSimpleModule::send(), cSimpleModule::sendDirect(), SendOptions

isReceptionStart()

bool isReceptionStart ( ) const

inline

Returns true if getRemainingDuration() and getDuration() would return the same value, and false otherwise.

isReceptionEnd()

bool isReceptionEnd ( ) const

inline

Returns true if getRemainingDuration() would return zero, and false otherwise.

References SimTime::isZero().

---

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

• cpacket.h