7 - The DDS Broker API

The DDS Broker API is in the libDdsBroker library.

It is built on the Broker API. The DDS Broker Library is the full implementation of the DDS broker.

DtDdsBroker (ddsBroker.h) is the central class in libDdsBroker. It is a subclass of DtBroker that connects to a DDS partition execution using a DtDdsDomainConnection. The DtDdsBroker instance also opens a connection to Qt to process the broker's GUI. This instance is created by DtDdsBrokerApp (ddsBrokerApp.h).

The DtDdsBroker is responsible for creating object and interaction translators, configuring the DDS connection through a DtDdsBrokerInitializer (ddsBrokerInitializer.h) instance, and giving each translator processor time by calling tick().

The DtDdsBroker instance manages DtTranslator. There are two subclasses of DtTranslator: DtInteractionTranslator and DtObjectTranslator. The DtDdsBroker creates a translator for each message type. Each translator is responsible for translating its message type to a DDS class and back. Interaction translators register for updates for their interaction type. They translate the updates and pass them to their local DDS partition or the Portal, as appropriate.

Object translators register for object discovery, update, and removal messages, then translate and publish them to the Portal or DDS partition. A DtBrokerObject is maintained for every object the translator knows about. The broker object contains pointers to the reflected object, the publisher, and other data about the object, such as whether it has been discovered or filtered.

You can create translators in the following ways:

• Create translators that override existing translators. You would do this if you want to replace the functionality of an existing translator.
• Create a translator to add a new type of message to the broker.

When you create a translator class, you must create a static function called translatorName() that returns a c-string. For example, the DtEntityTranslator class's code is equivalent to the following:

static const char* DtEntityTranslator::translatorName()
{
   Return "Entity State";
}

If you want to override this class, you add the same function to your class:

static const char* MyNewEntityTranslator::translatorName()
{
   Return "Entity State";
}

If you want to add a new type of translator, you provide a new name:

static const char* MyAppleTranslator::translatorName()
{
   Return "Apple";
}

The translator name is displayed on the Translators page of a connection's information dialog box.

Note

You must enable translators.

Brokers that want to replace a translator should register their translator with the factory after creating the DtDdsBroker. The broker should then tell the DtDdsBroker instance to load all its translators. For example, code to replace the Entity translator would look like this:

// Create a DDS broker application. This creates the DtDdsBroker 
// instance and registers all the default translators. It is initialized
// with a DtDdsBrokerInitializer object; in this case, ddsInit.
DtDdsBrokerApp brokerApplication( ddsInit );

// Register a new translator creator for entities. Its factory knows 
// this class creates entities because the method translatorName() 
// returns a c-string called "Entity State"
brokerApplication.ddsBroker()->objectTranslatorFactory()
   ->addCreator<MyNewEntityTranslator>();

// run() calls the creator functions to load all required translators. It
// uses the creators registered in the previous lines of code.
brokerApplication->run();

[<< The DIS Broker API] [Home] [Top of Page] [The TENA Broker API >>]