Object Messages

Table of Contents

• Object Message Types
  • Task Messages
  • Set Data Request Messages
  • Report Messages
  • Admin Messages
• Simulation Internal Messages
• Radio Messages
  • Creating Custom Communication Models
• Sending Object Messages
• Receiving Object Messages

An object message, implemented by the class DtVrfObjectMessage, is used to communicate between VR-Forces siulation objects.

Object messages are sent using one of the message passing systems in VR-Forces.

There are two ways to send a message between simulation objects: the simulation internal message system and the radio message system. All object message can be sent via either method.

All communication within a particular sim object is managed by the DtVrfObjectCommunicationInterface class. This class has member functions for sending messages and for registering callbacks for message receipt.

Object Message Types

There are four types of object messages, each represented by a subclass of DtVrfObjectMessage. Each subclass overrides the pure virtual method DtVrfObjectMessage::contentCategoryType() to return a value indicating which of the four message types it represents. These types are defined in messageTypes.h.

Each of these types of DtVrfObjectMessage functions as an envelope for content classes that contain the data of the message. When sending a message, you first create an instance of the specific content subclass, and then add it to an instance of the appropriate message class.

Task Messages

Instances of DtTaskMessage are derived from DtVrfObjectMessage and are used to tell a simulation object to perform some task. Examples of tasks include moving to location and firing on a target. These messages may be sent to a simulation object as a result of:

• The planning engine executing a task statement in the simulation object's plan
• A directive from a superior simulation object
• A task command in the GUI

In all cases, the task (a subclass of DtSimTask object) is packaged inside of a DtTaskMessage and sent to the appropriate simulation object, usually by radio. (For details, please see See Sending Object Messages and Receiving Object Messages.) The DtTaskMessage class maintains its own copy of the DtSimTask it is carrying. You set the task in the message by calling its setTask() member function, giving it a pointer to a DtSimTask. The DtTaskMessage class makes its own copy of the task, so the memory pointed to by the DtSimTask that you passed into the DtTaskMessage class should be deleted in the calling application code.

New task messages can be created by creating a new subclass of DtSimTask. See the example Add Task (addTaskSim) for more details.

For more information on the VR-Forces tasking system, see Tasks and Sets.

Set Data Request Messages

Instances of DtSetDataRequestMessage are derived from DtVrfObjectMessage and are used to tell a simulation object to immediately change some aspect of its current state. Examples of set data requests include setting the location, damage state, or ordered speed. These messages may be sent to a simulation object as a result of:

• The planning engine executing a set data request statement in the simulation object's plan
• A directive from a superior simulation object
• A set data request in the GUI

In all cases, the set data request (a subclass of DtSetDataRequest object) is packaged inside of a DtSetDataRequestMessage and sent to the appropriate simulation object, usually by radio. (For details, please see Sending Object Messages and Receiving Object Messages.) The DtSetDataRequestMessage class maintains its own copy of the DtSetDataRequest it is carrying. You set the task in the message by calling its setSetDataRequest() member function, giving it a pointer to a DtSetDataRequest. The DtSetDataRequestMessage class makes its own copy of the request, so the memory pointed to by the DtSetDataRequest that you passed into the DtSetDataRequestMessage class should be deleted in the calling application code.

New set data request messages can be created by creating a new subclass of DtSetDataRequest. See the example Add Set (addSetSim) for more details.

For more information on the VR-Forces set data request system, see Tasks and Sets.

Report Messages

Reports are messages sent between simulation objects, usually via radios. They are used for exchanging information between simulation objects, such as task status, situation reports, or intelligence.

DtSimReport is the abstract base class from which all report classes should be derived. In order to send the report, it gets placed inside of an instance of DtReportMessage, which is derived from DtVrfObjectMessage. Components send and receivereport messages in the same way that they do for task and set data messages. See Sending Object Messages and Receiving Object Messages for details.

Admin Messages

Admin Messages are sent both between simulation objects and between simulation objects and GUIs (or other applications using the Remote Control API). These messages are for simulation administration purposes, and do not fall into any of Task, Set Data Request, or Report categories. For example, requests for the available tasks and formations, as well as the responses to those requests, use Admin Messages.

DtAdminContent is the abstract base class from which all admin content types are derived. An instance of DtAdminContent subclass is placed inside an instance of the DtAdminMessage class for transportation. This is a subclass of DtVrfObjectMessage and can be sent using the same transport mechanisms as all other object messages. See Sending Object Messages and Receiving Object Messages.

Simulation Internal Messages

Messages that are for simulation purposes only are sent though the simulation internal system. These messages are not simulations of real-world messages. They are encoded into Data interactions, similar to Interface Messages. Examples of messages that VR-Forces sends using the internal message system are Set Location messages sent by the VR-Forces GUI when an object is repositioned on the map and tasks initiated by the GUI user.

Radio Messages

Messages that are sent between simulation objects that represent actual radio traffic are sent though the radio message system. Only other simulation objects that have radios configured on them are able to receive radio messages. A simulation object can have more than one radio, and messages can be sent and received on any of the radios on the simulation object. Radio messages are sent over the network inside signal interactions or signal PDUs.

Examples of messages that VR-Forces sends using the radio message system include spot reports and text reports that a simulation object can be tasked to send from the GUI.

The radio system in VR-Forces has two major pieces: the radio on the simulation object (DtVrfRadio or subclass) and the communication model (DtCommModel) associated with the radio. The radio handles message operations for a specific radio on a specific object. When a message is sent from a radio, that radio passes the message to the communication model with which it is associated. The communication model then processes the message, and based on communication model parameters, passes the message to any recipient radios. The radios on the recipient simulation objects then process the message and invoke any callbacks that have been registered on that radio.

Both the radios and the communication models can be configured. For details, please see "Configuring Radios", and "Configuring Communication Models" in VR-Forces Users Guide.

Creating Custom Communication Models

You can create new communication models and install them in VR-Forces. This is useful if you want to define your own connectivity model, or write your own algorithms for determining if radio messages get delivered.

Communication model classes are derived from DtCommModel and are generated from the communication model factory based on the string types specified in ./data/simulationModelSets/<model_set>/commModelParams.mtl. A communication model entry contains parameters for the type of communication model descriptor and communication model class being used.

To create a custom communication model, create a new class derived from DtCommModel, or one of its existing subclasses, and implement the sendMessage() member function. This is the member function that is called by a radio when that radio is sending a message. The communication model must then locate other radios on its list of registered radios, and call receiveMessage() on each radio that should receive the message. The communication model can delay the receipt of a message for as long as it likes, and can choose not to deliver a message at all.

If all you want to do is change the connectivity model of the simple radio communication model, derive from DtSimpleRadioCommModel and implement the checkRadioConnectivity() member function, which determines if two simulation objects are on the same network or not.

After you define the communication model, register it with the DtCommModelFactory, as follows:

cgf()->factoryManager()->commModelFactory()->addCreatorFcn("custom-comm-model", myCommModel::create);

Add the new communication model to commModelParams.mtl, as follows:

(default-radio-model
   (comm-model-descriptor-type "simple-radio-comm-model-descriptor")
   (comm-model-type "custom-comm-model")
    …

VR-Forces includes code for an example plugin that adds a custom communication model. Please see Add Comm Model (addCommModel) for more details.

Sending Object Messages

All messages are sent using the following generic procedure:

1. Create and fill in a message content class.
2. Create a DtVrfObjectMessage subclass to wrap the content class.
3. Fill in the DtVrfObjectMessage subclass with the content and recipient information.
4. Call one of the sendMessage() member functions on the DtVrfObjectCommunicationInterface of the sending object.

The communication interface fills in the proper data for the message sender.

Messages can be addressed to a specific simulation object by specifying its UUID in the recipient field. Two special recipient strings are also defined.

• DtVrfObjectMessageSendToAll - This indicates that the message should be sent to all simulation objects.
• DtVrfObjectMessageFrontEndAddress - This indicates that the message should be sent to the GUI as well as other applications using the Remote Control API. While most object mesages are sent between simulation objects, some can also be sent from a simulation object to a Remote Control application.

The following example illustrates how to construct a text report object message.

DtTextReport textReport;
textReport.setText("text");
DtReportMessage reportMsg;
reportMsg.setRecipient(receiversUuid);
reportMsg.setReceiverIsEchelonId(false);
reportMsg.setReport(&textReport);

Sending Simulation Internal Messages

Internal messages are for simulation purposes only and are not meant to represent real-world messages broadcast over radio between object. To send an internal message, you would use DtVrfObjectCommunicationInterface::sendSimInternalMessage.

vrfObject->communicationInterface()->sendSimInternalMessage(&reportMsg);

Sending Radio Messages

Radio messages represent communications sent between objects in the simulation. An object can have multiple radios, so when you send messages using the radio system, you must choose which radio to send the message on. You can specify the radio by name, ID, or as the default radio. The radio name is the string that identifies the desired radio in the entity’s OPE file. The radio ID is the index of the radio on the local simulation object, starting with 0, and reflects the order the radios are defined in the entity’s OPE file. The default radio is always the first radio listed in the OPE file, and is equivalent to radio ID 0.

To send the DtTextReport assembled above using the default radio, use the following call:

vrfObject->communicationInterface()->sendRadioMessage(&reportMsg);

To send the message with a named radio, use the following call:

vrfObject->communicationInterface()->sendRadioMessage("radio-name", &reportMessage);

To send the message with a specific radio ID, use the following call:

vrfObject->communicationInterface()->sendRadioMessage(2, &reportMessage);

The default configuration for most VR-Forces simulation objects has one radio, so it is usually appropriate to send messages using the default radio.

Receiving Object Messages

Simulation objects receive messages based on callback functions registered with message processing classes. The message processing class that you register a callback with depends on which message system is being used to transport the message. All message receipt is handled by the DtVrfObjectCommunicationInterface class on the sim object that is receiving the message.

Message Receipt Callback Member Functions

The signature for the callback member function registered with any of the message receipt callback lists is:

void processMessage(const DtVrfObjectMessage* message, void* usr);

As with other callbacks in VR-Forces, this must be a static function. The void* usr parameter is an arbitrary pointer that can be passed in when registering the callback, and will be returned as a parameter to the callback function. A null pointer can be passed if no callback pointer is needed. Typical usage is to pass a pointer to a specific instance of a class, and have the static callback member function call a non-static member of that class when it is invoked.

Receiving Specific Types of Messages

Message receipt callbacks can be registered in the following ways:

• To register a callback that will be invoked when any message is received by a simulation object, register the callback like this:

  vrfObject->communicationInterface()->addMessageCallback(processMessage, this);

• To register for a particular type of message, such as a text report message, register the callback by type:

  vrfObject->communicationInterface()->addMessageCallback(DtTextReportType, processMessage, this);

• To register a callback for all messages of a particular category, such as all task messages or all report messages, use the form:

  vrfObject->communicationInterface()->addMessageCallbackByCategory(DtReportMessageType, processMessage, this);

Receiving Messages from Specific Sources

Messages arrive at a simulation object through either the simulation internal message system or one of its radios. Callbacks that are registered directly with the communication interface of a simulation object, as shown above, are invoked when a message arrives from any source. This is the most common way to receive messages, and the way that all internal VR-Forces components work. However, it is sometimes useful to register callbacks directly with one of the source systems within the communication interface. You can do this by querying the communication interface for the desired source object, which will be either a DtVrfRadio or the DtSimInternalCommunicationInterface, and then registering the callback with that object. Callbacks are registered with these objects the same way that they are registered with the DtVrfObjectCommunicationInterface.

To register a callback for receipt of a report received on the internal communicaiton interface:

vrfObject->communicationInterface()->simInternalCommunicationInterface()->addMessageCallback(DtReportMessageType, processMessage, this);

To register a callback for receipt of a text report received on the default radio:

vrfObject->communicationInterface()->defaultRadio()->addMessageCallback(DtTextReportType, processMessage, this);