cMessage Class Reference
[Simulation core classes]

#include <cmessage.h>

Inheritance diagram for cMessage:

cObject cPolymorphic cPacket 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 ()
cMessageoperator= (const cMessage &msg)
Redefined cObject functions.
virtual cPolymorphicdup () 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)
cPolymorphicremoveControlInfo ()
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
cPolymorphiccontrolInfo () const
Dynamically attaching objects.
cArrayparList ()
cParaddPar (const char *s)
cParaddPar (cPar *p)
cParaddPar (cPar &p)
cParpar (int n)
cParpar (const char *s)
int findPar (const char *s) const
bool hasPar (const char *s) const
cObjectaddObject (cObject *p)
cObjectgetObject (const char *s)
bool hasObject (const char *s)
cObjectremoveObject (const char *s)
cObjectremoveObject (cObject *p)
Message encapsulation.
void encapsulate (cMessage *msg)
cMessagedecapsulate ()
cMessageencapsulatedMsg () const
Sending/arrival information.
bool isSelfMessage () const
bool isScheduled () const
cModulesenderModule () const
cGatesenderGate () const
cGatearrivalGate () 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:
Generated on Sat Oct 21 17:47:56 2006 for OMNeT++/OMNEST Simulation Library by  doxygen 1.4.6