3.10. Generating Type Support with rtiddsgen¶

3.10.1. Why Use rtiddsgen?¶

For Connext Micro to publish and subscribe to topics of user-defined data types, the types must be defined and programmatically registered with Connext Micro. A registered type is then serialized and deserialized by Connext Micro through a pluggable interface that each type must implement.

Rather than manually implementing each new type yourself, Connext Micro provides you with the rtiddsgen IDL compiler to generate type support code.

3.10.2. IDL Type Definition¶

rtiddsgen for Connext Micro accepts types defined in IDL. The HelloWorld examples included with Connext Micro use the following HelloWorld.idl:

struct HelloWorld
{
    string<128> msg;
};

For further reference, see the section on Creating User Data Types with IDL in the RTI Connext DDS Core Libraries User’s Manual.

3.10.3. Generating Type Support¶

Before running rtiddsgen, you must set some environment variables:

RTIMEHOME sets the path to the Connext Micro installation directory.
JREHOME sets the path for a Java JRE.

Note

A JRE is shipped with Connext Professional on platforms supported for the execution of rtiddsgen (Linux®, Windows®, and macOS®). It is not necessary to set JREHOME on these platforms, unless a specific JRE is preferred.

3.10.3.1. Generating type support for C¶

Run rtiddsgen from the command line to generate C language type support for a UserType.idl (and replace any existing generated files):

> $rti_connext_micro_root/bin/rtiddsgen -micro -language C -replace UserType.idl

3.10.3.2. Generating type support for C++¶

Run rtiddsgen from the command line to generate C++ language type-support for a UserType.idl (and replace any existing generated files):

> $rti_connext_micro_root/bin/rtiddsgen -micro -language C++ -replace UserType.idl

Note

Connext Micro only supports traditional C++.

3.10.3.3. Notes on command line options¶

In order to generate type support for Connext Micro with rtiddsgen, you must specify the -micro option on the command line.

To list all command-line options specifically supported by rtiddsgen for Connext Micro, enter:

> rtiddsgen -micro -help

Note

You might notice that the previously available options -language microC and -language microC++ have been replaced with -micro -language C and -micro -language C++, respectively. It is still possible to specify microC and microC++ for backwards compatibility, but we advise switching to using the -micro command-line option along with other arguments.

3.10.3.4. Generated type support files¶

rtiddsgen will produce the following header and source files for each IDL file passed to it:

UserType.h and UserType.c (.cxx for C++) implement creation/initialization and deletion (only for Connext Micro) of a single sample and a sequence of samples of the type (or types) defined in the IDL description.
UserTypePlugin.h and UserTypePlugin.c (.cxx for C++) implement the pluggable type interface that Connext Micro uses to serialize and deserialize the type.
UserTypeSupport.h and UserTypeSupport.c (.cxx for C++) define type-specific DataWriters and DataReaders for user-defined types.

3.10.4. Using Custom Types in Connext Micro Applications¶

A Connext Micro application must include the generated headers and register the type with the DomainParticipant before a topic of that type can be created. For an example HelloWorld type, the following code registers the type with the participant and then creates a topic of that type:

#include "HelloWorld.h"
#include "HelloWorldPlugin.h"
#include "HelloWorldSupport.h"

/* ... */

retcode = HelloWorldTypeSupport_register_type(application->participant,
                                              "HelloWorld");
if (retcode != DDS_RETCODE_OK)
{
    /* Log an error */
    goto done;
}

application->topic =
    DDS_DomainParticipant_create_topic(application->participant,
                                       "Example HelloWorld",
                                       "HelloWorld",
                                       &DDS_TOPIC_QOS_DEFAULT, NULL,
                                       DDS_STATUS_MASK_NONE);

if (application->topic == NULL)
{
    /* Log an error */
    goto done;
}

The generated source files must be compiled and linked with the application. See the full HelloWorld examples for further reference.

3.10.5. Customizing Generated Code¶

rtiddsgen allows you to select whether you want to generate code to subscribe to and/or publish a custom data type. When generating code for subscriptions, only those parts of code dealing with deserialization of data and the implementation of a typed DataReader endpoint are generated. Conversely, only those parts of code addressing serialization and the implementation of a DataWriter are considered when generating publishing code.

Control over these options is provided by two command-line arguments:

-reader generates code for deserializing custom data-types and creating DataReaders for the type.
-writer generates code for serializing custom data-types and creating DataWriters for the type.

If neither of these two options are supplied to rtiddsgen, both DataReaders and DataWriters will be generated. If both options are supplied, both are enabled.

3.10.6. Unsupported Features of rtiddsgen with Connext Micro¶

Connext Micro supports a subset of the features and options in rtiddsgen. Use rtiddsgen -micro -help to see the list of features supported by rtiddsgen for Connext Micro.