# cEnvir Class Reference
[User interface: cEnvir and ev, Extension interface to Envir]

`#include <cenvir.h>`

List of all members.

## Detailed Description

Interface to the environment (user interface) of the simulation.

cEnvir is a common facade for the Cmdenv and Tkenv user interfaces (and any other future user interface).

cEnvir has only one instance, the ev global variable.

cEnvir member functions can be rougly divided into two groups:

- I/O for module activities; actual implementation is different for each user interface (e.g. stdin/stdout for Cmdenv, windowing in Tkenv)
- functions for exchanging information between the simulation and the environment.

The implementation of cEnvir is not part of the simulation kernel, it is in a separate library (the Envir library; see src/envir). This means that customizers are free to replace the environment of the simulation as they like, by simply linking the executable with a different library.

The default (Envir library) implementation of cEnvir delegates its task to an internal "simulation application" object. Cmdenv and Tkenv inherit from the default simulation application class.

The default (src/envir) implementation of cEnvir can be customized by subclassing the classes declared in the envirext.h header (e.g. cConfiguration, cRNG, cOutputVectorManager, cOutputScalarManager), and selecting the new classes from `omnetpp.ini`.

## Public Member Functions

Constructor, destructor.
Note that only one instance of cEnvir exists, the ev object.
| cEnvir ()
| ~cEnvir ()
Methods called from main().
void | setup (int ac, char *av[])
int | run ()
void | shutdown ()
Methods to be called by the simulation kernel to notify the environment about events.
void | objectDeleted (cObject *object)
void | messageSent (cMessage *msg, cGate *directToGate=NULL)
void | moduleReparented (cModule *module, cModule *oldparent)
void | messageDelivered (cMessage *msg)
void | breakpointHit (const char *lbl, cSimpleModule *mod)
void | moduleMethodCalled (cModule *from, cModule *to, const char *method)
void | moduleCreated (cModule *newmodule)
void | moduleDeleted (cModule *module)
void | connectionCreated (cGate *srcgate)
void | connectionRemoved (cGate *srcgate)
void | displayStringChanged (cGate *gate)
void | displayStringChanged (cModule *submodule)
void | backgroundDisplayStringChanged (cModule *parentmodule)
void | undisposedObject (cObject *obj)
Methods called by the simulation kernel to access configuration settings.
std::string | getParameter (int run_no, const char *parname)
bool | getParameterUseDefault (int run_no, const char *parname)
bool | isModuleLocal (cModule *parentmod, const char *modname, int index)
cXMLElement * | getXMLDocument (const char *filename, const char *path=NULL)
unsigned | extraStackForEnvir ()
cConfiguration * | config ()
Input/output methods called from simple modules or the simulation kernel.
bool | isGUI ()
bool | disabled ()
void | bubble (cModule *mod, const char *text)
void | printfmsg (const char *fmt,...)
void | printf (const char *fmt="\n",...)
void | puts (const char *s)
cEnvir & | flush ()
std::string | gets (const char *prompt, const char *defaultreply=NULL)
bool | gets (const char *prompt, char *buf, int len=255)
bool | askYesNo (const char *msgfmt,...)
Access to RNGs.
int | numRNGs ()
cRNG * | rng (int k)
void | getRNGMappingFor (cModule *mod)
Methods for recording data from output vectors.
These are functions cOutVector internally relies on. The behavior of these functions can be changed by plugging in a different cOutputVectorManager object into the user interface library. (Or alternatively, by reimplementing the whole cEnvir of course).
void * | registerOutputVector (const char *modulename, const char *vectorname, int tuple)
void | deregisterOutputVector (void *vechandle)
bool | recordInOutputVector (void *vechandle, simtime_t t, double value)
bool | recordInOutputVector (void *vechandle, simtime_t t, double value1, double value2)
Scalar statistics.
The method cSimpleModule::recordScalar() function internally relies on. The behavior of this function can be changed by plugging in a different cOutputScalarManager object into the user interface library. (Or alternatively, by reimplementing the whole cEnvir of course).
void | recordScalar (cModule *module, const char *name, double value)
Management of streams where snapshots can be written.
The behavior of these functions can be changed by plugging in a different cSnapshotManager object into the user interface library. (Or alternatively, by reimplementing the whole cEnvir of course).
std::ostream * | getStreamForSnapshot ()
void | releaseStreamForSnapshot (std::ostream *os)
Miscellaneous functions.
int | argCount ()
char ** | argVector ()
int | getParsimProcId ()
int | getParsimNumPartitions ()
unsigned long | getUniqueNumber ()
bool | idle ()

## Constructor & Destructor Documentation

cEnvir::cEnvir | ( |  | ) |

| Constructor.

cEnvir::~cEnvir | ( |  | ) |

| Destructor.

## Member Function Documentation

int cEnvir::argCount | ( |  | ) |

| Access to original command-line arguments.

char** cEnvir::argVector | ( |  | ) |

| Access to original command-line arguments.

bool cEnvir::askYesNo | ( | const char * | msgfmt,
|  |  | ...
| ) |

| Puts a yes/no question to the user. The question itself is expected in the printf() format (format string + arguments). The true return value means yes, false means no.

void cEnvir::backgroundDisplayStringChanged | ( | cModule * | parentmodule | ) |

| Notifies the environment that a module display string has been changed.

void cEnvir::breakpointHit | ( | const char * | lbl,
|  | cSimpleModule * | mod
| ) |

| Notifies the environment that a simple module executed a breakpoint() call.

void cEnvir::bubble | ( | cModule * | mod,
|  | const char * | text
| ) |

| In Tkenv it pops up a "bubble" over the module icon.

cConfiguration* cEnvir::config | ( |  | ) |

| Access to the configuration data (by default, omnetpp.ini). This is provided here for the benefit of schedulers, parallel simulation algorithms and other simulation kernel extensions. Models (simple modules) should NOT directly access the configuration -- they should rely on module parameters to get input.

void cEnvir::connectionCreated | ( | cGate * | srcgate | ) |

| Notifies the environment that a connection has been created using srcgate->connectTo().

void cEnvir::connectionRemoved | ( | cGate * | srcgate | ) |

| Notifies the environment that a connection has been removed using srcgate->disconnect().

void cEnvir::deregisterOutputVector | ( | void * | vechandle | ) |

| cOutVector objects must deregister themselves when they are no longer needed.

bool cEnvir::disabled | ( |  | ) | `[inline]`

Returns true if the simulation is running in an Express or Express-like mode where output from `ev<<` and `ev.printf()` statement is not printed or logged anywhere but discarded.

Model code may make `ev<<` statements conditional on this flag to save CPU cycles. For example:

         if (!ev.disabled())  ev << "Packet " << msg->name() << " received";

The following version may also be useful (it makes use of the fact that << binds stronger than ?:)

         define EV  ev.disabled()?ev:ev
         EV << "Packet " << msg->name() << " received";

void cEnvir::displayStringChanged | ( | cModule * | submodule | ) |

| Notifies the environment that a module display string has been changed.

void cEnvir::displayStringChanged | ( | cGate * | gate | ) |

| Notifies the environment that a connection display string (stored in the source gate) has been changed.

unsigned cEnvir::extraStackForEnvir | ( |  | ) |

| Called from cSimpleModule, it returns how much extra stack space the user interface recommends for activity() simple modules.

cEnvir& cEnvir::flush | ( |  | ) |

| Flushes the output buffer of ev.printf() and ev<< operations. Only some user interfaces need it: it can be useful with Cmdenv which writes to the standard output, but no need for it with Tkenv which displays all output immediately anyway.

std::string cEnvir::getParameter | ( | int | run_no,
|  | const char * | parname
| ) |

| Called by the simulation kernel (cPar) to obtain value for an input module parameter. Returns empty string if the configuration doesn't specify a value for this parameter.

bool cEnvir::getParameterUseDefault | ( | int | run_no,
|  | const char * | parname
| ) |

| Called by the simulation kernel (cPar) to learn whether it should use the default value for a parameter if getParameter() fails.

int cEnvir::getParsimNumPartitions | ( |  | ) |

| Returns the number of partitions when parallel simulation is active; otherwise it returns 0.

int cEnvir::getParsimProcId | ( |  | ) |

| Returns the partitionID when parallel simulation is active.

void cEnvir::getRNGMappingFor | ( | cModule * | mod | ) |

| Sets up RNG mapping (which maps module-local RNG numbers to "physical" RNGs) for the given module.

bool cEnvir::gets | ( | const char * | prompt,
|  | char * | buf,
|  | int | len = `255`
| ) |

| DEPRECATED. Retained for compatibility only.

std::string cEnvir::gets | ( | const char * | prompt,
|  | const char * | defaultreply = `NULL`
| ) |

| Interactively prompts the user to enter a string. std::stringstream can be used to further process the input.

std::ostream* cEnvir::getStreamForSnapshot | ( |  | ) |

| Returns a stream where a snapshot can be written. Called from cSimulation::snapshot().

unsigned long cEnvir::getUniqueNumber | ( |  | ) |

| The function underlying cSimulation::getUniqueNumber().

cXMLElement* cEnvir::getXMLDocument | ( | const char * | filename,
|  | const char * | path = `NULL`
| ) |

Resolves reference to an XML model configuration file.

First argument is the file name of the XML document. The optional second argument may contain an XPath-like expression to denote an element within the XML document. If path is not present, the root element is returned.

See documentation of cXMLElement::getElementByPath() for path syntax. There's a difference however: paths starting with "." are not accepted, and the first path component must name the root element of the document (with getElementByPath() it would match a child element of the current element). That is, a leading "/" is always assumed at the beginning of the path expression, even if it is not explicitly there.

The method throws an exception if the document cannot be found or the given path expression is invalid. Returns NULL if the element denoted by the path expression doesn't exist in the document.

The returned object tree should not be modified because cEnvir may cache the file and return the same pointer to several callers.

bool cEnvir::idle | ( |  | ) |

May be called from the simulation while actively waiting for some external condition to occur -- for example from blocking receive in parallel simulation, or during wait in real-time simulation.

In a graphical user interface, this method may take care of display redraw and handling user interaction (including handling of the Stop button).

Normally returns false. A true value means the user wants to abort waiting (e.g. pushed the Stop button).

bool cEnvir::isGUI | ( |  | ) | `[inline]`

| Tells if the current environment is graphical or not. (For Tkenv it returns true, and with Cmdenv it returns false.) Simple modules can examine this flag to decide whether or not they need to bother updating display strings.

bool cEnvir::isModuleLocal | ( | cModule * | parentmod,
|  | const char * | modname,
|  | int | index
| ) |

| Used for parallel distributed simulation. Returns true if a to-be-created module which is (or has any submodule which is) in the local partition, and false otherwise. Note that for compound modules that contain simple modules in several partitions, this function will return true on all those partitions.

void cEnvir::messageDelivered | ( | cMessage * | msg | ) |

| Notifies the environment that a message was delivered to its destination module, that is, a message arrival event occurred. Details can be extracted from the message object itself. The user interface implementation may use the notification to animate the message on a network diagram, to write a log entry, etc.

void cEnvir::messageSent | ( | cMessage * | msg,
|  | cGate * | directToGate = `NULL`
| ) |

Notifies the environment that a message was sent.

Details can be extracted from the message object itself. The user interface implementation may use the notification to animate the message on a network diagram, to write a log entry, etc.

The second argument is non-NULL only when sendDirect() was used, and identifies the target gate that was passed to the sendDirect() call. (This information is necessary for proper animation: the target gate might belong to a compound module and be further connected, and then the message will additionally travel through a series of connections before it arrives in a simple module.)

void cEnvir::moduleCreated | ( | cModule * | newmodule | ) |

| Notifies the environment that a module was created. This method is called from cModuleType::create(), when the module has already been created but buildInside() has not been invoked yet.

void cEnvir::moduleDeleted | ( | cModule * | module | ) |

Notifies the environment that a module was (more precisely: is being) deleted.

This method is called from cModule destructor, so the "real" type (className() and everything from the actual subclass) is already lost at this point, however name(), fullName(), fullPath(), gates, parameters (everything that comes from cModule) are still valid.

If a compound module (or a module with dynamically created submodules) is deleted, one should not assume anything about the relative order moduleDeleted() is called for the module and its submodules.

void cEnvir::moduleMethodCalled | ( | cModule * | from,
|  | cModule * | to,
|  | const char * | method
| ) |

| Notifies the environment that one module called a member function of another module object. This hook enables a graphical user interface animate the method call in the network diagram.

void cEnvir::moduleReparented | ( | cModule * | module,
|  | cModule * | oldparent
| ) |

| Notifies the environment that a module changed parent.

int cEnvir::numRNGs | ( |  | ) |

| Returns the number of RNGs available for the simulation ("num-rngs=" omnetpp.ini setting).

void cEnvir::objectDeleted | ( | cObject * | object | ) |

| Notifies the environment that the object no longer exists. The user interface should close all inspector windows for the object and remove it from object lists currently displayed. cObject's destructor automatically calls this function.

void cEnvir::printf | ( | const char * | fmt = `"\n"`,
|  |  | ...
| ) |

| Simple modules can output text into their own window through this function. The text is expected in printf() format (format string + arguments). It is recommended to use C++-style I/O instead of this function.

void cEnvir::printfmsg | ( | const char * | fmt,
|  |  | ...
| ) |

| Displays a message in dialog box. This function should not be used too much by simple modules, if ever.

void cEnvir::puts | ( | const char * | s | ) |

| DEPRECATED. Similar to ev.printf(), but just writes out its argument string with no formatting. Use ev<< instead.

bool cEnvir::recordInOutputVector | ( | void * | vechandle,
|  | simtime_t | t,
|  | double | value1,
|  | double | value2
| ) |

| This method is intended to be called by cOutVector objects to write a value pair into the output vector. The return value is true if the data was actually recorded, and false if it was not recorded (because of filtering, etc.)

bool cEnvir::recordInOutputVector | ( | void * | vechandle,
|  | simtime_t | t,
|  | double | value
| ) |

| This method is intended to be called by cOutVector objects to write a value into the output vector. The return value is true if the data was actually recorded, and false if it was not recorded (because of filtering, etc.)

void cEnvir::recordScalar | ( | cModule * | module,
|  | const char * | name,
|  | double | value
| ) |

| Records a double scalar result, in a default configuration into the scalar result file.

void* cEnvir::registerOutputVector | ( | const char * | modulename,
|  | const char * | vectorname,
|  | int | tuple
| ) |

| This method is intended to be called by cOutVector objects to register themselves. The return value is a handle of type void*; this handle has to be passed to record() to identify the vector each time a value is written.

void cEnvir::releaseStreamForSnapshot | ( | std::ostream * | os | ) |

| Releases a stream after a snapshot was written.

cRNG* cEnvir::rng | ( | int | k | ) |

| Returns pointer to "physical" RNG k (0 <= k < numRNGs()).

int cEnvir::run | ( |  | ) |

| Called from main(). This function should encapsulate the whole functionality of running the application. The return value may be used as exit code for the simulation program.

void cEnvir::setup | ( | int | ac,
|  | char * | av[]
| ) |

| This function is called by main() at the beginning of the program. It receives the command-line arguments as parameters.

void cEnvir::shutdown | ( |  | ) |

| Called from main() before exiting.

void cEnvir::undisposedObject | ( | cObject * | obj | ) |

| Called from module destructors, to notify the environment about objects that the user didn't delete in the module destructor.

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

- cenvir.h