An application programmers interface exists to allow the construction of user written collaborative modules. These modules can then operate within the COVISA framework in the same way as any other collaborative module. All of the collaborative data sharing modules supplied with this release use this library, and their source code can be found in $EXPLORERHOME/src, where $EXPLORERHOME is the root directory of the installed IRIS Explorer tree. Some annotated source code is available.

To compile a collaborative module, you must select Collaborative under Module->Options... within Module Builder.  You must write your collaborative code in C++; this may of course be combined with other code written in C or Fortran.

COVISA collaboration class for IRIS Explorer

Name

Synopsis

Constructor and Destructor from class cxCollab:

cxCollab(void);
~cxCollab(void);

Methods from class cxCollab:

int portRegister(int numPorts, char **names, int *portTypes, int *dataTypes);
int portRegister(char *name, int portType, int dataType);

void checkWidgets(void);
int isConnected(void);
int newData(char *name);

int setData(char *name, void *ptr);
int sendData(int numPorts, char **names);
int sendData(char *name);
void clearData(char *name);

cxLattice * getLattice(char *name);
cxParameter * getParameter(char *name);
cxPyramid * getPyramid(char *name);
cxGeo * getGeometry(char *name);

Description

Constructors

Creates an instance of cxCollab. It should be created as a static variable so that state parameters within the class are not lost between firings of an IRIS Explorer module.

Methods

Registers a name to be associated with a data object that is to be shared. It requires a name, a port type and a datatype. Port types are either INPUT or INTERNAL. An INPUT type associates the given name with a module input port. Sending data of type INPUT takes the current data object on that named port and passes it into the collaborative session. An INTERNAL type takes a reference to an IRIS Explorer data object created within the module during its execution and passes it into the collaborative session. Data types are either PARAMETER, LATTICE, PYRAMID or GEOMETRY and correspond directly to the IRIS Explorer datatype of that name.

Registers a number of ports at one time to be associated with a data object that is to be shared. See above for a description of the parameters.

A number of reserved widgets are required to make this system work. The reserved names are :- 
Initiate, Connection_State, Join, ID, Name, Application. 
This function checks the state of these widgets and takes appropriate action. It should be called once on each firing.

Checks whether the module is currently connected to the collaborative session. Returns 1 (TRUE) if it is connected, else 0 (FALSE).

Checks whether there is any new data associated with a registered name. Returns 1 (TRUE) if it is a valid registered name and new data has arrived else 0 (FALSE).

For port types of type INTERNAL, the pointer to the data object to be sent must be set before calling sendData. After sendData has been called, the internal pointer is reset to NULL. Returns 1 (TRUE) if successful, else 0 (FALSE).

Send the data associated with a given registered port name. If the port type is INPUT, then the module input port of that name will be opened and the current data sent. If the port type is internal then the data associated with that name by a previous call to setData will be sent. Returns 1 (TRUE) if successful, else 0 (FALSE). Failure will occur if the name given does not match one of the registered port names.

As above but sends multiple data objects in a single message. This minimises the number of firings of the attached modules in the session. Returns 1 (TRUE) if successful, else 0 (FALSE). Failure will occur if the name given does not match one of the registered port names.

To be more memory efficient, the incoming data object held by the named port may be deleted once it has been used. If not deleted, it remains until a new data object is sent from the session, this has the advantage that it may be re-referenced.

Get the incoming data object, which should be a lattice, from the named port. Returns NULL on error.

Get the incoming data object, which should be a parameter, from the named port. Returns NULL on error.

Get the incoming data object, which should be a pyramid, from the named port. Returns NULL on error.

Get the incoming data object, which should be a geometry, from the named port. The geometry is returned as a piece of scene graph under the returned geometry node. It should be instanced using a call to cxGeoInventorDefine. Returns NULL on error.

• Initiate
• Join
• ID
• Name
• Connection_State
• Application