6. Capabilities and Interfaces

6.1. Operating System Environment

RTI Connext TSS has been implemented using the POSIX API calls prescribed for the applicable conformance profile. This usage has been validated using the FACE Conformance Test Suite (CTS).

6.2. TSS Capabilities

RTI Connext TSS supports the following TSS capabilities:

  • Distribution Capability
  • Configuration Capability
  • QoS Management Capability

RTI Connext TSS generates support code with the rtiddsgen tool to enable these capabilities.

6.2.1. Type Support

DDS is a strongly typed API that requires explicit definition of the data types to be used. The definition is provided in a platform and language neutral description such as IDL.

Once this definition is provided, the rtiddsgen tool is used to generate type support code for the given data type(s). The generated code (for a specific language) contains the definition of:

  • the type itself,
  • the DataWriter and DataReader code,
  • serialization and deserialization code, and
  • other utilities needed to use the data type in DDS systems.

In a DDS application, the generated type support is ‘registered’ with a DomainParticipant via an explicit call:

HelloWorldTypeSupport_register_type(participant, type_name);

Essentially, this function installs a type support plugin that registers the various type-specific utilities so that the DDS core can use the type.

The FACE TSS API is also strongly typed. The modified version of the rtiddsgen tool provided with Connext TSS will generate both the type support required by the underlying DDS and the type plugin required by Connext TSS.

The generated type plugin files (i.e., HelloGoodbye, HelloGoodbyePlugin, HelloGoodbyeSupport, and HelloGoodbye_TypeSupport) should not need any modification. If, however, multiple IDL files have been used, the _TypeSupport.c files will need to be modified to define just one RTI_TSS_get_type_support() function between them and for that function to provide type plugins for all types across all IDLs.

6.2.2. Configuration Support

The FACE TSS specification requires the TSS library to be initialized via configuration that is provided via:

  • a function that is compiled/linked into the library
  • an XML file that is opened and read by the library
  • a Configuration Service that provides the data through the TSS itself

Only configuration through a function is currently supported by the Connext TSS library. This function, RTI_TSS_ConfigData_get_config_data(), is in a file initially generated by the rtiddsgen tool (e.g, HelloGoodbye_Config.c). Although this is sufficient for an example to work, it would likely need modification by the FACE UoP developer or the TSS integrator. The function returns an array of structures that contain configuration data for individual connections.

Experimental support for configuration via an XML file is available when using Connext DDS Professional. This capability is not enabled when building for Connext DDS Micro targets.

In the future, it is possible that Data Modeling tools could generate this plugin. Such tools would have the information needed for the modifying the source file produced by rtiddsgen and so could avoid having to hand-edit the source file.

The configuration function and structures are defined in include/config/ext_config.h.

During the call to FACE_TS_Initialize(), the configuration function RTI_TSS_ConfigData_get_config_data() will be called IF:

  • The library is compiled with the flag RTI_TSS_STATIC_CONFIG_FUNCTION (which is enabled by default).
  • The name of the configuration file passed into the FACE_TS_Initialize() call is a string with the form “RTI_TSS_STATIC_INITIALIZATION##foo”, where the token “RTI_TSS_STATIC_INITIALIZATION” indicates that configuration will be sourced from a function, and “foo” is a string that will be passed to the configuration function.

The RTI_TSS_ConfigData_get_config_data() implementation must return a structure of type RTI_TSS_ExternalConfigData which provides the following information:

  • An array of individual connection configuration elements, one per possible connection.
  • The length of the above array.
  • A string “url profile”, which can be used to specify QoS XML files that should be loaded by the Connext DDS core. The string is passed “as is” to the DomainParticipantFactory. NOTE: This functionality is only available when building for targets using Connext DDS Professional.
  • The logging verbosity for the Connext TSS library. Note this logging verbosity is NOT used to configure the Connext DDS verbosity.

The individual connection configuration elements are structures of type RTI_TSS_ExternalConfigDataElement. The structure provides the following information:

  • The DDS domain used by the connection.
  • The name of the connection associated with the configuration element.
  • The direction for the connection. Connection options are SOURCE, DESTINATION, or BI_DIRECTIONAL.
  • A QoS plugin to be used by the connection. The QoS plugin allows for customization of QoS policies (see next section).
  • The topic name for the connection.
  • The type name for the connection. This type name will be passed to the RTI_TSS_get_type_support() function described in the previous section.

The data contained in the configuration elements will be copied by the Connext TSS library and stored internally. The configuration data will be used when the FACE UoP creates a connection.

A note about DomainParticipants and Topics:

  • Connext TSS will only create a single DomainParticipant for each unique domain. If more than one connection uses the same domain, the DomainParticipant will be reused. A shared DomainParticipant will not be deleted until the last connection using the DomainParticipant is deleted.
  • Similarly, Connext TSS will create a single Topic for each unique domain. Much like the DomainParticipant, the Topic will be reused if more than one connection uses the same topic (in the same domain). A shared Topic will not be deleted until the last connection using the Topic is deleted (as a side effect of destroying the connection).

6.2.3. QoS Support

A QoS plugin can be passed as one of the fields within the individual connection configuration structure (RTI_TSS_ExternalConfigDataElement). The QoS plugin structure, of type RTI_TSS_QoSConfigPlugin, is defined in the file include/qos_support/qos_plugin.h.

The plugin file is initially generated by the rtiddsgen provided with Connext TSS (e.g., HelloGoodbye_QosSupport.c). Although this is sufficient for an example to work, it would likely need modification by the FACE UoP developer or the TSS integrator. The file contains implementations of configuration functions for the QoS of each DDS Entity. This source code can be hand edited to set the desired QoS for a given application.

In the future, it is possible that Data Modeling tools could generate this plugin. Such tools would have the information needed for the modifying the source file produced by rtiddsgen and so could avoid having to hand-edit the source file.

QoS plugins can be shared by separate connection configuration elements. The plugin contains:

  • Pointers to functions that configure QoS policies for individual DDS entities.
  • Names of a QoS library and profile that should be loaded from a QoS XML file. NOTE: This is only applicable to targets using Connext DDS Professional.
  • A generic pointer for plugin implementers to keep a pointer to data that may be needed by the configuration functions.

Each field is optional (the value should be NULL if not specified). If all fields are NULL, or if the plugin field of the configuration structure is itself NULL, then the “default” QoS will be used for all entities created for that connection.

If the plugin is not NULL, then the plugin will be referenced each time a DDS entity is to be created. The QoS information from the plugin is used in the following order:

  1. The default QoS is loaded.
  2. If the library/profile is not NULL, the profile is loaded. NOTE: this is only applicable to targets using Connext DDS Professional.
  3. If the configuration function is not NULL, then the configuration function is invoked. The QoS container from step (2) is passed to the configuration function; any additional modifications should be made directly to the provided QoS container.
  4. The QoS is used to create the DDS entity.

For example, the following logic is for creating DDS DataWriters:

  • A structure of type struct DDS_DataWriterQos is declared and initialized.
  • The DDSPublisher is used to retrieve the default QoS for a DataWriter. The default QoS is stored in the structure declared in step (1).
  • If the target uses Connext DDS Professional, the DDSDomainParticipantFactory is used to retrieve the library/profile specified in the plugin. The profile is loaded into the structure declared in step (1).
  • The QoS plugin function configure_datawriter_qos_fnc() is invoked, with a pointer to the structure declared in step (1). Any QoS modifications should be made directly on the provided structure.
  • The structure is then used to create a new DDSDataWriter.

When used with Connext DDS Professional, most applications will simply use the library/profile but not provide implementations for any of the functions that configure individual QoS structures.

NOTE: Per the FACE TSS specification, the QoS for a connection’s entities is established at creation time for that connection and cannot be dynamically modified during communication.

NOTE: It is important to know and configure the participant QoS of the first created connection. Because only one DomainParticipant is created for each unique DDS domain, the corresponding participant QoS function of the first created connection will be applied.