cenvir.h

//==========================================================================
//  CENVIR.H - part of
//                     OMNeT++/OMNEST
//            Discrete System Simulation in C++
//
//==========================================================================

/*--------------------------------------------------------------*
  Copyright (C) 1992-2017 Andras Varga
  Copyright (C) 2006-2017 OpenSim Ltd.

  This file is distributed WITHOUT ANY WARRANTY. See the file
  `license' for details on this and other legal matters.
*--------------------------------------------------------------*/

#ifndef __OMNETPP_CENVIR_H
#define __OMNETPP_CENVIR_H

#include <sstream>
#include <iostream>
#include "simkerneldefs.h"
#include "simtime_t.h"
#include "opp_string.h"
#include "clistener.h"  // for simsignal_t
#include "clifecyclelistener.h"
#include "ccanvas.h"

namespace osg { class Node; }

namespace omnetpp {

class cObject;
class cOwnedObject;
class cLogEntry;
class cEvent;
class cMessage;
class cPar;
class cGate;
class cComponent;
class cComponentType;
class cModule;
class cSimpleModule;
class cStatistic;
class cProperty;
class cRNG;
class cXMLElement;
class cEnvir;
class cConfiguration;
class cConfigurationEx;

using std::endl;

// internal macro, usage: EVCB.beginSend(...)
#define EVCB  cSimulation::getActiveEnvir()->suppressNotifications ? (void)0 : (*cSimulation::getActiveEnvir())

class SIM_API cEnvir
{
    friend class evbuf;
  public:
    // Internal flag for express mode.
    bool loggingEnabled;

    // Internal flag. When set to true, the simulation kernel MAY omit calling
    // the following cEnvir methods: messageScheduled(), messageCancelled(),
    // beginSend(), messageSendDirect(), messageSendHop(), messageSendHop(),
    // messageSendHop(), messageDeleted(), moduleReparented(), simulationEvent(),
    // componentMethodBegin(), moduleCreated(), moduleDeleted(), connectionCreated(),
    // connectionDeleted(), displayStringChanged().
    bool suppressNotifications;

    // Debugging. When set, cRuntimeError constructor executes a debug trap/launches debugger
    bool debugOnErrors = false;

  public:

    cEnvir();

    virtual ~cEnvir();


    // note: this cannot be pure virtual, because it has to work even after ev was disposed of
    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) = 0;

    virtual void messageSendDirect(cMessage *msg, cGate *toGate, simtime_t propagationDelay, simtime_t transmissionDelay) = 0;

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

    virtual void messageSendHop(cMessage *msg, cGate *srcGate, simtime_t propagationDelay, simtime_t transmissionDelay, bool discard) = 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;

    // Note: this may not be pure virtual, as it may get called even after main()
    // exited and StaticEnv was destructed, and we do not want to get a "pure virtual
    // method called" error
    virtual void undisposedObject(cObject *obj) {}

    virtual const char *getCurrentEventName() { return nullptr; }

    virtual const char *getCurrentEventClassName() { return nullptr; }

    virtual cModule *getCurrentEventModule() { return nullptr; }


    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;

    virtual bool isGUI() const = 0;

    bool isLoggingEnabled() const { return loggingEnabled; }

    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 double getZoomLevel(const cModule *module) = 0;

    virtual double getAnimationTime() const = 0;

    virtual double getAnimationSpeed() const = 0;

    virtual double getRemainingAnimationHoldTime() const = 0;


    virtual int getNumRNGs() const = 0;

    virtual cRNG *getRNG(int k) = 0;


    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;


    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 addResultRecorders(cComponent *component, simsignal_t signal, const char *statisticName, cProperty *statisticTemplateProperty) = 0;


    virtual std::ostream *getStreamForSnapshot() = 0;

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

    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 bool ensureDebugger(cRuntimeError *error = nullptr) = 0;


    virtual void addLifecycleListener(cISimulationLifecycleListener *listener) = 0;

    virtual void removeLifecycleListener(cISimulationLifecycleListener *listener) = 0;

    // internal. TODO it swallows exceptions, which is sometimes desirable, sometimes not!
    virtual void notifyLifecycleListeners(SimulationLifecycleEventType eventType, cObject *details=nullptr) = 0;
};


class SIM_API cRunnableEnvir : public cEnvir
{
  public:
    virtual int run(int argc, char *argv[], cConfiguration *cfg) = 0;
};

}  // namespace omnetpp

#endif