#include <cenvir.h>

Description

cEnvir represents the "environment" or user interface of the simulation.

The active cEnvir object can be accessed via cSimulation::getActiveEnvir() or the getEnvir() global function.

Methods useful for simulation models include isGUI() and isExpressMode(). Most other cEnvir methods are used in the communication between the simulation kernel and the environment.

The default implementation of cEnvir can be extended by subclassing the classes declared in the envirext.h header (e.g. cConfiguration, cRNG, cIOutputVectorManager, cIOutputScalarManager), and selecting the new classes in omnetpp.ini.

Inheritance diagram for cEnvir:

Public Member Functions
Constructor, destructor.
	cEnvir ()

virtual	~cEnvir ()

Methods to be called by the simulation kernel to notify the environment about events.
virtual void	objectDeleted (cObject *object)

virtual void	componentInitBegin (cComponent *component, int stage)

virtual void	simulationEvent (cEvent *event)=0

virtual void	messageScheduled (cMessage *msg)=0

virtual void	messageCancelled (cMessage *msg)=0

virtual void	beginSend (cMessage *msg, const SendOptions &options)=0

virtual void	messageSendDirect (cMessage msg, cGate toGate, const ChannelResult &result)=0

virtual void	messageSendHop (cMessage msg, cGate srcGate)=0

virtual void	messageSendHop (cMessage msg, cGate srcGate, const ChannelResult &result)=0

virtual void	endSend (cMessage *msg)=0

virtual void	messageCreated (cMessage *msg)=0

virtual void	messageCloned (cMessage msg, cMessage clone)=0

virtual void	messageDeleted (cMessage *msg)=0

virtual void	moduleReparented (cModule module, cModule oldparent, int oldId)=0

virtual void	componentMethodBegin (cComponent from, cComponent to, const char *methodFmt, va_list va, bool silent)=0

virtual void	componentMethodEnd ()=0

virtual void	moduleCreated (cModule *newmodule)=0

virtual void	moduleDeleted (cModule *module)=0

virtual void	gateCreated (cGate *newgate)=0

virtual void	gateDeleted (cGate *gate)=0

virtual void	connectionCreated (cGate *srcgate)=0

virtual void	connectionDeleted (cGate *srcgate)=0

virtual void	displayStringChanged (cComponent *component)=0

virtual void	undisposedObject (cObject *obj)

Methods called by the logging mechanism to query the current state.
virtual const char *	getCurrentEventName ()

virtual const char *	getCurrentEventClassName ()

virtual cModule *	getCurrentEventModule ()

Methods called by the simulation kernel to access configuration settings.
virtual void	preconfigure (cComponent *component)=0

virtual void	configure (cComponent *component)=0

virtual void	readParameter (cPar *parameter)=0

virtual bool	isModuleLocal (cModule parentmod, const char modname, int index)=0

virtual cXMLElement *	getXMLDocument (const char filename, const char xpath=nullptr)=0

virtual cXMLElement *	getParsedXMLString (const char content, const char xpath=nullptr)=0

virtual void	forgetXMLDocument (const char *filename)=0

virtual void	forgetParsedXMLString (const char *content)=0

virtual void	flushXMLDocumentCache ()=0

virtual void	flushXMLParsedContentCache ()=0

virtual unsigned	getExtraStackForEnvir () const =0

virtual cConfiguration *	getConfig ()=0

virtual cConfigurationEx *	getConfigEx ()

virtual std::string	resolveResourcePath (const char fileName, cComponentType context=nullptr)=0

Input/output methods called from simple modules or the simulation kernel.
virtual bool	isGUI () const =0

bool	isLoggingEnabled () const

virtual bool	isExpressMode () const =0

virtual void	bubble (cComponent component, const char text)=0

virtual void	log (cLogEntry *entry)=0

virtual void	alert (const char *msg)=0

virtual void	printfmsg (const char *fmt,...)

virtual std::string	gets (const char prompt, const char defaultReply=nullptr)=0

virtual bool	askYesNo (const char *prompt)=0

virtual void	getImageSize (const char *imageName, double &outWidth, double &outHeight)=0

virtual void	getTextExtent (const cFigure::Font &font, const char *text, double &outWidth, double &outHeight, double &outAscent)=0

virtual void	appendToImagePath (const char *directory)=0

virtual void	loadImage (const char fileName, const char imageName=nullptr)=0

virtual cFigure::Rectangle	getSubmoduleBounds (const cModule *submodule)=0

virtual std::vector< cFigure::Point >	getConnectionLine (const cGate *sourceGate)=0

virtual double	getZoomLevel (const cModule *module)=0

virtual double	getAnimationTime () const =0

virtual double	getAnimationSpeed () const =0

virtual double	getRemainingAnimationHoldTime () const =0

Access to RNGs.
virtual int	getNumRNGs () const =0

virtual cRNG *	getRNG (int k)=0

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 cIOutputVectorManager object into the user interface library. (Or alternatively, by reimplementing the whole cEnvir of course).
virtual void *	registerOutputVector (const char modulename, const char vectorname)=0

virtual void	deregisterOutputVector (void *vechandle)=0

virtual void	setVectorAttribute (void vechandle, const char name, const char *value)=0

virtual bool	recordInOutputVector (void *vechandle, simtime_t t, double value)=0

Scalar statistics.
The method cComponent::recordScalar() function internally relies on. The behavior of this function can be changed by plugging in a different cIOutputScalarManager object into the user interface library. (Or alternatively, by reimplementing the whole cEnvir of course).
virtual void	recordScalar (cComponent component, const char name, double value, opp_string_map *attributes=nullptr)=0

virtual void	recordStatistic (cComponent component, const char name, cStatistic statistic, opp_string_map attributes=nullptr)=0

virtual void	recordParameter (cPar *par)=0

virtual void	recordComponentType (cComponent *component)=0

Statistic recording.
virtual void	addResultRecorders (cComponent component, simsignal_t signal, const char statisticName, cProperty *statisticTemplateProperty)=0

Management of streams where snapshots can be written.
The behavior of these functions can be changed by plugging in a different cISnapshotManager object into the user interface library. (Or alternatively, by reimplementing the whole cEnvir of course).
virtual std::ostream *	getStreamForSnapshot ()=0

virtual void	releaseStreamForSnapshot (std::ostream *os)=0

Miscellaneous functions.
virtual int	getArgCount () const =0

virtual char **	getArgVector () const =0

virtual int	getParsimProcId () const =0

virtual int	getParsimNumPartitions () const =0

virtual unsigned long	getUniqueNumber ()=0

virtual void	refOsgNode (osg::Node *scene)=0

virtual void	unrefOsgNode (osg::Node *scene)=0

virtual bool	idle ()=0

virtual void	pausePoint ()=0

virtual bool	ensureDebugger (cRuntimeError *error=nullptr)=0

Lifecycle listeners
virtual void	addLifecycleListener (cISimulationLifecycleListener *listener)

virtual void	removeLifecycleListener (cISimulationLifecycleListener *listener)

virtual std::vector< cISimulationLifecycleListener * >	getLifecycleListeners () const

virtual void	notifyLifecycleListeners (SimulationLifecycleEventType eventType, cObject *details=nullptr)

Constructor & Destructor Documentation

◆ cEnvir()

cEnvir ( )

inline

Constructor.

◆ ~cEnvir()

virtual ~cEnvir ( )

inlinevirtual

Destructor.

Member Function Documentation

◆ objectDeleted()

virtual void objectDeleted ( cObject * object )

inlinevirtual

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.

Reimplemented in cNullEnvir.

◆ componentInitBegin()

virtual void componentInitBegin	(	cComponent *	component,
		int	stage
	)

inlinevirtual

Notifies the environment that a component's initialize method is about to be called.

◆ simulationEvent()

virtual void simulationEvent ( cEvent * event )

pure virtual

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.

Implemented in cNullEnvir.

◆ messageScheduled()

virtual void messageScheduled ( cMessage * msg )

pure virtual

Notifies the environment that a message was scheduled.

See also: cSimpleModule::scheduleAt()

Implemented in cNullEnvir.

◆ messageCancelled()

virtual void messageCancelled ( cMessage * msg )

pure virtual

Notifies the environment that a scheduled message was cancelled.

See also: cSimpleModule::cancelEvent()

Implemented in cNullEnvir.

◆ beginSend()

virtual void beginSend	(	cMessage *	msg,
		const SendOptions &	options
	)

pure virtual

Notifies the environment that a message is being sent from a simple module. beginSend() will be followed by a messageSendDirect() (optional, only present when cSimpleModule::sendDirect() was called), several messageSendHop() calls (one for each connection in the path), and finally an endSend(). At least one call to either messageSendDirect() or messageSendHop() must occur between corresponding beginSend()/endSend() pairs. If the result.discard parameter (member) is true in a messageSendHop() call, the sequence ends there without a call to endSend(), and a messageDeleted() call will follow.

Implemented in cNullEnvir.

◆ messageSendDirect()

virtual void messageSendDirect	(	cMessage *	msg,
		cGate *	toGate,
		const ChannelResult &	result
	)

pure virtual

Part of the beginSend() sequence.

See also: beginSend()

Implemented in cNullEnvir.

◆ messageSendHop() [1/2]

virtual void messageSendHop	(	cMessage *	msg,
		cGate *	srcGate
	)

pure virtual

Part of the beginSend() sequence.

See also: beginSend()

Implemented in cNullEnvir.

◆ messageSendHop() [2/2]

virtual void messageSendHop	(	cMessage *	msg,
		cGate *	srcGate,
		const ChannelResult &	result
	)

pure virtual

Part of the beginSend() sequence.

See also: beginSend()

Implemented in cNullEnvir.

◆ endSend()

virtual void endSend ( cMessage * msg )

pure virtual

Closes a beginSend() sequence.

See also: beginSend()

Implemented in cNullEnvir.

◆ messageCreated()

virtual void messageCreated ( cMessage * msg )

pure virtual

Notifies the environment that a message object is being created. This is called from the cMessage constructor.

Implemented in cNullEnvir.

◆ messageCloned()

virtual void messageCloned	(	cMessage *	msg,
		cMessage *	clone
	)

pure virtual

Notifies the environment that a message object is being cloned. This is called from the cMessage copy constructor.

Implemented in cNullEnvir.

◆ messageDeleted()

virtual void messageDeleted ( cMessage * msg )

pure virtual

Notifies the environment that a message object is being deleted. This is called from the cMessage destructor, so any information added to cMessage via subclassing is already lost at the time of the call.

Implemented in cNullEnvir.

◆ moduleReparented()

virtual void moduleReparented	(	cModule *	module,
		cModule *	oldparent,
		int	oldId
	)

pure virtual

Notifies the environment that a module changed parent.

Implemented in cNullEnvir.

◆ componentMethodBegin()

virtual void componentMethodBegin	(	cComponent *	from,
		cComponent *	to,
		const char *	methodFmt,
		va_list	va,
		bool	silent
	)

pure virtual

Notifies the environment that one component (module) called a member function of another component. This hook enables a graphical user interface to animate the method call in the network diagram. Pass methodFmt==nullptr for Enter_Method_Silent.

Implemented in cNullEnvir.

◆ componentMethodEnd()

virtual void componentMethodEnd ( )

pure virtual

Notifies the environment that the method entered in the last componentMethodBegin() call has exited.

Implemented in cNullEnvir.

◆ moduleCreated()

virtual void moduleCreated ( cModule * newmodule )

pure virtual

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.

Implemented in cNullEnvir.

◆ moduleDeleted()

virtual void moduleDeleted ( cModule * module )

pure virtual

Notifies the environment that a module was (more precisely: is being) deleted. This method is called from cModule destructor, so the "real" type (getClassName() and everything from the actual subclass) is already lost at this point, however getName(), getFullName(), getFullPath(), 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.

Implemented in cNullEnvir.

◆ gateCreated()

virtual void gateCreated ( cGate * newgate )

pure virtual

Notifies the environment that a gates was created.

Implemented in cNullEnvir.

◆ gateDeleted()

virtual void gateDeleted ( cGate * gate )

pure virtual

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

Implemented in cNullEnvir.

◆ connectionCreated()

virtual void connectionCreated ( cGate * srcgate )

pure virtual

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

Implemented in cNullEnvir.

◆ connectionDeleted()

virtual void connectionDeleted ( cGate * srcgate )

pure virtual

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

Implemented in cNullEnvir.

◆ displayStringChanged()

virtual void displayStringChanged ( cComponent * component )

pure virtual

Notifies the environment that a module or channel display string has changed.

Implemented in cNullEnvir.

◆ undisposedObject()

virtual void undisposedObject ( cObject * obj )

inlinevirtual

Called from module destructors, to notify the environment about objects that the user did not delete in the module destructor.

Reimplemented in cNullEnvir.

◆ getCurrentEventName()

virtual const char* getCurrentEventName ( )

inlinevirtual

Returns the name of the event current being processed by the simulation kernel or nullptr if unknown.

◆ getCurrentEventClassName()

virtual const char* getCurrentEventClassName ( )

inlinevirtual

Returns the class name of the event currently being processed by the simulation kernel or nullptr if unknown.

◆ getCurrentEventModule()

virtual cModule* getCurrentEventModule ( )

inlinevirtual

Returns the module that is processing the current event or nullptr. Calling this function after the module has been already deleted returns nullptr.

◆ preconfigure()

virtual void preconfigure ( cComponent * component )

pure virtual

Called when a module or channel object has been created and added to the model, but no parameters or gates have been set up yet. It allows the environment perform extra configuration. One use is to set up RNG mapping.

Implemented in cNullEnvir.

◆ configure()

virtual void configure ( cComponent * component )

pure virtual

Called when a module or channel has been created and installed in the model, after parameters and gates have been set up, but before submodules and internal connections are added. This method lets the environment perform extra configuration.

Implemented in cNullEnvir.

◆ readParameter()

virtual void readParameter ( cPar * parameter )

pure virtual

Assigns the module or channel parameter from the configuration, or by asking the user.

Implemented in cNullEnvir.

◆ isModuleLocal()

virtual bool isModuleLocal	(	cModule *	parentmod,
		const char *	modname,
		int	index
	)

pure virtual

Used for parallel distributed simulation. Returns true if the named future submodule of parentmod is (or will have any submodule) in the local partition, and false otherwise. index should be -1 if the submodule is not in a module vector.

Note that for compound modules that contain simple modules in several partitions, this function will return true on all those partitions.

Implemented in cNullEnvir.

◆ getXMLDocument()

virtual cXMLElement* getXMLDocument	(	const char *	filename,
		const char *	xpath = `nullptr`
	)

pure virtual

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 is 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, there was a parse error, or the given path expression is invalid. It returns nullptr if the element denoted by the path expression does not 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.

Implemented in cNullEnvir.

◆ getParsedXMLString()

virtual cXMLElement* getParsedXMLString	(	const char *	content,
		const char *	xpath = `nullptr`
	)

pure virtual

Returns the parsed form of an XML content string. The first argument is the XML content string. 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 is 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 there was a parse error or if the given path expression is invalid. It returns nullptr if the element denoted by the path expression does not exist in the document.

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

Implemented in cNullEnvir.

◆ forgetXMLDocument()

virtual void forgetXMLDocument ( const char * filename )

pure virtual

Removes the given document from the XML document cache (if cached), and deletes the object tree from memory. Further getXMLDocument() calls will reload the file from the disk. After forgetXMLDocument(), cXMLElement objects returned for the same document by getXMLDocument() should no longer be referenced. The call has no effect if the given file does not exist or has not yet been loaded.

CAUTION: As of version 4.1, this is not a safe operation! Module parameters (cPar) of type "xml" hold pointers to the element trees returned by getXMLDocument(), and this method makes those pointers invalid.

Implemented in cNullEnvir.

◆ forgetParsedXMLString()

virtual void forgetParsedXMLString ( const char * content )

pure virtual

Removes the given document from the XML document cache (if cached), and deletes the object tree from memory. After forgetXMLDocument(), cXMLElement objects returned for the same content string by getParsedXMLString() should no longer be referenced. The call has no effect if the given string has not yet been parsed.

CAUTION: As of version 4.1, this is not a safe operation! Module parameters (cPar) of type "xml" hold pointers to the element trees returned by getXMLDocument(), and this method makes those pointers invalid.

Implemented in cNullEnvir.

◆ flushXMLDocumentCache()

virtual void flushXMLDocumentCache ( )

pure virtual

Clears the cache of loaded XML documents, and deletes the corresponding cXMLElement trees.

CAUTION: As of version 4.1, this is not a safe operation, as module parameters (cPar) of type "xml" hold pointers to the element trees returned by getXMLDocument(), and this method makes those pointers invalid.

Implemented in cNullEnvir.

◆ flushXMLParsedContentCache()

virtual void flushXMLParsedContentCache ( )

pure virtual

Clears the cache of parsed XML content strings, and deletes the corresponding cXMLElement trees.

CAUTION: As of version 4.1, this is not a safe operation, as module parameters (cPar) of type "xml" hold pointers to the element trees returned by getXMLDocument(), and this method makes those pointers invalid.

Implemented in cNullEnvir.

◆ getExtraStackForEnvir()

virtual unsigned getExtraStackForEnvir ( ) const

pure virtual

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

Implemented in cNullEnvir.

◆ getConfig()

virtual cConfiguration* getConfig ( )

pure virtual

Access to the configuration (by default, omnetpp.ini). This method 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.

Implemented in cNullEnvir.

◆ getConfigEx()

virtual cConfigurationEx* getConfigEx ( )

virtual

Returns the configuration as used by the Envir library. It will throw an error if the configuration object does not subclass from cConfigurationEx. This method should not be used from the simulation kernel or model code.

◆ resolveResourcePath()

virtual std::string resolveResourcePath	(	const char *	fileName,
		cComponentType *	context = `nullptr`
	)

pure virtual

Searches a number of folders for a resource given with its file name or relative path, and returns the path for the first match. If the resource is not found, the empty string is returned.

The list of the search folders includes the current working directory, the folder of the main ini file, the folder that the NED file of the given "context" type was loaded from, folders in the NED path, and folders in the image path (OMNETPP_IMAGE_PATH).

Implemented in cNullEnvir.

◆ isGUI()

virtual bool isGUI ( ) const

pure virtual

Returns true if the current environment is a graphical user interface. (For example, it returns true if the simulation is running in Qtenv, and false if it's running in Cmdenv.) Modules can examine this flag to decide whether or not they need to bother with visualization, e.g. dynamically updating display strings or drawing on canvases.

Implemented in cNullEnvir.

◆ isLoggingEnabled()

bool isLoggingEnabled ( ) const

inline

Returns true if logging is enabled. This is false in Express mode while the simulation is actually running.

◆ isExpressMode()

virtual bool isExpressMode ( ) const

pure virtual

Returns true if the simulation is running under a GUI in Express mode. Visualization code (e.g. inside module refreshDisplay() methods) may check this flag and adapt the visualization accordingly.

Implemented in cNullEnvir.

◆ bubble()

virtual void bubble	(	cComponent *	component,
		const char *	text
	)

pure virtual

In graphical user interfaces like Qtenv, it pops up a transient "bubble" over the module icon.

Implemented in cNullEnvir.

◆ log()

virtual void log ( cLogEntry * entry )

pure virtual

Log a line described by the entry.

Implemented in cNullEnvir.

◆ alert()

virtual void alert ( const char * msg )

pure virtual

Displays the given alert text in a conspicuous way, e.g. in a dialog box. This function should be used sparingly from models, if ever.

Implemented in cNullEnvir.

◆ printfmsg()

virtual void printfmsg	(	const char *	fmt,
			...
	)

virtual

A printf-like frontend for alert().

◆ gets()

virtual std::string gets	(	const char *	prompt,
		const char *	defaultReply = `nullptr`
	)

pure virtual

Interactively prompts the user to enter a string. This function should be used sparingly from models, if ever.

Implemented in cNullEnvir.

◆ askYesNo()

virtual bool askYesNo ( const char * prompt )

pure virtual

Asks the user a yes/no question with the given prompt. The return value is true for "yes", and false for "no". This function should be used sparingly from models, if ever.

Implemented in cNullEnvir.

◆ getImageSize()

virtual void getImageSize	(	const char *	imageName,
		double &	outWidth,
		double &	outHeight
	)

pure virtual

Returns the size of the image with the given name (e.g. "block/switch_l") in pixels. If the image does not exist, it returns the size of the "unknown" icon (as that is the image actually displayed). Non-GUI environments like Cmdenv may return made-up (but not completely unrealistic) numbers.

This method is used by some methods of cImageFigure, e.g. getBounds().

Implemented in cNullEnvir.

◆ getTextExtent()

virtual void getTextExtent	(	const cFigure::Font &	font,
		const char *	text,
		double &	outWidth,
		double &	outHeight,
		double &	outAscent
	)

pure virtual

Returns the size and ascent of the bounding box of the text when rendered with the given font in the GUI. Non-GUI environments like Cmdenv may return made-up (but not completely unrealistic) numbers.

This method is used by some methods of cTextFigure, e.g. getBounds().

Implemented in cNullEnvir.

◆ appendToImagePath()

virtual void appendToImagePath ( const char * directory )

pure virtual

Tells the user interface to load the images from the given directory, as if the directory was part of the the OMNeT++ image path. The loaded images can then be used in display strings and with cImageFigure/cIconFigure.

An error is thrown if the given directory does not exist or cannot be accessed. This method is idempotent: the second and further invocations with the same parameter have no effect. The method may have no effect if the simulation is running under Cmdenv or another non-graphical user interface.

Implemented in cNullEnvir.

◆ loadImage()

virtual void loadImage	(	const char *	fileName,
		const char *	imageName = `nullptr`
	)

pure virtual

Tells the user interface to load the image from the given image file. The loaded image can then be used in display strings and with cImageFigure/cIconFigure, by referencing it with the image name. If the location of the image file is not known or cannot be easily determined, resolveResourcePath() may be used to find it prior to loadImage().

The image name may be specified explicitly (in the imageName argument), or if it is missing (is nullptr or empty string), the base file name will be used (fileName with directories and extension stripped). Note that if an image with the given name has already been loaded, this method will do nothing, i.e. already loaded images are NOT replaced. This also means that the method is idempotent: the second and further invocations with the same parameter have no effect.

An error is thrown if the given file does not exist or cannot be loaded as a supported image format. The method may have no effect if the simulation is running under Cmdenv or another non-graphical user interface.

See also: resolveResourcePath()

Implemented in cNullEnvir.

◆ getSubmoduleBounds()

virtual cFigure::Rectangle getSubmoduleBounds ( const cModule * submodule )

pure virtual

Returns the effective bounding rectangle of the given module when it is visualized in the graphical inspector of its containing compound module, or (NAN,NAN,NAN,NAN) if such a rectangle is not available. This method is the only way to access positions of "floating" modules, i.e. those placed by a layouting algorithm that runs as part of the UI. The method may unconditionally return (NAN,NAN,NAN,NAN) when the simulation is running under Cmdenv or another non-graphical user interface.

Also note that this method may return different values at different times, e.g. as a result of the user opening and closing inspectors, hitting the "Relayout" button, or even changing the zoom level or icon size of graphical module inspectors displaying the parent module. Visualization code relying on this method is advised to re-read coordinates in every refreshDisplay() call, and check whether they changed since last time.

Implemented in cNullEnvir.

◆ getZoomLevel()

virtual double getZoomLevel ( const cModule * module )

pure virtual

Returns the current zoom level of a graphical module inspector displaying the given module (its contents from the inside, not as a submodule icon), or NAN if not available. A value of 1.0 means 100% zoom (actual size), 0.5 means 50% (half size), and so on. The method may unconditionally return NAN if the simulation is running under Cmdenv or another non-graphical user interface.

Also note that this method may return different values at different times, e.g. as a result of the user changing the zoom level, or even opening and closing inspectors. Visualization code relying on this method is advised to re-read the value in every refreshDisplay() call, and check whether it changed since last time.

Implemented in cNullEnvir.

◆ getAnimationTime()

virtual double getAnimationTime ( ) const

pure virtual

Returns the current animation time. Animation time starts from zero, and monotonically increases with simulation time and also during zero-simtime animations a.k.a. "holds". The method may return 0 if the simulation is running under Cmdenv or another non-graphical user interface.

Implemented in cNullEnvir.

◆ getAnimationSpeed()

virtual double getAnimationSpeed ( ) const

pure virtual

Returns the current animation speed. It is usually computed as the minimum of the animation speeds of visible canvases, unless the user interactively overrides it in the UI, for example imposes a lower limit. The method returns 0 if there is currently no animation speed, or the simulation is running under Cmdenv or another non-graphical user interface.

See also: cCanvas::setAnimationSpeed()

Implemented in cNullEnvir.

◆ getRemainingAnimationHoldTime()

virtual double getRemainingAnimationHoldTime ( ) const

pure virtual

Returns the remaining animation "hold" time. This is the maximum of the animation times remaining from the holds times requested by visible canvases.

See also: cCanvas::holdSimulationFor()

Implemented in cNullEnvir.

◆ getNumRNGs()

virtual int getNumRNGs ( ) const

pure virtual

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

Implemented in cNullEnvir.

◆ getRNG()

virtual cRNG* getRNG ( int k )

pure virtual

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

Implemented in cNullEnvir.

◆ registerOutputVector()

virtual void* registerOutputVector	(	const char *	modulename,
		const char *	vectorname
	)

pure virtual

This method is intended to be called by cOutVector objects to register themselves. The returned value is a handle that identifies the vector in subsequent recordInOutputVector() and deregisterOutputVector() calls. The handle may have any value (it does not have to be a valid pointer), but it should NOT be nullptr.

Implemented in cNullEnvir.

◆ deregisterOutputVector()

virtual void deregisterOutputVector ( void * vechandle )

pure virtual

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

Implemented in cNullEnvir.

◆ setVectorAttribute()

virtual void setVectorAttribute	(	void *	vechandle,
		const char *	name,
		const char *	value
	)

pure virtual

This method is called when an attribute of the output vector is set.

Implemented in cNullEnvir.

◆ recordInOutputVector()

virtual bool recordInOutputVector	(	void *	vechandle,
		simtime_t	t,
		double	value
	)

pure virtual

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

Implemented in cNullEnvir.

◆ recordScalar()

virtual void recordScalar	(	cComponent *	component,
		const char *	name,
		double	value,
		opp_string_map *	attributes = `nullptr`
	)

pure virtual

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

Implemented in cNullEnvir.

◆ recordStatistic()

virtual void recordStatistic	(	cComponent *	component,
		const char *	name,
		cStatistic *	statistic,
		opp_string_map *	attributes = `nullptr`
	)

pure virtual

Records a statistic object (histogram, etc) into the scalar result file. This operation may invoke the setUpBins() method on the histogram object.

Implemented in cNullEnvir.

◆ recordParameter()

virtual void recordParameter ( cPar * par )

pure virtual

Records a module or channel parameter, in a default configuration into the scalar result file.

Implemented in cNullEnvir.

◆ recordComponentType()

virtual void recordComponentType ( cComponent * component )

pure virtual

Records the runtime NED type of module or channel, in a default configuration into the scalar result file.

Implemented in cNullEnvir.

◆ addResultRecorders()

virtual void addResultRecorders	(	cComponent *	component,
		simsignal_t	signal,
		const char *	statisticName,
		cProperty *	statisticTemplateProperty
	)

pure virtual

Adds result recording listeners for the given signal on the given component. The result will be recorded to the the given component, with a name equal to or derived from the given statisticName. The statisticTemplateProperty parameter is expected to point to a @statisticTemplate NED property with content similar to @statistic properties. The computation and result type (scalar, vector, etc) will be taken from the 'record' key of statisticTemplateProperty in the same way as with @statistic. Also similar to @statistic, key-value pairs of statisticTemplateProperty will be recorded as result attributes.

In statisticTemplateProperty, the 'source' key will be ignored (because the signal given as parameter will be used as source). The actual name and index of statisticTemplateProperty will also be ignored. (With @statistic, the index holds the result name, but here the name is explicitly specified in the statisticName parameter.)

The purpose of this function is to allow setting up signal-based result recording dynamically when static configuration via @statistic properties is not possible, e.g. because the set of signals to record is only known at runtime.

Implemented in cNullEnvir.

◆ getStreamForSnapshot()

virtual std::ostream* getStreamForSnapshot ( )

pure virtual

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

Implemented in cNullEnvir.

◆ releaseStreamForSnapshot()

virtual void releaseStreamForSnapshot ( std::ostream * os )

pure virtual

Releases a stream after a snapshot was written.

Implemented in cNullEnvir.

◆ getArgCount()

virtual int getArgCount ( ) const

pure virtual

Access to original command-line arguments.

Implemented in cNullEnvir.

◆ getArgVector()

virtual char** getArgVector ( ) const

pure virtual

Access to original command-line arguments.

Implemented in cNullEnvir.

◆ getParsimProcId()

virtual int getParsimProcId ( ) const

pure virtual

Returns the partitionID when parallel simulation is active.

Implemented in cNullEnvir.

◆ getParsimNumPartitions()

virtual int getParsimNumPartitions ( ) const

pure virtual

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

Implemented in cNullEnvir.

◆ getUniqueNumber()

virtual unsigned long getUniqueNumber ( )

pure virtual

The function underlying cSimulation::getUniqueNumber().

Implemented in cNullEnvir.

◆ refOsgNode()

virtual void refOsgNode ( osg::Node * scene )

pure virtual

Used by cOsgCanvas to increase the reference count of an osg::Node. Should delegate to node->ref() when OSG support is available.

Implemented in cNullEnvir.

◆ unrefOsgNode()

virtual void unrefOsgNode ( osg::Node * scene )

pure virtual

Used by cOsgCanvas to increase the reference count of an osg::Node. Should delegate to node->unref() when OSG support is available.

Implemented in cNullEnvir.

◆ idle()

virtual bool idle ( )

pure virtual

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

Implemented in cNullEnvir.

◆ pausePoint()

virtual void pausePoint ( )

pure virtual

Potentially blocks the execution of model code when called. When using user interfaces (graphical environments) that support it, gives the user opportunity to examine the state of the simulation even in the middle of performing an event, and resume on demand. This is similar to how breakpoints work in debuggers.

Implemented in cNullEnvir.

◆ ensureDebugger()

virtual bool ensureDebugger ( cRuntimeError * error = nullptr )

pure virtual

Starts an external debugger program and attaches it to this process, if no already attached debugger is detected. The command line to start the debugger can be configured.

The error parameter points to the exception that is the reason a debugger is needed. If there is no error, just a simple request for debugging, it is nullptr.

Returns true if a debugger was already attached, or one could be started and attached successfully. Returns false if a debugger was not already attached and could not be started, or the user chose not to start and attach one.

Implemented in cNullEnvir.

◆ addLifecycleListener()

virtual void addLifecycleListener ( cISimulationLifecycleListener * listener )

virtual

Adds a listener that will be notified about simulation lifecycle events. It has no effect if the listener is already subscribed. NOTE: The listeners will NOT be deleted when the program exits.

◆ removeLifecycleListener()

virtual void removeLifecycleListener ( cISimulationLifecycleListener * listener )

virtual

Removes the given listener. This method has no effect if the listener is not currently subscribed.

◆ getLifecycleListeners()

virtual std::vector<cISimulationLifecycleListener*> getLifecycleListeners ( ) const

virtual

Returns the list of installed lifecycle listeners.

◆ notifyLifecycleListeners()

virtual void notifyLifecycleListeners	(	SimulationLifecycleEventType	eventType,
		cObject *	details = `nullptr`
	)

virtual

Notify lifecycle listeners

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

cenvir.h

Description

Public Member Functions

Constructor & Destructor Documentation

◆ cEnvir()

◆ ~cEnvir()

Member Function Documentation

◆ objectDeleted()

◆ componentInitBegin()

◆ simulationEvent()

◆ messageScheduled()

◆ messageCancelled()

◆ beginSend()

◆ messageSendDirect()

◆ messageSendHop() [1/2]

◆ messageSendHop() [2/2]

◆ endSend()

◆ messageCreated()

◆ messageCloned()

◆ messageDeleted()

◆ moduleReparented()

◆ componentMethodBegin()

◆ componentMethodEnd()

◆ moduleCreated()

◆ moduleDeleted()

◆ gateCreated()

◆ gateDeleted()

◆ connectionCreated()

◆ connectionDeleted()

◆ displayStringChanged()

◆ undisposedObject()

◆ getCurrentEventName()

◆ getCurrentEventClassName()

◆ getCurrentEventModule()

◆ preconfigure()

◆ configure()

◆ readParameter()

◆ isModuleLocal()

◆ getXMLDocument()

◆ getParsedXMLString()

◆ forgetXMLDocument()

◆ forgetParsedXMLString()

◆ flushXMLDocumentCache()

◆ flushXMLParsedContentCache()

◆ getExtraStackForEnvir()

◆ getConfig()

◆ getConfigEx()

◆ resolveResourcePath()

◆ isGUI()

◆ isLoggingEnabled()

◆ isExpressMode()

◆ bubble()

◆ log()

◆ alert()

◆ printfmsg()

◆ gets()

◆ askYesNo()

◆ getImageSize()

◆ getTextExtent()

◆ appendToImagePath()

◆ loadImage()

◆ getSubmoduleBounds()

◆ getZoomLevel()

◆ getAnimationTime()

◆ getAnimationSpeed()

◆ getRemainingAnimationHoldTime()

◆ getNumRNGs()

◆ getRNG()

◆ registerOutputVector()

◆ deregisterOutputVector()

◆ setVectorAttribute()

◆ recordInOutputVector()

◆ recordScalar()

◆ recordStatistic()

◆ recordParameter()

◆ recordComponentType()

◆ addResultRecorders()

◆ getStreamForSnapshot()

◆ releaseStreamForSnapshot()

◆ getArgCount()

◆ getArgVector()