4.9. Generating Type Support with rtiddsgen¶

4.9.1. Why Use rtiddsgen?¶

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

Rather than have users manually implement each new type, Connext DDS Micro provides the rtiddsgen utility for automatically generating type support code.

4.9.2. IDL Type Definition¶

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

struct HelloWorld {
    string<128> msg;
};

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

4.9.3. Generating Type Support¶

Before running rtiddsgen, some environment variables must be set:

RTIMEHOME sets the path of the Connext DDS Micro installation directory
RTIMEARCH sets the platform architecture (e.g. i86Linux2.6gcc4.4.5 or i86Win32VS2010)
JREHOME sets the path for a Java JRE

Note that a JRE is shipped with Connext DDS Micro on platforms supported for the execution of rtiddsgen (Linux, Windows, and Mac OS X). It is not necessary to set JREHOME on these platforms, unless a specific JRE is preferred.

4.9.3.1. C¶

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

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

4.9.3.2. C++¶

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

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

4.9.3.3. Notes on command-line options¶

In order to taget Connext DDS Micro when generating code with rtiddsgen, the -micro option must be specified on the command line.

It is possible to list all command-line options specifically supported by rtiddsgen for Connext DDS Micro, by doing:

> cd $rti_connext_micro_root/rtiddsgen/scripts
> rtiddsgen -micro -help

Existing users might notice that that previously available options, -language microC and -language microC++, have now been replaced by -micro -language C and -micro -language C++ respectively. It is still possible to specify microC and microC++ for backwards compatibility, but users are advised to switch to using the -micro command-line option along with other arguments.

4.9.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(xx) implement creation/intialization and deletion of a single sample and a sequence of samples of the type (or types) defined in the IDL description.
UserTypePlugin.h and UserTypePlugin.c(xx) implement the pluggable type interface that Connext DDS Micro uses to serialize and deserialize the type.
UserTypeSupport.h and UserTypeSupport.c(xx) define type-specific DataWriters and DataReaders for user-defined types.

4.9.4. Using custom data-types in an RTI Connext DDS Micro Application¶

An Connext DDS Micro application must first of all include the generated headers. Then, it must register the type with the DomainParticipant before a topic of that type can be defined. For an example HelloWorld type, the following code registers the type with the participant and then creates a topic of that type:

#include "HelloWorldPlugin.h"

/* ... */

retcode = DDS_DomainParticipant_register_type(application->participant,
                                              "HelloWorld",
                                              HelloWorldTypePlugin_get());
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;
}

See the full HelloWorld examples for further reference.

4.9.5. Customizing generated code¶

rtiddsgen now enables Connext DDS Micro users to select whether they want to generate code to subscribe and/or publish a custom data-type. When generating code for subscription, only those parts of code dealing with deserialization of data and the implementation of a typed DataReader endpoint are generated. Conversevely, only those parts of code addressing serialization and the implementation of a DataWriter are considered when generating publishing code.

Control over these option is provide by two command-line arguments:

-reader generates code for deserializing custom data-types and creating DataReaders from them.
-writer generates code for serialiazing custom data-types and creating DataWriters from them.

If none of these two options is supplied to rtiddsgen, they will be both considered active, and code for both DataReaders and DataWriters will be generated. If any of the two is specified then only those passed as command line are enabled.

4.9.6. Unsupported Features of rtiddsgen with RTI Connext DDS Micro¶

RTI Connext DDS 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 DDS Micro.

Of note, generation of example publisher/subscriber code and makefiles to compile generated files is not yet available when targeting Connext DDS Micro.