cMessage Class Reference
[Simulation core classes]

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

#include <cmessage.h>

Inheritance diagram for cMessage:
cOwnedObject cNamedObject cObject cPacket

List of all members.

Public Member Functions

virtual bool isPacket () const
Constructors, destructor, assignment

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

virtual cMessagedup () 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)
cObjectremoveControlInfo ()
short getKind () const
short getSchedulingPriority () const
simtime_t_cref getTimestamp () const
void * getContextPointer () const
cObjectgetControlInfo () const
Dynamically attaching objects.

virtual cArraygetParList ()
virtual cMsgParaddPar (const char *s)
virtual cMsgParaddPar (cMsgPar *p)
_OPPDEPRECATED cMsgParaddPar (cMsgPar &p)
virtual cMsgParpar (int n)
virtual cMsgParpar (const char *s)
virtual int findPar (const char *s) const
virtual bool hasPar (const char *s) const
virtual cObjectaddObject (cObject *p)
virtual cObjectgetObject (const char *s)
virtual bool hasObject (const char *s)
virtual cObjectremoveObject (const char *s)
virtual cObjectremoveObject (cObject *p)
Sending/arrival information.

bool isSelfMessage () const
bool isScheduled () const
cModulegetSenderModule () const
cGategetSenderGate () const
cModulegetArrivalModule () const
cGategetArrivalGate () 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:
Generated on Fri Mar 7 17:19:40 2014 for OMNeT++ Simulation Library by  doxygen 1.6.3