cMessage Class Reference
[Simulation core classes]

The message class in OMNeT++. More...

#include <cmessage.h>

Inheritance diagram for cMessage:

Public Member Functions
virtual bool	isPacket () const
Constructors, destructor, assignment

	cMessage (const cMessage &msg)
	cMessage (const char *name=NULL, short kind=0)
virtual	~cMessage ()
cMessage &	operator= (const cMessage &msg)
Redefined cObject member functions.

virtual cMessage *	dup () const
virtual std::string	info () const
virtual std::string	detailedInfo () const
virtual void	forEachChild (cVisitor *v)
virtual void	parsimPack (cCommBuffer *buffer)
virtual void	parsimUnpack (cCommBuffer *buffer)
Message attributes.

void	setKind (short k)
void	setSchedulingPriority (short p)
void	setTimestamp ()
void	setTimestamp (simtime_t t)
void	setContextPointer (void *p)
void	setControlInfo (cObject *p)
cObject *	removeControlInfo ()
short	getKind () const
short	getSchedulingPriority () const
simtime_t_cref	getTimestamp () const
void *	getContextPointer () const
cObject *	getControlInfo () const
Dynamically attaching objects.

virtual cArray &	getParList ()
virtual cMsgPar &	addPar (const char *s)
virtual cMsgPar &	addPar (cMsgPar *p)
_OPPDEPRECATED cMsgPar &	addPar (cMsgPar &p)
virtual cMsgPar &	par (int n)
virtual cMsgPar &	par (const char *s)
virtual int	findPar (const char *s) const
virtual bool	hasPar (const char *s) const
virtual cObject *	addObject (cObject *p)
virtual cObject *	getObject (const char *s)
virtual bool	hasObject (const char *s)
virtual cObject *	removeObject (const char *s)
virtual cObject *	removeObject (cObject *p)
Sending/arrival information.

bool	isSelfMessage () const
bool	isScheduled () 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
Miscellaneous.

virtual const char *	getDisplayString () const
Static Public Member Functions
Statistics.

static long	getTotalMessageCount ()
static long	getLiveMessageCount ()
static void	resetMessageCounters ()
Friends
class	cMessageHeap

Detailed Description

The message class in OMNeT++.

cMessage objects may represent events, messages, jobs or other entities in a simulation. To represent network packets, use the cPacket subclass.

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 cNamedObject); other attributes include message kind, priority, and time stamp. 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. A message also stores information about its last sending, including sending time, arrival time, arrival module and gate.

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 declaration files (.msg) which are translated into C++ classes. An example message declaration:

 message Job
 {
    fields:
        string label;
        int color = -1;
 }

See also:: cSimpleModule, cQueue, cPacket

Member Function Documentation

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

Add an object to the message's object list.

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

See also:: getParList()

virtual cMsgPar& cMessage::addPar ( cMsgPar * p ) [inline, virtual]

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

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

See also:: getParList()

virtual cMsgPar& cMessage::addPar ( const char * s ) [inline, virtual]

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

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

See also:: getParList()

bool cMessage::arrivedOn ( const char * gatename ) const

Return true if the message arrived on the gate given with its name.

If it is a vector gate, the method returns true if the message arrived on any gate in the vector.

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

Produces a multi-line description of the object's contents.

See cObject for more details.

Reimplemented from cObject.

Reimplemented in cPacket.

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

Creates and returns an exact copy of this object, except for the message ID (the clone is assigned a new ID).

Note that the message creation time is also copied, so clones of the same message object have the same creation time. See cObject for more details.

Reimplemented from cObject.

Reimplemented in cPacket.

virtual int cMessage::findPar ( const char * s ) const [virtual]

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 getParList() and cArray::find() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also:: getParList()

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

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

See cObject for more details.

Reimplemented from cObject.

Reimplemented in cPacket.

cGate* cMessage::getArrivalGate ( ) 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::getArrivalGateId ( ) const [inline]

Returns the gate ID of the gate in the receiver module on which the message was received, or -1 if the message has not been sent/scheduled yet.

Note: this is not the same as the gate's index (cGate::getIndex()).

See also:: cGate::getId(), cModule::gate(int)

cModule* cMessage::getArrivalModule ( ) const [inline]

Returns a pointer to the arrival module.

It returns NULL if the message has not been sent/scheduled yet, or if the module was deleted in the meantime.

References simulation.

int cMessage::getArrivalModuleId ( ) const [inline]

Returns the module ID of the receiver module, or -1 if the message has not been sent/scheduled yet.

See also:: cModule::getId(), cSimulation::getModule()

simtime_t_cref cMessage::getArrivalTime ( ) const [inline]

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

When the message has nonzero length and it travelled though a channel with nonzero data rate, arrival time may represent either the start or the end of the reception, as returned by the isReceptionStart() method. By default it is the end of the reception; it can be changed by calling setDeliverOnReceptionStart(true) on the gate at receiving end of the channel that has the nonzero data rate.

See also:: getDuration()

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

Override to define a display string for the message.

Display string affects message appearance in Tkenv. This default implementation returns "".

static long cMessage::getLiveMessageCount ( ) [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 cObject* cMessage::getObject ( const char * s ) [inline, virtual]

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 getParList() and cArray::get() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also:: getParList()

virtual cArray& cMessage::getParList ( ) [inline, virtual]

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

One can use either getParList() combined with cArray methods, or several convenience methods (addPar(), addObject(), par(), etc.) to add, retrieve or remove cMsgPars 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.

cGate* cMessage::getSenderGate ( ) 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::getSenderGateId ( ) const [inline]

Returns the gate ID of the gate in the sender module on which the message was sent, or -1 if the message has not been sent/scheduled yet.

Note: this is not the same as the gate's index (cGate::getIndex()).

See also:: cGate::getId(), cModule::gate(int)

cModule* cMessage::getSenderModule ( ) const [inline]

Returns a pointer to the sender module.

It returns NULL if the message has not been sent/scheduled yet, or if the sender module got deleted in the meantime.

References simulation.

int cMessage::getSenderModuleId ( ) const [inline]

Returns the module ID of the sender module, or -1 if the message has not been sent/scheduled yet.

See also:: cModule::getId(), cSimulation::getModule()

static long cMessage::getTotalMessageCount ( ) [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.

long cMessage::getTreeId ( ) const [inline]

Returns an identifier which is shared among a message object and all messages created by copying it (i.e.

by dup() or the copy constructor).

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

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

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

See also:: getParList()

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

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

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

See also:: getParList()

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

Produces a one-line description of the object's contents.

See cObject for more details.

Reimplemented from cObject.

Reimplemented in cPacket.

virtual bool cMessage::isPacket ( ) const [inline, virtual]

Returns whether the current class is subclass of cPacket.

The cMessage implementation returns false.

Reimplemented in cPacket.

cMessage& cMessage::operator= ( const cMessage & msg )

Assignment operator.

The data members NOT copied are: object name (see cNamedObject's operator=() for more details) and message ID. All other members, including creation time and message tree ID, are copied.

virtual cMsgPar& cMessage::par ( const char * s ) [virtual]

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

If the object does not exist or it cannot be cast to cMsgPar (using dynamic_cast<>), the method throws a cRuntimeError.

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

See also:: getParList()

virtual cMsgPar& cMessage::par ( int n ) [virtual]

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

If the object does not exist or it cannot be cast to cMsgPar (using dynamic_cast<>), the method throws a cRuntimeError.

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

See also:: getParList()

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

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

See cObject for more details.

Reimplemented from cOwnedObject.

Reimplemented in cPacket.

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

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

See cObject for more details.

Reimplemented from cOwnedObject.

Reimplemented in cPacket.

cObject* 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.

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

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

If the object does not exist, NULL is returned.

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

See also:: getParList()

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

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

If the object does not exist, NULL is returned.

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

See also:: getParList()

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 ( cObject * p )

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 cObject interface does not define dup/copy operations. The assignment operator does not change control info.

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

Sets the message kind.

Nonnegative values can be freely used by the user; negative values are reserved by OMNeT++ for internal purposes.

void cMessage::setSchedulingPriority ( short p ) [inline]

Sets event scheduling priority of the message.

The priority member is used when the simulator inserts messages into the future events set (FES), to order messages with identical arrival time values.

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

cmessage.h

cMessage Class Reference [Simulation core classes]

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Function Documentation

cMessage Class Reference
[Simulation core classes]