7. API Reference

Note

This API Reference for RTI Connext TSS contains examples and is easier for a beginner to use. However, Connext TSS also comes bundled with a separate TSS API Reference with only the functions and parameters defined. Both API References are complete and up-to-date.

7.1. TSS Type-Specific Base and Typed Interfaces

Connext TSS implements the FACE TSS Type-Specific Base and Typed interfaces in the C++ programming language as the RTI::TSS::Base class.

RTI::TSS::Base also implements the FACE Configuration Injectable interface for Connext TSS configuration.

For applications requiring all resources to be allocated and configured during an intialization phase, an extended function pf RTI::TSS::Base, Enable_DDS_Entities(), allows Connext TSS users first to create disabled DDS entities during initialization and then to enable them after initialization.

7.2. Headers

Include these header files to allow your application to call the FACE TSS APIs implemented by the RTI FACE TSS library.

  • RTI/TSS/Base.hpp defines the Connext TSS implementation of the FACE TSS Type-Specific Base interface.

  • Given a user datatype, once the RTI FACE TSS library has been built and the rtiddsgen tool has been run, the generated header file <modules>/<user_datatype_name>/TypedTS.hpp defines the FACE TSS Type-Specific Typed interface for the user datatype, and the generated header file <modules>/<user_datatype_name>/TypedTS_Impl.hpp defines the implementation of that interface.

For a reference on including headers, see the example application(s) in the examples directory.

7.3. Initialization

7.3.1. Set_Reference()

A new Base instance must set its reference to a Configuration Interface before the Base is initialized.

void Set_Reference (
    /* in */  const FACE::STRING_TYPE &interface_name,
    /* in */  FACE::Configuration **interface_reference,
    /* out */ const FACE::GUID_TYPE id,
    /* out */ FACE::RETURN_CODE_TYPE::Value &return_code);
)
Table 7.1 FACE::Configuration_Injectable::Set_Reference Parameters

Parameter Name

Type

Direction

Description

interface_name

const FACE::STRING_TYPE

IN

Unused by Connext TSS

interface_reference

const FACE::Configuration

IN

A reference to an FACE Configuration instance for Connext TSS.

id

const FACE::GUID_TYPE

OUT

Unused by Connext TSS

return_code

FACE::RETURN_CODE_TYPE

OUT

The return code for the call to Set_Reference(Base). Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure.

Table 7.2 FACE::Configuration_Injectable::Set_Reference Return Codes

Return Code

Description

FACE::NO_ERROR

The operation completed successfully.

FACE::NO_ACTION

A configuration reference was previously set successfully.

The Set_Reference function sets the FACE Configuration instance that a Base instance will use to configure the TSS connections it will create, as well as the underlying DDS.

The interface_reference must be a configured instance of RTI::Configuration implementing the FACE 3.x Configuration interface. For help in creating and setting the configuration data in the configuration interface, see Configuration Interface.

The Set_Reference function is non-blocking.

This function is not thread safe.

7.3.2. Initialize()

Once the Configuration interface reference is set, the TSS is initialized by calling the Base interface Initialize(TS) function.

void Initialize (
    /* in */  const FACE::CONFIGURATION_RESOURCE &configuration,
    /* out */ FACE::RETURN_CODE_TYPE::Value &return_code
)
Table 7.3 FACE::TS::Initialize Parameters

Parameter Name

Type

Direction

Description

configuration

const FACE::CONFIGURATION_RESOURCE

IN

The name of the configuration to load. Passed to the Configuration Interface’s Initialize() member function.

NOTE: Configuration files are only available when using Connext DDS Professional with the General Purpose Profile.

return_code

FACE::RETURN_CODE_TYPE&

OUT

The return code for the call to Initialize(TS). Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure.

Table 7.4 FACE::TS::Initialize Return Codes

Return Code

Description

FACE::NO_ERROR

The operation completed successfully.

FACE::NO_ACTION

Connext TSS was successfully initialized previously.

FACE::NOT_AVAILABLE

Connext TSS internal data could not be properly initialized.

FACE::INVALID_CONFIG

Connext TSS could not be configured with the provided configuration parameter.

The Initialize(TS) function will initialize Connext TSS and its supporting DDS with configuration data from its set configuration interface. It will load the system configuration the first time it is called, idempotently.

The Initialize(TS) function is non-blocking.

This function is not thread safe.

7.4. Connections

7.4.1. Create_Connection()

A connection is created with the RTI::TSS::Base Create_Connection function.

void Create_Connection(
    const FACE::TSS::CONNECTION_NAME_TYPE &connection_name,
    const FACE::TIMEOUT_TYPE timeout,
    FACE::TSS::CONNECTION_ID_TYPE &connection_id,
    FACE::TSS::MESSAGE_SIZE_TYPE &max_message_size,
    FACE::RETURN_CODE_TYPE::Value &return_code
)
Table 7.5 FACE::TSS::Create_Connection Parameters

Parameter Name

Type

Direction

Description

connection_name

const FACE::TSS::CONNECTION_NAME_TYPE

IN

The name of the connection to create. Must match the name (case-insensitive) of a connection in configuration data.

timeout

FACE::TIMEOUT_TYPE

IN

Specifies a timeout for connection creation.

NOTE: This parameter is not used by the RTI TSS.

connection_id

FACE::CONNECTION_ID_TYPE

OUT

A unique connection ID. This ID will be used to refer to the connection in all other TSS API calls. This field is passed by reference and is set upon return from a successful call.

max_message_size

FACE::TSS::MESSAGE_SIZE_TYPE

OUT

The maximum size of a message for this connection. This field is passed by reference and is set upon return from a successful call.

NOTE: This parameter is not supported by RTI TSS and consequently is set to 0.

return_code

FACE::RETURN_CODE_TYPE

OUT

The return code for the call to FACE::TS::Create_Connection. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure.

Table 7.6 FACE::TS::Create_Connection Return Codes

Return Code

Description

FACE::NO_ERROR

The operation completed successfully.

FACE::NOT_AVAILABLE

Connext TSS was not properly initialized prior to the call to FACE::TS::Create_Connection.

FACE::INVALID_PARAM

A configuration with a name matching the provided connection_name parameter was not found.

NOTE: Because both strings will have been converted to uppercase prior to the matching process, the matching is case-insensitive, as required by the FACE TSS specification.

FACE::INVALID_CONFIG

Connext TSS was unable to create the connection due to an invalid configuration.

A successfully created connection will have had DDS entities asserted or created in the following manner:

Table 7.7 DDS Entity Creation

DDS Entity

Creation Requirements

DomainParticipant

Created if there is no existing DomainParticipant for the new connection’s configured domain parameter. Otherwise the existing DomainParticipant on that domain will be reused by the new connection. See the OMG Specification for Data Distribution Service for Real-time Systems, v1.2 section 7.1.2.2.1, for information on the DomainParticipant entity class.

NOTE: DomainParticipant reuse does not allow for new connections to modify DomainParticipant QoS after the initial creation of the DomainParticipant. Any connection created with the same domain as an existing connection will use the DomainParticipant QoS of the original connection, regardless of the QoS plugin specified for the new connection.

Topic

Created if there is no existing Topic matching the new connection’s topic name in the connection configuration. Otherwise the existing Topic will be reused by the new connection. See the OMG Specification for Data Distribution Service for Real-time Systems, v1.2 section 7.1.2.3.2, for information on the Topic entity class.

NOTE: Topic reuse does not allow for connections to modify Topic QoS after the initial creation of the Topic. Any connection created with the same topic name as an existing connection will use the Topic QoS of the original connection, regardless of the QoS plugin specified for the new connection.

Publisher

Created if the connection is configured as FACE::SOURCE or FACE::BI_DIRECTIONAL. See the OMG Specification for Data Distribution Service for Real-time Systems, v1.2 section 7.1.2.4.1, for information on the Publisher entity class.

NOTE: Although DDS allows for Publishers to contain multiple DataWriters, in Connext TSS Publishers are not shared by connections.

Subscriber

Created if the connection is configured as FACE::DESTINATION or FACE::BI_DIRECTIONAL. See the OMG Specification for Data Distribution Service for Real-time Systems, v1.2 section 7.1.2.5.2, for information on the Subscriber entity class.

NOTE: Although DDS allows for Subscribers to contain multiple DataReaders, in Connext TSS Subscribers are not shared by connections.

DataWriter

Created if the connection is configured as FACE::SOURCE or FACE::BI_DIRECTIONAL. See the OMG Specification for Data Distribution Service for Real-time Systems, v1.2 section 7.1.2.4.2, for information on the DataWriter entity class.

DataReader

Created if the connection is configured as FACE::DESTINATION or FACE::BI_DIRECTIONAL. See the OMG Specification for Data Distribution Service for Real-time Systems, v1.2 section 7.1.2.5.3, for information on the DataReader entity class.

The Create_Connection function is non-blocking.

This function is not thread safe for Connext DDS Pro and Connext Micro.

7.4.2. Destroy_Connection

void Destroy_Connection(
    const FACE::TSS::CONNECTION_ID_TYPE connection_id,
    FACE::RETURN_CODE_TYPE::Value &return_code
)
Table 7.8 FACE::TS::Destroy_Connection Parameters

Parameter Name

Type

Direction

Description

connection_id

FACE::CONNECTION_ID_TYPE

IN

The ID of the connection to be destroyed.

return_code

FACE::RETURN_CODE_TYPE

OUT

The return code for the call to Destroy_Connection(). Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure.

Table 7.9 FACE::TS::Destroy_Connection Return Codes

Return Code

Description

FACE::NOT_AVAILABLE

Connext TSS was not properly initialized prior to the call to FACE::TS::Destroy_Connection.

FACE::NO_ACTION

The connection was already destroyed

FACE::INVALID_PARAM

The connection does not exist.

FACE::NO_ERROR

The operation completed successfully.

Note

NOTE: Connext TSS built with Connext DDS Micro for Safety Base or Security OSS profiles does not reclaim any Connext TSS connection or DDS resources.

This function is not thread safe for Connext DDS Pro and is thread safe for Connext Micro.

7.4.3. Enable_DDS_Entities()

The DDS entities underlying Connext TSS connections can have their QoS configured such that they are disabled upon connection creation, with resources allocated but no processes running or discovery messages sent. This would be necessary for platforms with explicit intialization phases (e.g. ARINC 653).

Consequently, after all connections have been created and the platform is done with intialization, the first call after initialization must be to this function, so that DDS processes can run and DDS discovery can be done.

void Enable_DDS_Entities (
    /* out */ FACE::RETURN_CODE_TYPE::Value &return_code);
)
Table 7.10 RTI::TSS::Base::Enable_DDS_Entities Parameters

Parameter Name

Type

Direction

Description

return_code

FACE::RETURN_CODE_TYPE

OUT

The return code for the call to Enable_DDS_Entities(). Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure.

Table 7.11 RTI::TSS::Base::Enable_DDS_Entities Return Codes

Return Code

Description

FACE::NO_ERROR

The operation completed successfully.

FACE::NOT_AVAILABLE

Connext TSS was not initialized before this operation, or the operation failed to enable DDS entities.

This function is non-blocking.

This function is not thread safe for Connext DDS Pro. It is thread safe for Connext DDS Micro.

7.5. Communication

For each user defined type, Connext TSS rtiddsegn generates a class implementing the Typed-Specific Typed Inteface. Its functions are responsible for sending and receiving the typed messages.

7.5.1. Send_Message()

void Send_Message(
  FACE::TSS::CONNECTION_ID_TYPE connection_id,
  FACE::TIMEOUT_TYPE timeout,
  FACE::TSS::TRANSACTION_ID_TYPE& transaction_id,
  DATATYPE_TYPE& message,
  FACE::RETURN_CODE_TYPE::Value& return_code
)
Table 7.12 FACE::TS::Send_Message Parameters

Parameter Name

Type

Direction

Description

connection_id

FACE::CONNECTION_ID_TYPE

IN

The ID of a created connection to use to send the message.

timeout

FACE::TIMEOUT_TYPE

IN

The timeout parameter is not used by Connext TSS.

transaction_id

FACE::TRANSACTION_ID_TYPE

INOUT

The transaction_id parameter is used in the request/reply communication pattern. It is not used or set by Connext TSS.

message

DATATYPE_TYPE

INOUT

The typed message to be sent.

NOTE: The type of the message must correspond to the type specified in the connection configuration for the given connection_id.

return_code

FACE::RETURN_CODE_TYPE

OUT

The return code for the call to FACE::TS::Send_Message. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure.

Table 7.13 FACE::TS::Send_Message Return Codes

Return Code

Description

FACE::NOT_AVAILABLE

Connext TSS was not properly initialized prior to the call to FACE::TS::Send_Message.

FACE::INVALID_PARAM

The provided connection_id parameter does not correspond to an active connection or the DDS DataWriter’s write call returned an error.

FACE::CONNECTION_CLOSED

The provided connection_id existed at some point but its associated connection was already destroyed.

FACE::INVALID_MODE

The connection associated with the connection_id is of direction FACE::DESTINATION. FACE::TS::Send_Message only works with connections using direction FACE::SOURCE or FACE::BI_DIRECTIONAL.

FACE::NO_ACTION

The underliying DDS-level API returned an error.

FACE::NO_ERROR

The operation completed successfully.

Upon a successful call, the DDS DataWriter corresponding to the connection with the matching connection ID will have written one message.

This function is not thread safe.

7.5.2. Receive_Message()

void Receive_Message(
  FACE::TSS::CONNECTION_ID_TYPE connection_id,
  FACE::TIMEOUT_TYPE timeout,
  FACE::TSS::TRANSACTION_ID_TYPE& transaction_id,
  DATATYPE_TYPE& message,
  FACE::TSS::HEADER_TYPE& header,
  FACE::TSS::QoS_EVENT_TYPE& qos_parameters,
  FACE::RETURN_CODE_TYPE::Value& return_code
)
Table 7.14 FACE::TS::Receive_Message Parameters

Parameter Name

Type

Direction

Description

connection_id

FACE::CONNECTION_ID_TYPE

IN

The ID of the connection to be used for receiving the message. This ID is returned via a successful call to FACE::TS::Create_Connection.

timeout

FACE::TIMEOUT_TYPE

IN

The duration to wait for an incoming message before returning to the calling application with a return code indicating the call has timed out.

transaction_id

FACE::TRANSACTION_ID_TYPE

INOUT

The transaction_id parameter is used in the request/reply communication pattern, which is not currently available in Connext TSS.

message

DATATYPE_TYPE

INOUT

The strongly typed message to be received. An implementer will substitute their type for DATATYPE_TYPE.

NOTE: The type of the message must correspond to the type specified in the connection configuration for the given connection_id.

header

FACE::TSS::HEADER_TYPE

OUT

The header parameter is not currently set or supported by Connext TSS.

qos_parameters

FACE::TSS::QoS_EVENT_TYPE

OUT

The qos_parameters parameter is not currently set or supported by Connext TSS.

return_code

FACE::RETURN_CODE_TYPE

OUT

The return code for the call to Receive_Message. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure.

Table 7.15 FACE::TS::Receive_Message Return Codes

Return Code

Description

FACE::NOT_AVAILABLE

Connext TSS was not properly initialized prior to the call to FACE::TS::Receive_Message or no data was received.

FACE::INVALID_PARAM

The provided connection_id parameter does not correspond to an active connection or the timeout value is invalid.

FACE::CONNECTION_CLOSED

The provided connection_id existed at some point but its associated connection was already destroyed.

FACE::INVALID_MODE

The connection associated with the connection_id is of direction FACE::SOURCE. FACE::TS::Receive_Message only works with connections using direction FACE::DESTINATION or FACE::BI_DIRECTIONAL.

FACE::TIMED_OUT

The call to FACE::TS::Receive_Message timed out before any data was received on the connection.

FACE::MESSAGE_STALE

The instance was disposed.

FACE::NO_ACTION

The underliying DDS-level API returned an error.

FACE::NO_ERROR

The operation completed successfully.

Users will poll with this function for received data.

Upon a successful call, the DDS DataReader corresponding to the connection with the matching connection ID will have received and taken one message.

This function is not thread safe.

7.6. Callback Interface

The FACE TSS callback interface allows for messages to be received without polling.

7.6.1. Register_Callback()

The TypedTS instance supports the Register_Callback function to receive data without polling. Each received message will invoke the registered callback.

void Register_Callback(
  FACE::TSS::CONNECTION_ID_TYPE   connection_id,
  Read_Callback&   callback,
  FACE::RETURN_CODE_TYPE::Value&  return_code
)
Table 7.16 FACE::TS:Register_Callback Parameters

Parameter Name

Type

Direction

Description

connection_id

FACE::CONNECTION_ID_TYPE

IN

The ID of the connection on which the messages shall be received. This ID is returned via a successful call to Create_Connection.

callback

DATATYPE_TYPE::Read_Callback

IN

The user-defined callback function to invoke whenever data is received on the connection.

return_code

FACE::RETURN_CODE_TYPE

OUT

The return code for the call to FACE::TS::Register_Callback. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure.

Table 7.17 FACE::TS::Register_Callback Return Codes

Return Code

Description

FACE::NOT_AVAILABLE

Connext TSS was not properly initialized prior to the call to FACE::TS::Receive_Message or no data was received.

FACE::INVALID_PARAM

The provided connection_id parameter does not correspond to an active connection or the callback parameter is invalid.

FACE::CONNECTION_CLOSED

The provided connection_id existed at some point but its associated connection was already destroyed.

FACE::NO_ACTION

There is a callback already registered.

FACE::NO_ERROR

The callback was successfully registered.

The registered callback is invoked in the context of the DDS DataReader’s receive thread.

Only one callback can be registered per connection.

This function is not thread safe.

7.6.2. Read_Callback::Callback_Handler

This function is a user defined handler for receiving data via callback instead of polling.

void Callback_Handler(
  FACE::TSS::CONNECTION_ID_TYPE connection_id,
  FACE::TSS::TRANSACTION_ID_TYPE transaction_id,
  const DATATYPE_TYPE& message,
  const FACE::TSS::HEADER_TYPE& header,
  const FACE::TSS::QoS_EVENT_TYPE& qos_parameters,
  FACE::RETURN_CODE_TYPE::Value& return_code
)
Table 7.18 FACE::Read_Callback:Callback_Handler Parameters

Parameter Name

Type

Direction

Description

connection_id

FACE::CONNECTION_ID_TYPE

IN

The ID of the connection on which the message was received.

transaction_id

FACE::TRANSACTION_ID_TYPE

IN

The transaction_id parameter is used in the request/reply communication pattern, which is not currently available in Connext TSS.

message

FACE_SPECIFIED_TYPE

INOUT

The strongly typed message that was received. An implementer will substitute their type for DATATYPE_TYPE.

NOTE: The type of the message must correspond to the type specified in the connection configuration for the given connection_id.

header

FACE::TSS::HEADER_TYPE

OUT

The header parameter is not currently set or supported by Connext TSS.

qos_parameters

FACE::TSS::QoS_EVENT_TYPE

OUT

The qos_parameters parameter is not currently set or supported by Connext TSS.

return_code

FACE::RETURN_CODE_TYPE

OUT

The return code for the call to FACE::TS::Receive_Message. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure.

7.6.3. FACE::TSS::BASE::Unregister_Callback()

This function removes a registered callback from a connection.

void Unregister_Callback(
  const FACE::TSS::CONNECTION_ID_TYPE connection_id,
  FACE::RETURN_CODE_TYPE::Value   &return_code
)
Table 7.19 FACE::TS:Unregister_Callback Parameters

Parameter Name

Type

Direction

Description

connection_id

FACE::CONNECTION_ID_TYPE

IN

The ID of the connection with the callback that will be unregistered.

return_code

FACE::RETURN_CODE_TYPE

OUT

The return code for the call to Unregister_Callback. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure.

Table 7.20 FACE::TSS::BASE::Unregister_Callback Return Codes

Return Code

Description

FACE::NOT_AVAILABLE

The RTI TSS was not properly initialized prior to the call to FACE::TS::Receive_Message or no data was received.

FACE::INVALID_PARAM

The call failed to unregister a callback on a connection with the provided ID. This could be the result of an invalid ID or that no callback was associated with the connection.

FACE::INVALID_PARAM

The provided connection_id parameter does not correspond to an active connection or the data_callback parameter is invalid.

This function is not thread safe.

7.7. Logging

Connext TSS provides a logging mechanism that can be used by applications using Connext TSS headers and linking against the Connext TSS libraries.

The logging output behavior is configured at the time of the Connext TSS build. It is configured by the RTI_LOG_VERBOSITY and RTI_TSS_LOG_FILE_TYPE CMake variable, and are set to warning and stdout by default. The following logging options are available:

Table 7.21 FACE TSS Logging File Type Options

Option

Description

none

Disables logging.

stdout

Enables logging to the operating system STDOUT file descriptor. This is the default behavior if RTI_TSS_LOG_FILE_TYPE is not defined.

file

Enables logging to a named file. The file name is defined with the LOG_FILE_NAME variable. If LOG_FILE_NAME is not defined, it is set to rtifacetss.log by default.

timestamp

Enables logging to a file named with a timestamp created at application startup. This filename is formatted as rtifacetss_<YYYYMMDD>_<hhmmss>.log.

Table 7.22 FACE TSS Logging Verbosity Options

Option

Description

Silent

Disables logging.

Error

Enables logging for error messages

Warning

Enables logging for error and warning messages. This is the default behavior if RTI_TSS_LOG_FILE_TYPE is not defined.

Info

Enables logging for error, warning, and info messages.

Debug

Enables logging for error, warning, info, and debug messages.

All log writing is done using the POSIX write() API.

The logging header is in log/ext_log.h and exposes the following macros for logging:

#define Logger_error(methodName, message_, ...)
#define Logger_warning(methodName, message_, ...)
#define Logger_info(methodName, message_, ...)
#define Logger_debug(methodName, message_, ...)

Messages can be logged using the macros which offer usage similar to an fprintf() call:

Logger_error(THIS_METHOD_NAME, "Unable to register callback for connection id (%llu)", connection_id);

Notes:

  • The logger is not thread safe.

  • The logger is not available (compiled out, not part of the build) for FACE OS profiles Safety Base or stricter.