5.2 - Interacting Directly with the RTI

Table of Contents

• 5.2.1 Building Applications for Use with the RTI 1516 Specification
• 5.2.2 Federate-Initiated Services
• 5.2.3 RTI-Initiated Services
  • 5.2.3.1 Subclassing DtVrlFederateAmbassador
  • 5.2.3.2 Telling DtExerciseConn About Your Derived Class

Although most applications based on VR-Link will never need to access the RTI directly (VR-Link functions make the RTI calls for you), some applications will want the flexibility of making their own calls to the RTI.

Often, you will want to mix and match, letting VR-Link handle most interaction with the RTI, while handling some of it directly within the same application.

The RTI's API contains two main classes: the RTIambassador and the FederateAmbassador. When a DtExerciseConn is constructed, it creates instances of both of these classes.

5.2.1 Building Applications for Use with the RTI 1516 Specification

We have tried to maintain source compatibility between the 1.3 and 1516 versions of VR-Link. Most types in the 1516 RTI API have the same name as in the 1.3 RTI API. The exceptions are as follows:

• In pre-1516 versions of VR-Link, RTI classes were prefaced with RTI::. This convention effectively created an RTI namespace. The new RTI 1516 API has a true namespace called rti1516. The HLA Evolved API has a true namespace called rti1516e. In rtiCompatibility.h we rename both namespaces to RTI to provide backwards compatibility. This was intended by the RTI API standards committee.
• The RTI 1516 API eliminated the AttributeHandleValuePairSet class. It was replaced by a std::map<AttributeHandle, VariableLengthData> type. To preserve source compatibility with VR-Link encoders and decoders that were written to use the AttributeHandleValuePairSet, we added a wrapper class, called AttributeHandle- ValuePairSet, which is passed to all encoders and decoders. This preserves source compatibility. The definition of this class is in the file rtiCompatibility.h.
• The 1516 RTI uses std::wstring (wide strings) instead of char* or std::string (narrow strings). VR-Link uses narrow strings and converts the narrow strings to wide strings for RTI calls. If you mix VR-Link and RTI calls, you must take this difference into account.

5.2.2 Federate-Initiated Services

Federate-initiated services, such as publishObjectClass(), updateAttributeValues(), and sendInteraction(), are invoked by making calls to the RTI ambassador's member functions.

A DtExerciseConn's RTI ambassador is available through the rtiAmb() member function. Use this object to invoke any federate-initiated RTI services. The object returned by rtiAmb() is an instance of the class DtVrlRtiAmbassador, which serves as a wrapper around RTI::RTIambassador. (DtVrlRtiAmbassador has the same member functions as RTI::RTIambassador, but the functions are declared virtual, so that they can be overwritten by application code.)

For example, to call the RTI's queryAttributeTransportationType() service:

DtExerciseConn exConn(...);
...
DtVrlRtiAmbassador* rtiAmb = exConn.rtiAmb();
rtiAmb.queryAttributeTransportationType(...);

5.2.3 RTI-Initiated Services

RTI-initiated services, such as discoverObject(), reflectAttributeValues(), and receiveInteraction(), are invoked when the RTI calls virtual member functions of RTI::FederateAmbassador() from within RTI::RTIambassador::tick(). Federates are responsible for deriving a class from RTI::FederateAmbassador and providing definitions for these pure virtual functions.

Normally, this responsibility is satisfied through VR-Link's DtVrlFederateAmbassador class (defined in vrlFederateAmbassador.h). This class is derived from RTI::FederateAmbassador, and includes definitions for all virtual functions (though some are empty definitions).

5.2.3.1 Subclassing DtVrlFederateAmbassador

For direct access to the data the RTI provides through RTI-initiated services, you can derive your own class from DtVrlFederateAmbassador and implement new definitions for the virtual functions in your subclass. In general, you should call the DtVrlFederateAmbassador versions of these functions from your versions, to insure that any VR-Link functionality that may depend on this continues to work.

The following example shows a subclass of DtVrlFederateAmbassador that uses the RTI-initiated service initiatePause. The implementation of DtVrlFederateAmbassador's initiatePause() member function is empty. VR-Link does not take any action by default when this service is invoked by the RTI. If you want your application to be able to handle this service invocation, you can provide your own definition for the initiatePause() virtual function.

This example is for HLA 1.3.

class MyFedAmb : public DtVrlFederateAmbassador
{
public:
   virtual void initiatePause(const RTI::PauseLabel label)
      throw (RTI::FederateAlreadyPaused, RTI::FederateInternalError);
};
void MyFedAmb::initiatePause(const RTI::PauseLabel label)
      throw (RTI::FederateAlreadyPaused, RTI::FederateInternalError)
{
   // Your code to handle the pause
   ...
   // Call superclass version in case it's 
   // doing anything important
   DtVrlFederateAmbassador::initiatePause(label);
}

5.2.3.2 Telling DtExerciseConn About Your Derived Class

After you create a subclass of DtVrlFederateAmbassador, you need to tell DtExerciseConn that it should use an instance of your class rather than the default DtVrlFederateAmbassador as its federate ambassador. To tell DtExerciseConn about your subclass, use the static member function DtExerciseConn::setFedAmbCreator(). This function expects a DtFedAmbCreator() function as an argument – a function that returns a new instance of a DtVrlFederateAmbassador or a subclass of it. The current DtFedAmbCreator() is called in the DtExerciseConn constructor, so you need to call setFedAmbCreator() before the DtExerciseConn is constructed.

A FedAmbCreator() function for the MyFedAmb class might look like this:

DtVrlFederateAmbassador* MyFedAmbCreator()
{
   return new MyFedAmb();
}

Tell the DtExerciseConn class about this function before creating a DtExerciseConn instance as follows:

DtExerciseConn::setFedAmbCreator(MyFedAmbCreator);
...
// The DtExerciseConn we create here will use a MyFedAmb as
// its federate ambassador
DtExerciseConn exConn(...);

A DtExerciseConn's DtVrlFederateAmbassador is available through its fedAmb() member function.

[<< Introduction to the HLA-Specific Interface] [Home] [Top of Page] [Getting Information About the FOM >>]