# cMessage Class Reference
[Simulation core classes]

`#include <cmessage.h>`

Inheritance diagram for cMessage:

List of all members.

## Detailed Description

The message class in OMNeT++.

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
     }

See also:
  cSimpleModule, cQueue

## Miscellaneous.

virtual const char * | displayString () const
static int | cmpbydelivtime (cObject *one, cObject *other)
static 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 cPolymorphic * | 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 | setByteLength (long l)
void | addLength (long delta)
void | addByteLength (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
long | byteLength () 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
cModule * | senderModule () 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)
bool | arrivedOn (const char *s, int gateindex)
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 (int procId)
int | srcProcId ()

## Static Public Member Functions

Statistics.
static long | totalMessageCount ()
static long | liveMessageCount ()
static void | resetMessageCounters ()

## Friends

class | cMessageHeap

## Constructor & Destructor Documentation

cMessage::cMessage | ( | const cMessage & | msg | ) |

| Copy constructor.

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

| Constructor.

virtual cMessage::~cMessage | ( |  | ) | `[virtual]`

| Destructor.

## Member Function Documentation

void cMessage::addByteLength | ( | long | delta | ) | `[inline]`

| Changes message length by the given value (bytes). This is just a convenience function which invokes addLength() with 8*l as argument. The caller must take care that the result does not overflow (i.e. fits into a long).

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 caller must take care that the result does not overflow (i.e. fits into a long). 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]`

| DEPRECATED! Use addPar(cPar *p) instead.

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 | gateindex
| ) |

| Return true if the message arrived through the given gate in the named gate vector.

bool cMessage::arrivedOn | ( | const char * | s | ) |

| Return true if the message arrived on the gate given with its name. If it's a vector gate, the method returns true if the message arrived on any gate in the vector.

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

| Return true if the message arrived through gate g.

long cMessage::byteLength | ( |  | ) | const`[inline]`

| Returns message length in bytes, that is, length()/8. If length() is not a multiple of 8, the result is rounded up.

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

static 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 cPolymorphic* 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() is increased by the length of the encapsulated message.

IMPORTANT NOTE: IT IS FORBIDDEN TO KEEP A POINTER TO A MESSAGE AFTER IT WAS ENCAPSULATED. For performance reasons, encapsulated messages are reference counted, meaning that the encapsulated message is not duplicated when you duplicate a message, but rather, both (all) copies share the same message instance. Any change done to the encapsulated message would affect other messages as well. Decapsulation (and even calling encapsulatedMsg()) will create an own (non-shared) copy of the message.

cMessage* cMessage::encapsulatedMsg | ( |  | ) | const

| Returns a pointer to the encapsulated message, or NULL. IMPORTANT: see notes at encapsulate() about reference counting of encapsulated messages.

int cMessage::findPar | ( | const char * | s | ) | 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().

int cMessage::kind | ( |  | ) | const`[inline]`

| Returns message kind.

long cMessage::length | ( |  | ) | const`[inline]`

| Returns message length (bits).

static 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 * | s | ) |

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 | n | ) |

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.

int cMessage::priority | ( |  | ) | const`[inline]`

| Returns message priority.

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()

static void cMessage::resetMessageCounters | ( |  | ) | `[inline, static]`

| Reset counters used by totalMessageCount() and liveMessageCount(). Reimplemented from cObject.

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.

cModule* cMessage::senderModule | ( |  | ) | const`[inline]`

| Returns a pointer to the sender module. It returns NULL if the message hasn't been sent/scheduled yet, or if the sender module got deleted in the meantime.

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::setBitError | ( | bool | err | ) | `[inline]`

| Set bit error flag.

void cMessage::setByteLength | ( | long | l | ) | `[inline]`

| Sets message length (bytes). This is just a convenience function which invokes setLength() with 8*l as argument. The caller must take care that the result does not overflow (i.e. fits into a long).

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 * | 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 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 | l | ) |

| 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 | ( | int | 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.

int cMessage::srcProcId | ( |  | ) | `[inline]`

| Used internally by the parallel simulation kernel.

simtime_t cMessage::timestamp | ( |  | ) | const`[inline]`

| Returns the message's time stamp.

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

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

- cmessage.h