cPacket Class Reference

API: cPacket Class Reference
API
cPacket Class Reference
Simulation Programming
Inheritance diagram for cPacket:
[legend]

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)

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

Constructor & Destructor Documentation

◆ cPacket() [1/2]

cPacket ( const cPacket & packet)

Copy constructor.

References cPacket().

Referenced by cPacket(), decapsulate(), dup(), encapsulate(), getEncapsulatedPacket(), and operator=().

◆ 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.

References cPacket().

◆ dup()

virtual cPacket * dup ( ) const
inlineoverridevirtual

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

Reimplemented from cMessage.

References cPacket().

◆ 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.

Referenced by setByteLength().

◆ 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).

References setBitLength().

◆ 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.

Referenced by addByteLength().

◆ 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).

References addBitLength().

◆ getBitLength()

virtual int64_t getBitLength ( ) const
inlinevirtual

Returns the packet length (in bits).

Referenced by getByteLength().

◆ 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.

References getBitLength().

◆ 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: 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.

References cPacket().

◆ 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.

References cPacket().

◆ getEncapsulatedPacket()

virtual cPacket * getEncapsulatedPacket ( ) const
virtual

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

Note: See notes at encapsulate() about reference counting of encapsulated packets.

References cPacket().

◆ 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 the packet's delivery to the module represents the beginning of the reception of the packet, and false otherwise.

◆ isReceptionEnd()

bool isReceptionEnd ( ) const
inline

Returns true if the packet's delivery to the module represents the end of the reception of the packet, and false otherwise.

Generated on for API by doxygen 1.14.0