Main Page Modules Class Hierarchy Compound List File List Compound Members

# cMessage Class Reference

`#include <cmessage.h>`

Inheritance diagram for cMessage::

List of all members.

## Miscellaneous.

virtual const char* | displayString () const
int | cmpbydelivtime (cObject *one, cObject *other)
int | cmpbypriority (cObject *one, cObject *other)
unsigned long | totalMessageCount ()
unsigned long | liveMessageCount ()
void | resetMessageCounters ()

## Public Methods

Constructors, destructor, assignment
| cMessage (const cMessage &msg)
| cMessage (const char *name=NULL, int k=0, long len=1, int pri=0, bool err=false)
virtual | ~cMessage ()
cMessage& | operator= (const cMessage &msg)
Redefined cObject functions.
virtual cObject* | dup () const
virtual void | info (char *buf)
virtual void | forEach (ForeachFunc do_fn)
virtual void | writeContents (ostream &os)
virtual int | netPack ()
virtual int | netUnpack ()
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)
int | kind () const
int | priority () const
long | length () const
bool | hasBitError () const
simtime_t | timestamp () const
unsigned long | insertOrder () const
void* | contextPointer () 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)

## Detailed Description

The message class in OMNeT++. cMessage objects may represent events, messages, packets (frames, cells, etc) or other entities in a simulation. cMessage can be assigned a name (a property inherited from cObject) and it has other attributes, including message kind, length, priority, error flag and time stamp.

After being sent through a channel, cMessage also remembers the sending and delivery times and its source module.

You can encapsulate another message into a message object, which is useful when modeling protocol stacks.

cMessage holds a cArray (see parList()) which means that you can attach any number of objects to a message. These objects can be cPar or other objects (like statistics objects, for example). However, when modeling protocol headers, it is not convenient to add header fields as cPar objects: cPars are fairly complex objects themselves, so they add both execution and memory overhead, and they are also error-prone because cPar objects have to be added dynamically and individually to each message object. It is a better idea to leave out cPar objects, and define new C++ message classes with the necessary parameters as int, char, double, etc. instance variables. The latter technique is called 'message subclassing', and the manual describes it in detail.

## Constructor & Destructor Documentation

cMessage::cMessage ( | const cMessage & msg )

| Copy constructor.

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

| Constructor.

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

| Destructor.

## Member Function Documentation

void cMessage::addLength ( | long delta )

| Changes message length by the given value. 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 cException.

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 has arrived 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 has 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 has 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 priority. It can be used to sort messages in a priority queue. Usable as cQeueue CompareFunc.

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

| Returns the context pointer.

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, cException is thrown.

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

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

void cMessage::forEach ( | ForeachFunc do_fn )`[virtual]`

| Call the passed function 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()

void cMessage::info ( | char * buf )`[virtual]`

| Produces a one-line description of object contents into the buffer passed as argument. See cObject for more details. Reimplemented from cObject. 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.

unsigned long cMessage::liveMessageCount ( | )`[inline, static]`

| Returns the total number of messages that currently exist in the simulation. May be useful for detecting memory leaks caused by forgetting to delete messages.

int cMessage::netPack ( | )`[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.

int cMessage::netUnpack ( | )`[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 cException.

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

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.

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

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

| Reset counters used by totalMessageCount() and liveMessageCount().

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.

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.

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.

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::setContextPointer ( | void * p )`[inline]`

| Sets context pointer.

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

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

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

| Returns the message's time stamp.

unsigned long cMessage::totalMessageCount ( | )`[inline, static]`

| Returns the total number of messages created so far during the current simulation run. May be useful for debugging, profiling, etc.

void cMessage::writeContents ( | 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