Generating Type Support with rtiddsgen
======================================
    
Why Use rtiddsgen?
------------------

For |rti_me| to publish and subscribe topics of user defined types, the types 
have to be defined and programmatically registered with |me|.  A registered type 
is then serialized and deserialized by |me| through a pluggable type interface 
that each type must implement. 
    
Rather than have users manually implement each new type, |me| provides the 
*rtiddsgen* utility for automatically generating type support code.  

IDL Type Definition
-------------------

*rtiddsgen* for |me| accepts types defined in IDL. The HelloWorld examples 
included with |me| use the following HelloWorld.idl::
    
        struct HelloWorld {
            string<128> msg;
        };

For further reference, see the |rti_core_um_userdatatypes_idl|_ section of
the |rti_core_um|_ for |rti_core|.

Generating Type Support
-----------------------

Before running *rtiddsgen*, some environment variables must be set:

- ``RTIMEHOME`` sets the path of the |me| 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 |me| 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.

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

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
    
Notes on command-line options
............................. 

In order to taget |me| 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 |me|, 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.
    
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
  |me| uses to serialize and deserialize the type.
     
- UserTypeSupport.h and UserTypeSupport.c(xx) define type-specific *DataWriters* 
  and *DataReaders* for user-defined types.

Using custom data-types in an |rti_me_h| Application
----------------------------------------------------

An |me| 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.
   
Customizing generated code
--------------------------
   
*rtiddsgen* now enables |me| 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.
   
Unsupported Features of rtiddsgen with |rti_me_h|
-------------------------------------------------

|rti_me| supports a subset of the features and options in *rtiddsgen*.  
Use *rtiddsgen* ``-micro -help`` to see the list of features supported by 
*rtiddsgen* for |me|.
   
Of note, generation of example publisher/subscriber code and makefiles to
compile generated files is not yet available when targeting |me|.