Overview | All Modules | Tutorial | User's Guide | Programming Guide
Previous

COVISE Online Documentation

Next


Module Programming

The coModule Base Class

The base class for all module programming is coModule. An application is created by deriving a class of coModule. The constructor of the derived class creates the module layout with input ports, output ports and parameters. Virtual functions are overloaded to implement the module's reactions on events. Every COVISE module based on coModule looks like:

Header file:

class myMod: public coModule
{
   private:
      ... // parameter and data object ports

   public:
      myMod(int argc, char *argv[]);     // Constructor: module set-up
      virtual void compute(const char *);       // Called for every execute
      virtual void param(const char *, bool inMapLoading);
                                         // Called for param changes
      virtual void sockData(int sockNo); // Called for receiving data
}

Source code:

myMod::myMod(int argc, char *argv[])
: coModule(argc, argv, "My example module")
                               {...}    // build ports and parameters
myMod::compute(const char *)         {...}    // module is executed
myMod::param(const char *, bool inMapLoading)
                               {...}    // parameters changed
myMod::postInst(const char *)  {...}    // between c'tor and main loop
myMod::quit(const char *)      {...}    // after the end of main loop
myMod::sockData(int socNo)     {...}    // data arrived on a socket

MODULE_MAIN(SomeCategory, myMod)

To allow future use of threads and multi-linked modules, modules should use neither global nor non-constant static variables.

coModule's Functions

Constructor

The constructor of a module is used to set up its external connectivity. First, it calls the constructor of the base class coModule:

      void coModule::coModule(int argc, char *argv[], const char *description=NULL, bool propagate=false)

The constructor of coModule establishes some basic data structures and pre-sets them with defaults values.

The execution of a module constructor is time-critical. If the constructor is not finished within the timeout period given in the config file, the CRB will not accept the module and the user interface will issue an error message telling that the module did not start.

In general, the constructor should never do anything else than defining the ports and parameters of the module.




postInst

For any additional functionality required before entering the main loop the routine

      virtual void coModule::postInst()

should be overloaded by the module. It is called once before entering the main event loop. This avoids timeouts, which could occur as described in the constructor paragraph.




param

Since COVISE 6.1, a module is notified immediately unconditionally when a parameter was changed by the user (i. e. all parameters are ``immediate'' now). For any changed parameters, the callback

      virtual void coModule::param(const char *paramName, bool inMapLoading)

is called with the name of the port as the parameter.




compute

The compute callback is called whenever new input data for a module is available or when the user executes a module manually.

      virtual int coModule::compute(const char *)

Before calling the user supplied routine, the input objects are retrieved from the data manager and the object pointer is stored to be retrieved from the port. The return value of the compute callback must be either CONTINUE_PIPELINE or STOP_PIPELINE depending on whether modules below should be executed or not.

Most modules only need a compute function and do not use the other functions. All functions are pre-initialized with empty functions in case the user does not overload them. A warning is submitted if compute(const char *) is executed without being overloaded.




sockData

If a module needs to use any other external communication means than the COVISE internal networking, e. g. connect to a simulation or use the X Window system, the programmer has to make sure that COVISE messages are still received and handled. Therefore, a file descriptor, e. g. a socket, can be registered with the module via

      void addSocket(int fd)

Once this has been done, COVISE adds the socket to its own sockets and calls the virtual function

      virtual void coModule::sockData(int fd)

with the file descriptor as the argument. The user can then handle the input and return control to COVISE by leaving the callback. After use, the socket is removed using

      void removeSocket(int fd)




quit

A module terminates either when COVISE terminates, the user deletes a module or a new map is loaded. To allow cleaning up resources, the routine

      virtual void coModule::quit()

is automatically called before the module quits.




idle

The idle function is called whenever the module waits for COVISE messages.

      virtual float coModule::idle()

You should not block in this function, otherwise the module will never get the chance to process incomming messages. If you overwrite this method, you have to return a float value. This value specifies the maximum number of seconds to wait until the idle function is called again. If zero is returned, the idle function is called again immediately after checking for COVISE messages. If a negative value is returned, the idle function will not be called until any message arrived. If a positive Value is returned, the idle function will be called after the appropriate time, or earlier if any message arrived.

Remember: You can't create COVISE distributed objects in this callback!




Other coModule functions

      virtual void feedback(int len, const char *data);

This function is called when a COVER plugin sends a feedback message.

      virtual void feedbacksetInfo(int len, const char *datatext);

Allows to set an info string in the control panel of the module.

coSimpleModule Set-Handler

COVISE can handle hierarchical structures of data created by Set containers, e.g. timestep series or data sets consisting of multiple distinct parts. A module handling these data types has to be written recursively to be able to handle arbtrary levels of hierarchy. In most cases, modules work with `corresponding' data, e.g. a set of geometry objects required an identical set of colors and normals, or a set of timesteps of a moving grid simulation corresponds to a similar set of data values.

For easier module development, the class coSimpleModule has been derived from coModule. It automatically un-packs all level of Set containers until reaching the lowes level, and then calls compute(const char *) for each low-level object. The module developer simply creates the module and writes a compute(const char *) function as if the data was non-hierarchical, which is then called for every corresponding set of low-level object.

The functions

      void setComputeTimesteps(const int off);    // 0 by default
      void setComputeMultiblock(const int off);   // 0 by default

can be called if the user wants to handle timesteps or multiblock data himself, e.g. for particle tracing.

The simple module also automatically copies all attributes from the input objects to the output objects at the port directly underneath the input port. If this is not desired, it can be switched of by calling

      void setCopyAttributes(const int on);      // 1 by default

Ports and Parameters

Ports establish the connection of a module to the rest of the COVISE system. Three different kinds of connections can be defined:

  1. Parameters: Values interactively set in the Map-Editor by the user
  2. Input data ports: Receive data from other modules
  3. Output data ports: Send data to other modules

All ports and parameters are created by calling a member function of coModule that returns a pointer to a port class object, which can later be used to set or retrieve port data. These pointers will usually be stored as module class private data being usable in the whole module.

The creation of ports and parameters only possible in the Constructor state, a later creation of ports is not supported. Ports can be hidden or de-activated if not currently needed.



Never create Modules with variable numbers of Ports or Parameters: These modules will crash COVISE when being read from a map file!



All ports and parameters must have a unique name and description, which can be any text explaining the function of the port. Names must not contain blank characters or any special ASCII characters like TAB, CR, LF, DEL, BS. The description may contain blanks, but no special characters like CR, LF or BS characters and need not be unique.

Never construct a port or parameter by its own constructor, COVISE must register it with the module. Instead, the functions add<type>Port and add<type>Param have to be used.

All input and parameter ports derive from the same base class coUifElem, which implements some base functionality for all kinds of ports. The following subroutines can therefore be called for all parameter and port class objects:

const char *coUifElem::getName() const
Description: Get port's name
COVISE states: all
Return value: Port name

const char *coUifElem::getDesc() const
Description: Get port's description
COVISE states: all
Return value: Port description

virtual void coUifElem::print(ostream &str) const
Description: Print port information into a stream
COVISE states: all
IN: str stream to print into

Data Ports

When replacing modules, data port connections can only be maintained if the ports adhere to a common naming scheme. A port name should start with a prefix from the following table. If the port is able to accept data types from several lines in this table, then choose ``Data'', except for when it is Geometry and grid types, then choose ``Grid''. As appropriate, append ``In'' or ``Out'' to the prefix. Finally you should append the number of the port: start with ``0'' for the first port with a certain prefix and direction, and increase the number for each other port with the same prefix and direction. Also append the final ``0'' if there is only one port of this type.

Name prefix Data object types
Data Int, Float, Vec2, Vec3, RGBA, Mat, Tensor
Grid Points, Spheres, Lines, Polygons, TriangleStrips,

UniformGrid, RectilinearGrid, StructuredGrid, UnstructuredGrid

Geometry Geometry
Texture Texture

Data ports are created by:

coInputPort *coModule::addInputPort(const char *name,const char *typeList, const char *desc)
Description: Create an Input data port
COVISE states: Constructor
IN: name: Port name
IN: typeList: Map editor data types
IN: desc: Parameter description
Return Value: pointer to newly created port

coOutputPort *coModule::addOutputPort(const char *name, const char *typeList, const char *desc)
Description: Create an Output data port
COVISE states: Constructor
IN: name: Port name
IN: typeList: Map editor data types
IN: desc: Parameter description
Return Value: pointer to newly created port

The parameter types string lists all type names of objects allowed to connect with this port divided by a `|' character, e.g.:

      "Float|Vec3"

The type string must not contain any blanks, otherwise it is not possible to connect the ports in the map editor. This type information is only given to the map editor, which then prohibits connections between ports without common types. The port information does not imply any checking of data types assigned to the port by the module, so type-checking must still be implemented in the module. The reason for not checking the data types according to the map editor types is to allow different usage of the same data type by different map editor types enforcing correct connections.

By default, a module only executes (i.e. calls its compute callback) if all input ports of a module are connected. By declaring a port 'not required', the pipeline will also be executed without a connection to this port. The module will then receive a NULL pointer when trying to retrieve the port's data.

void coInputPort::setRequired(int isRequired)
Description: declare a port (not) required
COVISE states: Compute
IN: isRequired =0:not required, else required

Whenever the compute(const char *) callback is called by the main loop, the data objects at the input ports are opened and can be read by calling the input port's getCurrentObject() method. If the port is not connected, or if an error occurs, a NULL pointer is returned.

A non-required input port can be declared as a `dependency' of an output port, meaning it becomes required if this output port is connected.

void coOutputPort::setDependency(coInputPort *port)
Description: declare an output port dependending on a certain input
COVISE states: Constructor
IN: port port depended upon

If no data is available on a connected port, the compute callback is not called and the start message is silently ignored. This allows a direct flow control by not creating some of the defined output objects which leads to branches of the data flow network that are not executed.

coDistributedObject *coInputPort::getCurrentObject()
Description: Retrieve input data
COVISE states: Compute
Return value: Object received at the port

The resulting object pointer is a pointer to a derived class of coDistributedObject, which can be casted up to the real class. To find the correct type, the base class member function getType() can be used.

const char *coOutputPort:: getObjName()
Description: get object name for output objects
COVISE states: Compute
Return value: pointer to name for new data object

This call delivers the appropriate name to create data objects for an output port. The return value must be given to the constructor of the object, which is then assigned to the port for sending it to all connected modules by

void coOutputPort::setCurrentObject(coDistributedObject *obj)
Description: Assign output data object to port
COVISE states: Compute



The output object will be sent to all connected modules after the compute(const char *) callback has finished and is then automatically deleted. Examples for object creation and receiving can be found in the example modules under covise/src/examples.

The tool-tip text, which appears when right-clicking on a port, can be set by:

void coPort::setInfo(const char *text)
Description: set tooltip text
COVISE states: After initialisation (postInst, compute, ...)
IN: text tooltip text

Parameters


Common functions

All parameter classes are derived from coUifPara, which offers common functions for all kinds of parameter ports:

To allow direct interaction with the module, all parameter changes are immediately sent to the module and the module's param() callback is fired. If the callback does not react on the parameter, the value is still updated, but no further action is taken.

A parameter can be mapped into the Control Panel by clicking the checkbox in the Module Set-up window. Nevertheless, the module programmer can control the mapping by calls to the functions:

void coUifPara::show()
Description: Show/Hide a parameter in the control panel
COVISE states: PostInst, all Main-Loop callbacks

void coUifPara::hide()
Description: Show/Hide a parameter in the control panel
COVISE states: PostInst, all Main-Loop callbacks

Parameters can also be disabled by the module. If a parameter is disabled, it is displayed in gray both in the Module set-up panel and in the control panel and no parameter changes are possible. Parameter disabling is typically used for parameters that are only required under certain circumstances, e.g. in simulation couplings, which can have different sets of parameters depending on the simulation case.

void coUifPara::enable()
Description: Enable or disable parameter
COVISE states: PostInst, all Main-Loop callbacks

void coUifPara::disable()
Description: Enable or disable parameter
COVISE states: PostInst, all Main-Loop callbacks


Boolean Parameter



A Boolean parameter can only have the values TRUE (NONZERO) or FALSE (=0).

The default value of a Boolean parameter is FALSE.

A Boolean parameter is created by:

coBooleanParam *coModule::addBooleanParam (const char *name, const char *desc)
Description: Create a Boolean parameter
COVISE states: Constructor
IN: name: Parameter name
IN: desc: Parameter description
Return value: pointer to new created port

This function creates a new port and registers it at the module for receiving port messages. The value of a Boolean Parameter can be requested and set by the program using:

int coBooleanParam::getValue()
Description: get Value of a Boolean parameter
COVISE states: all
Return value: Value of the parameter

int coBooleanParam::setValue(int value)
Description: set Value of a Boolean parameter
COVISE states: all
IN: value value to be set
Return value: =0 on error, =1 on success

A typical code fragment is:

myModule.h

class myModule
{
   private:

      coBooleanParam *p_shadeFlag;
      ...
   
}

myModule.cpp

myModule::myModule()   // ... build ports and parameters
{
  // create the boolean port: declared as member variable
  p_shadeFlag = addBooleanParameter("shade","apply shading");
 
  // set a default value

  p_shadeFlag->setValue(1);
}

myModule::compute(const char *)    // ... e.g. in the compute callback
{
  int shading = p_shadeFlag->getValue();
  ...
}

It is a good habit to mark all ports and parameters with a common prefix. In our examples we have chosen names that start with 'p_'.


Scalar Parameter





There are integer and float scalar parameters. Both represent a single value of the corresponding type. The integer scalar parameter is exactly identical to the float one except for replacing "...Float..." by "...Int..." in the names of functions and changing the data types.

Both float and integer scalar parameters default to 0.

A float scalar parameter is created by:

coFloatParam *coModule::addFloatParam
(const char *name, const char *desc)
Description: Create a float scalar parameter
COVISE states: Constructor
IN: name: Parameter name
IN: desc: Parameter description
Return value: pointer to newly created port

The value of a scalar parameter can be requested/set by the program using:

float coFloatParam::getValue()
Description: get Value of a float scalar parameter
COVISE states: all
Return value: Value of the parameter

int coFloatParam::setValue(float value)
Description: set Value of a float scalar parameter
COVISE states: all
IN: value value to be set
Return value: =0 on error, =1 on success

The corresponding commands for the integer scalar parameter are:

coInt32Param *coModule::addInt32Param(const char *name,
                                              const char *desc)
long coInt32Param::getValue()
int coInt32Param::setValue(long value)

A typical code fragment is:

myModule.h

class myModule
{
   private:

      coFloatParam *p_timestep;
      coInt32Param   *p_numsteps;
      ...
        
}

myModule.cpp

myModule::myModule()   // ... build ports and parameters
{
   p_timestep=addFloatParam ("timestep","length of a timestep");
   p_numsteps=addFloatParam ("numsteps","number of steps");
  
   // set a default values
   p_timestep->setValue(0.001);
   p_numsteps->setValue(100);
}

myModule::compute(const char *)    // compute callback
{
   float timestep =  p_timestep->getValue();
   int   numsteps =  p_numsteps->getValue(); // we can access it here!
   ...
}

myModule::param(const char *portname)      // param callback
{
   if ( strcmp(portname,numsteps->getName()) )  
      .... do something when the user changes number of steps
}


Slider Parameter



Sliders can also be either of type float or integer: Both of them have a minimum, maximum and a `current' value, which can be set or requested by the module.

Float sliders default to 0...0.5...1.0, int sliders to 0...127...255.

A Slider parameter is created by:

coFloatSliderParam *coModule::addFloatSliderParam (const char *name, const char *desc)
Description: Create a float slider parameter
COVISE states: Constructor
IN: name: Parameter name
IN: desc: Parameter description
Return value: pointer to newly created port

The value of a slider parameter can be requested/set by the program using:

void coFloatSliderParam::getValue (float &min, float &max, float &value)
Description: get Value of a float slider parameter
COVISE states: Constructor
IN: min/max lower/upper bound of slider
IN: value current value of slider
Return value: none

void coFloatSliderParam::setValue (float min, float max, float value)
Description: set Value of a float slider parameter
COVISE states: all
IN: min/max/value value to be setlike getValue()
Return value: =0 on error, =1 on success

Single values can also be requested or set:

   float coFloatSliderParam::getMin()
   float coFloatSliderParam::getMax()
   float coFloatSliderParam::getValue()
   void  coFloatSliderParam::getMin(float min)
   void  coFloatSliderParam::getMax(float max)
   void  coFloatSliderParam::getValue(float value)

As for the scalar parameter, there are corresponding integer functions, exactly like theirs float counterparts but with "Int" in the name and integer return/param type.

A typical code fragment is:

myModule.h

class myModule
{
   private:

      coFloatSliderParam *p_relax;
      ...
         
}

myModule.cpp

myModule::myModule()   // ... build ports and parameters
{
   p_relax=addFloatSliderParam ("p_relax","relaxation factor");
   p_relax->setValue(0.0,1.0,0.95);
}
 
myModule::compute(const char *)    // compute callback
{
   float relax =  p_relax->getValue();
   ...
 
   // if the relaxation is too high, we push it down...
   relax = relax * 0.9;
   p_relax->setValue(relax);
}


Vector Parameter



Vectors are parameters with an arbitrary number of scalar values. The number of fields is not limited by the system, but since there is no numbering in the control panel, it should be limited to a small number for clarity reasons.

Both integer and float vector parameters default to 3D null vectors.

A vector parameter is created with a default size of 3 elements by:

coFloatVectorParam *coModule::addFloatVectorParam (const char *name, const char *desc)
Description: Create a float vector parameter
COVISE states: Constructor
IN: name: Parameter name
IN: desc: Parameter description
Return value: pointer to newly created port

This is the only way for a user to specify vector parameters with another size than three elements.

The value of any vector parameter can be requested by the program using:

float coFloatVectorParam::getValue (int pos)
Description: get value of one element in a float vector parameter
COVISE states: all
IN: pos select which element to get
Return value: requested value

If the position parameter is out of bounds, a warning is issued and 0 is returned.

A single value of a scalar parameter can also be set by the module:

int coFloatVectorParam::setValue(int pos, float value)
Description: set value of one element in a vector parameter
COVISE states: all
IN: pos select which element to get
IN: value value to be set
Return value: =0 on error, =1 on success

To change the number of values in the field, an array can be used to initialize the parameter:

int coFloatVectorParam::setValue(int numElem, float *field)
Description: set number of elements and set all values
COVISE states: all
IN: numElem select which element to get
IN: field value to be set
Return value: =0 on error, =1 on success

Since 3-dimensional vectors are used very often, commodity functions for dealing with 3D vectors are defined:

int coFloatVectorParam::setValue (float data0, float data1, float data2)
Description: set 3-element vector parameter values
COVISE states: all
IN: data1...3 values to be set
Return value: =0 on error, =1 on success

All these functions are also defined for integer vectors:

coIntVectorParam*coModule::addIntSliderParam(const char *name, const char *desc);
int coIntVectorParam::getValue(int pos, long &value);
int coIntVectorParam::setValue(int pos, long value);
int coIntVectorParam::setValue(int numElem, long *field);
int coIntVectorParam::setValue(Int data0, long data1, Int data2);


String Parameter



A string is a 0-terminated sequence of characters.

The default value is the string "no default val".

A string parameter is created by:

CoStringParam *coModule::addStringParam (const char *name, const char *desc)
Description: Create a string parameter
COVISE states: Constructor
IN: name: Parameter name
IN: desc: Parameter description
Return value: pointer to newly created port

The value of a string parameter can be requested by the program using:

const char *coStringParam::getValue()
Description: get value of a string parameter
COVISE states: all
Return value: Value of the parameter

The value of a string parameter can also be set by the module:

int coStringParam::setValue(const char *val)
Description: set value of a string parameter
COVISE states: all
IN: val new value for the parameter
Return value: =0 on error, =1 on success


File Browser



A File Browser parameter allows the selection of a file on the host the module is running on.

The File Browser parameter cannot be updated by the module. setValue calls outside the constructors are ignored.

A Browser parameter is created by:

coFileBrowserParam *coModule::addFileBrowserParam (const char *name, const char *desc)
Description: Create a browser parameter
COVISE states: Constructor
IN: name: Parameter name
IN: desc: Parameter description
Return value: pointer to newly created port

The value of a browser parameter can be requested by the program using:

const char *coFileBrowserParam::getValue()
Description: get filename selected in a browser parameter
COVISE states: all
Return value: value of the parameter

The start value of a browser parameter must be set by the module in the constructor

int void coFileBrowserParam::setValue (const char *defaultFile, const char *mask)
Description: set the initial value of a file browser
COVISE states: all
IN: defaultFile default file name with path
IN: mask file selection mask, e.g. "*.dat"
Return value: =0 on error, =1 on success


Choice Parameter



A choice parameter allows to select one entry from a list of given choice strings.

A choice parameter is created by:

coChoiceParam *coModule::addChoiceParam (const char *name, const char *desc)
Description: Show a parameter in control panel
COVISE states: Constructor
IN: name: Parameter name
IN: desc: Parameter description
Return value: pointer to newly created port

The active choice list entry can be retrieved by:

int coChoiceParam::getValue()
Description: get value of a choice parameter
COVISE states: all
Return value: active choice, count starts with 1

The choice list can be set by:

int coChoiceParam::setValue(const char *val)
Description: set value of a choice parameter
COVISE states: all
IN: val new value for the parameter
Return value: =0 on error, =1 on success

int coChoiceParam::setValue
(int num, const char * const *label, int active)
Description: set value of a choice parameter
COVISE states: all
IN: num number of entries
IN: label array of strings:
define as `char *arr[num]'
IN: active pre-set value: count starts with 1
Return value: =0 on error, =1 on success

If you want to use the same contents of a choice parameter, even if it appears at a different position (number) use the update function:

int coChoiceParam::updateValue
(int num, const char * const *label, int active)
Description: set value of a choice parameter
COVISE states: all
IN: num number of entries
IN: label array of strings:
define as `char *arr[num]'
IN: active pre-set value: count starts with 1, use current label if possible. If this is possible, ignore active
Return value: =0 on error, =1 on success

The current value can be set by:

int coFloatVectorParam::setValue(int pos, float value)
Description: set value of one element in a vector parameter
COVISE states: all
IN: pos select which element to get
IN: value value to be set
Return value: =0 on error, =1 on success

See the example code $COVISEDIR/src/examples/UpdateChoice for an example using all features of the Choice parameter.


Parameter switching groups

Parameters can be grouped in the control panel. The syntax for grouping parameters is:

paraSwitch("top_switch","Now switch Parameters"); // switch with 
                                                     name and label
   paraCase("First possibility label");    // first possibility 
      // ... all parameters we want to change in this group
   paraEndCase();
   paraCase("other possibility");   // Next switch possibility
      // ... all parameters we want to change in this group
      // second level of switching 
      paraSwitch("subSwitch","Sub-Cases"); // nested switch 
         paraCase("one case");
            // ...parameters // one case
         paraEndCase();
         paraCase("other case");
            // ...parameters
         paraEndCase();
      // second level of switching ends here
      paraEndSwitch();
   // The `Scalar' case ends here
   paraEndCase();
paraEndSwitch();

Each paraSwitch call creates a `master' choice parameter, which automatically shows and hides the parameters of its paraCase groups. The name of the choice is the first parameter of the paraSwitch command, while the labels of the paraSwitch and all following paraCase commands are automatically added to the choice list. As the first choice, the `master' displays its own label and shows none of its cases.

The user can access the switch choices as usual choice parameters using the setValue command, e.g. to change the choice labels, but the assignment between choice result number and paraCase can not be influenced, so choice number 1 always is `no parameters', number 2 the first case, number 3 the second and so on. This feature will typically be used to de-activate complete cases from the control panel.

Notice: the module set-up panel will always show ALL parameters of the module.

The example program TestUIF shows the implementation of a 2-level hierarchy of switched parameter groups.

coChoiceParam *coModule::paraSwitch(const char *choiceName, const char *label)
Description: Start parameter switching group,
define name and top label of choice
COVISE states: Constructor
IN: choiceName Unique parameter port name
IN: label Label for the choice
Return value: Pointer to the `master' choice port

void coModule::paraEndSwitch()
Description: End parameter switching group
COVISE states: Constructor

int coModule::paraCase(const char *label)
Description: Start a case within a switched group and give corresponding choice label
COVISE states: Constructor
IN: label Label for the choice
Return value: -1 on error, 0 on success

void coModule::paraEndCase()
Description: End a group within a switched parameter area
COVISE states: Constructor


COVISE configuration database

COVISE has a central configuration database, which resides in XML files in the $COVISEDIR/config directory or in the .covise subdirectory of the user's home directory.

The configuration database is accessed by calling static methods of the coCoviseConfig singleton.

Several functions are provided to access entries in the configuration database. Most of these access functions require a single 'entry' parameter Scope.Var. This 'entry' parameter describes the path along which to descend in the tree of nested XML elements. Elements are separated by a dot ("."). However, the first two path elements are defined implictly (e. g. "COCONFIG.GLOBAL") and must not be specified. For all data types, there are two kinds of query functions. Those taking only an 'entry', return the value of the "value" attribute of the corresponding XML element. For querying another attribute, you have to use the method with 'variable' and 'entry' arguments.

Consider the following configuration file:

<?xml version="1.0"?>
<COCONFIG version="1">
 <GLOBAL>
  <Module>
   <MyModule>
    <BufferSize value="1024" />
   </MyModule>
  <Module>
 </GLOBAL>
</COCONFIG>
The "value" attribute of "BufferSize" could be queried with coCoviseConfig::getInt("value", "Module.MyModule.BufferSize") or coCoviseConfig::getInt("Module.MyModule.BufferSize").

const char *getEntry(const char *entry)
const char *getEntry(const char *variable, const char *entry)
Description: get a single string entry
IN: entry path to XML tag
IN: variable attribute, the value of which should be returned
Returns value of configuration

int getInt(const char *entry)
int getInt(const char *variable, const char *entry)
Description: get a single string entry
IN: entry path to XML tag
IN: variable attribute, the value of which should be returned
Returns value of configuration

long getLong(const char *entry)
long getLong(const char *variable, const char *entry)
Description: get a single string entry
IN: entry path to XML tag
IN: variable attribute, the value of which should be returned
Returns value of configuration

float getFloat(const char *entry)
float getFloat(const char *variable, const char *entry)
Description: get a single string entry
IN: entry path to XML tag
IN: variable attribute, the value of which should be returned
Returns value of configuration

bool isOn(const char *entry)
bool isOn(const char *variable, const char *entry)
Description: get a single string entry
IN: entry path to XML tag
IN: variable attribute, the value of which should be returned
Returns value of configuration

const char **getScopeEntries(const char *scope))
Description: get all entries of one scope
IN: scope name of scope
Returns NULL-terminated array, alternating
name0,value0,name1,value1,...valuen,NULL

const char *getScopeEntry (const char *scope, const char *name)
Description: get a single entry
IN: scope Scope to be looked in
IN: name Name of variable
Returns value of scope.name

PreviousNext


Authors: Martin Aumüller, Ruth Lang, Daniela Rainer, Jürgen Schulze-Döbold, Andreas Werner, Peter Wolf, Uwe Wössner
Copyright © 1993-2016 HLRS, 2004-2014 RRZK, 2005-2014 Visenso
COVISE Version 2016.3