4.9. Generating Type Support with rtiddsgen¶

4.9.1. Why Use rtiddsgen?¶

For Connext DDS Micro to publish and subscribe to 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 section on Creating User Data Types with IDL in the RTI Connext DDS Core Libraries User’s Manual (available here if you have Internet access).

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 target Connext DDS Micro when generating code with rtiddsgen, the -micro option must be specified on the command line.

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

> 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 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 Connext DDS Micro Applications¶

A 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 allows Connext DDS Micro users to select whether they 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 provide by two command-line arguments:

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

If neither of these two options are supplied to rtiddsgen, they will both be considered active and code for both DataReaders and DataWriters will be generated. If only one of the two options is supplied to rtiddsgen, only that one is enabled. If both options are supplied, both are enabled.

4.9.6. Unsupported Features of rtiddsgen with Connext DDS Micro¶

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.