OMNeT++/OMNEST Simulation Library: cMessage Class Reference

cMessage objects may represent events, messages, packets (frames, cells, etc) or other entities in a simulation.

Messages may be: scheduled (to arrive back at the same module at a later time), cancelled, sent out on a gate, or sent directly to another module; all via methods of cSimpleModule.

cMessage can be assigned a name (a property inherited from cObject); other attributes include message kind, length, priority, error flag and time stamp. Arrival time and gate is also stored. cMessage supports encapsulation, and messages may be cloned with the dup() function. The control info field facilitates modelling communication between protocol layers. The context pointer field makes it easier to work with several timers (self-messages) at a time. Useful methods are isSelfMessage(), which tells apart self-messages from messages received from other modules, and isScheduled(), which returns whether a self-message is currently scheduled.

Further fields can be added to cMessage via message declarations (.msg files) which are translated into C++ classes. An example message declaration:

 message NetwPkt
 {
    fields:
        int destAddr = -1; // destination address
        int srcAddr = -1;  // source address
        int ttl =  32;     // time to live
 }

Constructor & Destructor Documentation

cMessage::cMessage	(	const char *	name = `NULL`,
		int	k = `0`,
		long	len = `0`,
		int	pri = `0`,
		bool	err = `false`
	)	`[explicit]`

Constructor.

Member Function Documentation

void cMessage::addLength

(

long

delta

)

Changes message length by the given value (bits).

This is useful for modeling encapsulation/decapsulation. (See also encapsulate() and decapsulate().)

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

cObject* cMessage::addObject ( cObject * p ) [inline]

Add an object to the message's object list.

NOTE: This is a convenience function: one may use parList() and cArray::add() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also:: parList()

cPar& cMessage::addPar ( cPar * p ) [inline]

Add a parameter object to the message's object list.

NOTE: This is a convenience function: one may use parList() and cArray::add() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also:: parList()

cPar& cMessage::addPar ( const char * s ) [inline]

Add a new, empty parameter (cPar object) with the given name to the message's object list.

NOTE: This is a convenience function: one may use parList() and cArray::add() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also:: parList()

cGate* cMessage::arrivalGate

(

)

const

Returns pointers to the gate from which the message was sent and on which gate it arrived.

A NULL pointer is returned for new (unsent) messages and messages sent via scheduleAt().

int cMessage::arrivalGateId ( ) const [inline]

Returns index of gate the message arrived on in the sender module or -1 if the message hasn't sent/scheduled yet.

int cMessage::arrivalModuleId ( ) const [inline]

Returns receiver module's index in the module vector or -1 if the message hasn't been sent/scheduled yet.

simtime_t cMessage::arrivalTime ( ) const [inline]

Returns time when the message arrived (or will arrive if it is currently scheduled or is underway), or 0 if the message hasn't been sent/scheduled yet.

bool cMessage::arrivedOn	(	const char *	s,
		int	g = `0`
	)

Return true if the message arrived through the gate given with its name and index (if multiple gate).

bool cMessage::arrivedOn ( int g ) const [inline]

Return true if the message arrived through gate g.

int cMessage::cmpbydelivtime	(	cObject *	one,
		cObject *	other
	)	`[static]`

Static function that compares two messages by their delivery times, then by their priorities.

Usable as cQeueue CompareFunc.

int cMessage::cmpbypriority	(	cObject *	one,
		cObject *	other
	)	`[static]`

Static function that compares two messages by their priorities.

It can be used to sort messages in a priority queue. Usable as cQeueue CompareFunc.

void* cMessage::contextPointer ( ) const [inline]

Returns the context pointer.

cPolymorphic* cMessage::controlInfo ( ) const [inline]

Returns pointer to the attached "control info".

simtime_t cMessage::creationTime ( ) const [inline]

Returns time when the message was created.

cMessage* cMessage::decapsulate

(

)

Decapsulates a message from the message object.

The length of the message will be decreased accordingly, except if it was zero. If the length would become negative, cRuntimeError is thrown.

virtual const char* cMessage::displayString ( ) const [virtual]

Override to define a display string for the message.

Display string affects message appearance in Tkenv.

This default implementation returns "".

virtual cObject* cMessage::dup ( ) const [inline, virtual]

Creates and returns an exact copy of this object.

See cObject for more details.

Reimplemented from cObject.

Reimplemented in cPacket.

void cMessage::encapsulate

(

cMessage *

msg

)

Encapsulates msg in the message.

msg->length() will be added to the length of the message.

cMessage* cMessage::encapsulatedMsg ( ) const [inline]

Returns a pointer to the encapsulated message, or NULL.

int cMessage::findPar

(

const char *

)

const

Returns the index of the parameter with the given name in the message's object list, or -1 if it could not be found.

NOTE: This is a convenience function: one may use parList() and cArray::find() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also:: parList()

virtual void cMessage::forEachChild ( cVisitor * v ) [virtual]

Calls v->visit(this) for each contained object.

See cObject for more details.

Reimplemented from cObject.

cObject* cMessage::getObject ( const char * s ) [inline]

Returns the object with the given name in the message's object list.

If the object is not found, it returns NULL.

NOTE: This is a convenience function: one may use parList() and cArray::get() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also:: parList()

bool cMessage::hasBitError ( ) const [inline]

Returns true if bit error flag is set, false otherwise.

bool cMessage::hasObject ( const char * s ) [inline]

Check if an object with the given name exists in the message's object list.

NOTE: This is a convenience function: one may use parList() and cArray::exist() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also:: parList()

bool cMessage::hasPar ( const char * s ) const [inline]

Check if a parameter with the given name exists in the message's object list.

NOTE: This is a convenience function: one may use parList() and cArray::exist() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also:: parList()

virtual std::string cMessage::info ( ) const [virtual]

Produces a one-line description of object contents into the buffer passed as argument.

See cObject for more details.

Reimplemented from cPolymorphic.

Reimplemented in cPacket.

unsigned long cMessage::insertOrder ( ) const [inline]

INTERNAL: Used by cMessageHeap.

bool cMessage::isScheduled ( ) const [inline]

Return true if message is among future events.

bool cMessage::isSelfMessage ( ) const [inline]

Return true if message was posted by scheduleAt().

long cMessage::liveMessageCount ( ) [inline, static]

Returns the number of message objects that currently exist in the program.

The counter is incremented by cMessage constructor and decremented by the destructor. May be useful for profiling or debugging memory leaks caused by forgetting to delete messages.

virtual void cMessage::netPack ( cCommBuffer * buffer ) [virtual]

Serializes the object into a PVM or MPI send buffer Used by the simulation kernel for parallel execution.

See cObject for more details.

Reimplemented from cObject.

Reimplemented in cPacket.

virtual void cMessage::netUnpack ( cCommBuffer * buffer ) [virtual]

Deserializes the object from a PVM or MPI receive buffer Used by the simulation kernel for parallel execution.

See cObject for more details.

Reimplemented from cObject.

Reimplemented in cPacket.

cMessage& cMessage::operator=

(

const cMessage &

msg

)

Assignment operator.

Duplication and the assignment operator work all right with cMessage. The name member doesn't get copied; see cObject's operator=() for more details.

cPar& cMessage::par

(

const char *

)

Returns the object with the given name in the message's object list, converting it to a cPar.

If the object doesn't exist or it cannot be cast to cPar (using dynamic_cast<>), the method throws a cRuntimeError.

NOTE: This is a convenience function: one may use parList() and cArray::get() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also:: parList()

cPar& cMessage::par

(

int

)

Returns the nth object in the message's object list, converting it to a cPar.

If the object doesn't exist or it cannot be cast to cPar (using dynamic_cast<>), the method throws a cRuntimeError.

NOTE: This is a convenience function: one may use parList() and cArray::get() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also:: parList()

cArray& cMessage::parList ( ) [inline]

Returns reference to the 'object list' of the message: a cArray which is used to store parameter (cPar) objects and other objects attached to the message.

One can use either parList() combined with cArray methods, or several convenience methods (addPar(), addObject(), par(), etc.) to add, retrieve or remove cPars and other objects.

NOTE: using the object list has alternatives which may better suit your needs. For more information, see class description for discussion about message subclassing vs dynamically attached objects.

cPolymorphic* cMessage::removeControlInfo

(

)

Removes the "control info" structure (object) from the message and returns its pointer.

Returns NULL if there was no control info in the message

cObject* cMessage::removeObject ( cObject * p ) [inline]

Remove the object with the given name from the message's object list, and return its pointer.

If the object doesn't exist, NULL is returned.

NOTE: This is a convenience function: one may use parList() and cArray::remove() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also:: parList()

cObject* cMessage::removeObject ( const char * s ) [inline]

Remove the object with the given name from the message's object list, and return its pointer.

If the object doesn't exist, NULL is returned.

NOTE: This is a convenience function: one may use parList() and cArray::remove() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also:: parList()

cGate* cMessage::senderGate

(

)

const

Returns pointers to the gate from which the message was sent and on which gate it arrived.

A NULL pointer is returned for new (unsent) messages and messages sent via scheduleAt().

int cMessage::senderGateId ( ) const [inline]

Returns index of gate sent through in the sender module or -1 if the message hasn't been sent/scheduled yet.

int cMessage::senderModuleId ( ) const [inline]

Returns sender module's index in the module vector or -1 if the message hasn't been sent/scheduled yet.

simtime_t cMessage::sendingTime ( ) const [inline]

Returns time when the message was sent/scheduled or 0 if the message hasn't been sent yet.

virtual void cMessage::setArrival	(	cModule *	module,
		int	gate,
		simtime_t	t
	)	`[virtual]`

Called internally by the simulation kernel as part of processing the send(), scheduleAt() calls to set the parameters returned by the arrivalModuleId(), arrivalGate(), arrivalTime() methods.

virtual void cMessage::setArrival	(	cModule *	module,
		int	gate
	)	`[virtual]`

Called internally by the simulation kernel as part of processing the send(), scheduleAt() calls to set the parameters returned by the arrivalModuleId(), arrivalGate() methods.

virtual void cMessage::setArrivalTime ( simtime_t t ) [virtual]

Called internally by the simulation kernel to set the parameters returned by the arrivalTime() method.

void cMessage::setContextPointer ( void * p ) [inline]

Sets the context pointer.

This pointer may store an arbitrary value. It is useful when managing several timers (self-messages): when scheduling the message one can set the context pointer to the data structure the timer corresponds to (e.g. the buffer whose timeout the message represents), so that when the self-message arrives it is easier to identify where it belongs.

void cMessage::setControlInfo

(

cPolymorphic *

)

Attaches a "control info" structure (object) to the message.

This is most useful when passing packets between protocol layers of a protocol stack: e.g. when sending down an IP datagram to Ethernet, the attached "control info" can contain the destination MAC address.

The "control info" object will be deleted when the message is deleted. Only one "control info" structure can be attached (the second setControlInfo() call throws an error).

When the message is duplicated or copied, copies will have their control info set to NULL because the cPolymorphic interface doesn't define dup/copy operations. The assignment operator doesn't change control info.

void cMessage::setKind ( int k ) [inline]

Sets message kind.

The message kind member is not used by OMNeT++, it can be used freely by the user.

void cMessage::setLength

(

long

)

Sets message length (bits).

When the message is sent through a channel, message length affects transmission delay and the probability of setting the bit error flag.

void cMessage::setPriority ( int p ) [inline]

Sets message priority.

The priority member is used when the simulator inserts messages in the message queue (FES) to order messages with identical arrival time values.

virtual void cMessage::setSentFrom	(	cModule *	module,
		int	gate,
		simtime_t	t
	)	`[virtual]`

Called internally by the simulation kernel as part of the send(), scheduleAt() calls to set the parameters returned by the senderModuleId(), senderGate(), sendingTime() methods.

void cMessage::setSrcProcId ( unsigned char procId ) [inline]

Used internally by the parallel simulation kernel.

void cMessage::setTimestamp ( simtime_t t ) [inline]

Directly sets the message's time stamp.

void cMessage::setTimestamp ( ) [inline]

Sets the message's time stamp to the current simulation time.

unsigned char cMessage::srcProcId ( ) [inline]

Used internally by the parallel simulation kernel.

simtime_t cMessage::timestamp ( ) const [inline]

Returns the message's time stamp.

long cMessage::totalMessageCount ( ) [inline, static]

Returns the total number of messages created since the last reset (reset is usually called my user interfaces at the beginning of each simulation run).

The counter is incremented by cMessage constructor. Counter is signed to make it easier to detect if it overflows during very long simulation runs. May be useful for profiling or debugging memory leaks.

virtual void cMessage::writeContents ( std::ostream & os ) [virtual]

Writes textual information about this object to the stream.

See cObject for more details.

Reimplemented from cObject.


Miscellaneous.
virtual const char *	displayString () const
int	cmpbydelivtime (cObject one, cObject other)
int	cmpbypriority (cObject one, cObject other)
Public Member Functions
Constructors, destructor, assignment
	cMessage (const cMessage &msg)
	cMessage (const char *name=NULL, int k=0, long len=0, int pri=0, bool err=false)
virtual	~cMessage ()
cMessage &	operator= (const cMessage &msg)
Redefined cObject functions.
virtual cObject *	dup () const
virtual std::string	info () const
virtual void	forEachChild (cVisitor *v)
virtual void	writeContents (std::ostream &os)
virtual void	netPack (cCommBuffer *buffer)
virtual void	netUnpack (cCommBuffer *buffer)
Message attributes.
void	setKind (int k)
void	setPriority (int p)
void	setLength (long l)
void	addLength (long delta)
void	setBitError (bool err)
void	setTimestamp ()
void	setTimestamp (simtime_t t)
void	setContextPointer (void *p)
void	setControlInfo (cPolymorphic *p)
cPolymorphic *	removeControlInfo ()
int	kind () const
int	priority () const
long	length () const
bool	hasBitError () const
simtime_t	timestamp () const
unsigned long	insertOrder () const
void *	contextPointer () const
cPolymorphic *	controlInfo () const
Dynamically attaching objects.
cArray &	parList ()
cPar &	addPar (const char *s)
cPar &	addPar (cPar *p)
cPar &	addPar (cPar &p)
cPar &	par (int n)
cPar &	par (const char *s)
int	findPar (const char *s) const
bool	hasPar (const char *s) const
cObject *	addObject (cObject *p)
cObject *	getObject (const char *s)
bool	hasObject (const char *s)
cObject *	removeObject (const char *s)
cObject *	removeObject (cObject *p)
Message encapsulation.
void	encapsulate (cMessage *msg)
cMessage *	decapsulate ()
cMessage *	encapsulatedMsg () const
Sending/arrival information.
bool	isSelfMessage () const
bool	isScheduled () const
cGate *	senderGate () const
cGate *	arrivalGate () const
int	senderModuleId () const
int	senderGateId () const
int	arrivalModuleId () const
int	arrivalGateId () const
simtime_t	creationTime () const
simtime_t	sendingTime () const
simtime_t	arrivalTime () const
bool	arrivedOn (int g) const
bool	arrivedOn (const char *s, int g=0)
Internally used methods.
virtual void	setSentFrom (cModule *module, int gate, simtime_t t)
virtual void	setArrival (cModule *module, int gate)
virtual void	setArrival (cModule *module, int gate, simtime_t t)
virtual void	setArrivalTime (simtime_t t)
void	setSrcProcId (unsigned char procId)
unsigned char	srcProcId ()
Static Public Member Functions
Statistics.
long	totalMessageCount ()
long	liveMessageCount ()
void	resetMessageCounters ()
Friends
class	cMessageHeap

cMessage Class Reference
[Simulation core classes]

Detailed Description

Miscellaneous.

Public Member Functions

Static Public Member Functions

Friends

Constructor & Destructor Documentation

Member Function Documentation

cMessage Class Reference [Simulation core classes]

Detailed Description

Miscellaneous.

Public Member Functions

Static Public Member Functions

Friends

Constructor & Destructor Documentation

Member Function Documentation

cMessage Class Reference
[Simulation core classes]