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.

Set_Reference (Configuration)
Initialize (Base TS) Function
Create_Connection (Base TS) Function
Enable_DDS_Entities (RTI)
Destroy_Connection (Base TS) Function
Send_Message (Typed TS)
Receive_Message (Typed TS) Function
Register_Callback (Typed TS)
Callback_Handler (Typed TS) Function
Unregister_Callback (Base TS) Function

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.