7. API Reference¶

7.1. TS Interface¶

Quick links to descriptions of the FACE TS Interface functions:

FACE::TS::Initialize
FACE::TS::Create_Connection
FACE::TS::Destroy_Connection
FACE::TS::Receive_Message
FACE::TS::Send_Message
FACE::TS::Register_Callback
FACE::TS::Unregister_Callback
FACE::TS::Get_Connection_Parameters
FACE::Read_Callback::send_event

7.2. Headers¶

Including the below header files will allow you to call FACE TSS API functions that are implemented by the RTI FACE TSS library.

The FACE TSS API is defined in the header file include/FACE/TS.hpp.
The type specific part of the FACE TSS API will be defined by header files generated as part of building from your data model:
- <example>/gen/<example>.hxx
- <example>/gen/<example>_TSS.hpp
<example>/gen/<example>.hxx should either be replaced by user files from the FACE data modeling tools or be renamed <example>/gen/<example>.hpp.
Any header file prepended with “ext_*” can be included in applications or libraries that use RTI Connext TSS. The section RTI FACE TSS Required Plugins (link TBD)) contains more information on why this is relevant.

7.3. Initialization¶

7.3.1. FACE::TS::Initialize()¶

Before using any other features of Connext TSS, the TSS must first be initialized using the FACE::TS::Initialize() API call.

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

Table 7.1 FACE::TS::Initialize Parameters¶
Parameter Name	Type	Direction	Description
configuration	const FACE::CONFIGURATION_RESOURCE	IN	The name of the configuration to load. This can either be a filename or a static configuration identifier string. NOTE: Configuration files are only available when using Connext DDS Professional with the General Purpose Profile. Static configuration for all other profiles is enabled by specifying a configuration parameter in the following format: `RTI_TSS_STATIC_INITIALIZATION##config_name`, where `config_name` is a user-defined value passed into the configuration plugin. See the configuration section for additional details.
return_code	FACE::RETURN_CODE_TYPE&	OUT	The return code for the call to `FACE::TS:Initialize`. 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::TS::Initialize Return Codes¶
Return Code	Description
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.
FACE::NO_ERROR	The operation completed successfully.

The FACE::TS::Initialize function gets the Connext TSS singleton instance and then calls the RTI_TSS_ConfigManager_initialize function to configure the TSS.

The FACE::TS::Initialize call is non-blocking.

This function is not thread safe.

7.4. Configuration¶

Configuration can be specified in an XML file using Connext DDS Professional. When using Connext DDS Micro (and optionally when using Connext DDS Professional), the configuration is specified statically in a user-modified plugin source file. Configuration data is used to setup Distribution Capability.

The following table lists FACE TSS configuration data elements and what support (if any) is available in Connext TSS. Configuration entries that are not applicable to Connext TSS are listed as “Excluded”. For information on QoS settings used to configure certain elements, please refer to documentation for Connext DDS Professional/Micro and the QoS configuration information later in this documentation.

Table 7.3 Configuration Support¶
Configuration Type	Support
Connection Name	Supported
Connection Type	Excluded
Connection Direction	Supported
Connection Domain	Excluded
Socket Type	Excluded
Max Message Size	Excluded (message size is derived from the data type used for a connection)
Message Range	Excluded
Message Association	Excluded, Not Supported
Data Transform Required	Excluded, Not Supported
Refresh Period	Supported via QoS Settings
Reliability	Supported via QoS Settings
ReadWrite Behavior	Excluded
Queue Discipline	Excluded
Receive Flag	Excluded
Send Flag	Excluded
Source	Supported via QoS Settings
Destination	Supported via QoS Settings
Source Port	Supported via QoS Settings
Destination Port(s)	Supported via QoS Settings
Filter Specification	Excluded
Thread List	Excluded (implicitly defined for Connext DDS)
Priority (per thread)	Supported via QoS Settings
Thread Rate (per thread)	Excluded
Thread Stack Size (per thread)	Supported via QoS Settings
Scheduling Policy (per thread)	Excluded

7.4.1. RTI_TSS_ConfigData_get_config_data()¶

During the code generation process for FACE, an example configuration plugin is created. If you are running the code generator with an input IDL file named MyDataModel.idl, a configuration file named MyDataModel_Config will be generated.

The configuration plugin has a single function with the following prototype:

RTI_TSS_ExternalConfigData* RTI_TSS_ConfigData_get_config_data(const char* config_name)

Table 7.4 RTI_TSS_ConfigData_get_config_data Parameters¶
Parameter Name	Type	Direction	Description
config_name	const char*	IN	Intended to be the name of the configuration to load. The actual meaning and use of this parameter is left up to the implementer of the configuration plugin.

The following C structures are used in establishing the configuration for Connext TSS:

typedef struct RTI_TSS_ExternalConfigDataElement {
    int32_t                            domain;
    const char*                        connection_name;
    FACE_CONNECTION_DIRECTION_TYPE     direction_type;
    FACE_Boolean                       bi_dir_ignore_self;
    struct RTI_TSS_QoSConfigPlugin*    qos_plugin;
    const char*                        topic_name;
    const char*                        type_name;
} RTI_TSS_ExternalConfigDataElement;

typedef struct RTI_TSS_ExternalConfigData {
    RTI_TSS_ExternalConfigDataElement* config_elements_ptr;
    unsigned int                       length;
    const char*                        url_profile;
    LogVerbosity                       verbosity;
} RTI_TSS_ExternalConfigData;

Table 7.5 RTI_TSS_ExternalConfigDataElement¶
Field Name	Type	Description
domain	int32_t	The DDS domain that the connection will use for communication. An RTI Connext TSS Source and Destination will only be able to communicate if they are operating on the same domain. In practice, this logical separation may determine certain parameters for the underlying transport, such as the ports used for a network connection. See the OMG Specification for Data Distribution Service for Real-time Systems, v1.2 section 7.1.1.2.2 for information about how the domain applies to the conceptual model for DDS.
connection_name	const char*	The name for the connection configuration. Calls to `FACE::TS::Create_Connection` that supply a matching value for the `connection_name` field will create a connection using the configuration values specified in that entry. During initialization of RTI Connext TSS, all connection names are converted to uppercase using the ctype library’s `toupper` function on each lowercase alphabet character in the original name.
direction_type	FACE_CONNECTION_DIRECTION_TYPE	The direction type of the TSS connection. Can be `FACE::SOURCE` for a sender, `FACE::DESTINATION` for a receiver, or `FACE::BI_DIRECTIONAL` for a connection that will both send and receive messages. When using `FACE::SOURCE`, a DDS DataWriter is created for the connection. When using `FACE::DESTINATION`, a DDS DataReader is created for the connection. When using `FACE::BI_DIRECTIONAL`, both a DataWriter and a DataReader will be created.
bi_dir_ignore_self	FACE_Boolean	If the connection direction is `FACE::BI_DIRECTIONAL`, this will allow the application to ignore messages originating from the sending side of this connection. This is accomplished by using the `DDS_DomainParticipant_ignore_publication` function of the DDS API. NOTE: `DDS_DomainParticipant_ignore_publication` is not available in the API for Connext DDS Micro, so setting this field will have no effect on the connection.
qos_plugin	struct RTI_TSS_QosConfigPlugin*	A pointer to a structure that will be used to set the QoS parameters for this configuration’s side of the connection. Please see the section detailing the QoS plugin for additional information. NOTE: Each side of a connection must have QoS that is compatible with the other for communication to work.
topic_name	const char*	The DDS Topic name that will be used for the connection. Refer to the OMG Specification for Data Distribution Service for Real-time Systems, v1.2 section 7.1.2.3, for information about Topics in DDS. NOTE: The name of the DDS Topic must match on both sides of a connection for communication to work.
type_name	const char*	Connections in the RTI TSS are strongly typed. This field specifies the type name that will be used for this connection. The type support plugin provided by the application developer is responsible for ensuring that type names map to type-specific plugin code required by the underlying DDS implementation. NOTE: The type information must match on both sides of a connection for communication to work.

Table 7.6 RTI_TSS_ExternalConfigData¶
Field Name	Type	Description
config_elements_pointer	RTI_TSS_ExternalConfigDataElement*	A pointer to a table of connection configuration elements.
length	unsigned int	The number of elements in the config_elements_pointer table.
url_profile	const char*	URL for specifying XML QoS files. NOTE: This field is only used with Connext DDS Professional and is ignored when using Connext DDS Micro.
verbosity	LogVerbosity	An enumerated value indicating the verbosity of log messages from the TSS.

7.4.2. RTI_TSS_QoSConfigPlugin¶

During the code generation process for FACE, an example quality of service (QoS) plugin is created. If you are running the code generator with an input IDL file named MyDataModel.idl, a configuration file named MyDataModel_QosSupport.c will be generated. The QoS plugin allows for the implementation of functions for setting quality of service for each of the DDS entities that will be used by the TSS. It also provides a function to retrieve the structure of function pointers to the entity QoS configuration functions.

The structure to be provided by the QoS plugin is below:

typedef struct RTI_TSS_QoSConfigPlugin {
    DDS_Boolean (*configure_domain_participant_qos_fnc)(struct DDS_DomainParticipantQos*, void*);
    DDS_Boolean (*configure_publisher_qos_fnc)(struct DDS_PublisherQos*, void*);
    DDS_Boolean (*configure_subscriber_qos_fnc)(struct DDS_SubscriberQos*, void*);
    DDS_Boolean (*configure_topic_qos_fnc)(struct DDS_TopicQos*, void*);
    DDS_Boolean (*configure_datawriter_qos_fnc)(struct DDS_DataWriterQos*, void*);
    DDS_Boolean (*configure_datareader_qos_fnc)(struct DDS_DataReaderQos*, void*);
    void* plugin_data;
    const char* qos_library;
    const char* qos_profile;
} RTI_TSS_QoSConfigPlugin;

Table 7.7 RTI_TSS_QosConfigPlugin¶
Field Name	Type	Description
configure_domain_participant_qos_fnc	DDS_Boolean (fnc_ptr) (struct DDS_DomainParticipantQos, void*)	A function for configuring the QoS of a DDS Domain Participant entity. If NULL, QoS will be set to a default value set for the entity. NOTE: There is no default QoS function when building an application aligned to the FACE TSS Safety Base Profile. All QoS values for a profile should be set explicitly in the plugin.
configure_publisher_qos_fnc	DDS_Boolean (fnc_ptr) (struct DDS_PublisherQos, void*)	A function for configuring the QoS of a DDS Publisher entity. If NULL, QoS will be set to a default value set for the entity. NOTE: There is no default QoS function when building an application aligned to the FACE TSS Safety Base Profile. All QoS values for a profile should be set explicitly in the plugin.
configure_subscriber_qos_fnc	DDS_Boolean (fnc_ptr) (struct DDS_SubscriberQos, void*)	A function for configuring the QoS of a DDS Subscriber entity. If NULL, QoS will be set to a default value set for the entity. NOTE: There is no default QoS function when building an application aligned to the FACE TSS Safety Base Profile. All QoS values for a profile should be set explicitly in the plugin.
configure_topic_qos_fnc	DDS_Boolean (fnc_ptr) (struct DDS_TopicQos, void*)	A function for configuring the QoS of a DDS Topic entity. If NULL, QoS will be set to a default value set for the entity. NOTE: There is no default QoS function when building an application aligned to the FACE TSS Safety Base Profile. All QoS values for a profile should be set explicitly in the plugin.
configure_datawriter_qos_fnc	DDS_Boolean (fnc_ptr) (struct DDS_DataWriterQos, void*)	A function for configuring the QoS of a DDS DataWriter entity. If NULL, QoS will be set to a default value set for the entity. NOTE: There is no default QoS function when building an application aligned to the FACE TSS Safety Base Profile. All QoS values for a profile should be set explicitly in the plugin.
configure_datareader_qos_fnc	DDS_Boolean (fnc_ptr) (struct DDS_DataReaderQos, void*)	A function for configuring the QoS of a DDS DataReader entity. If NULL, QoS will be set to a default value set for the entity. NOTE: There is no default QoS function when building an application aligned to the FACE TSS Safety Base Profile. All QoS values for a profile should be set explicitly in the plugin.
plugin_data	void*	An opaque user-defined data field that will be passed to each of the entity QoS configuration function pointers.
qos_library	const char*	The QoS Library for built-in or XML-defined QoS that will be used to configure the entities created by any connections using this plugin. Can be NULL if external configuration will not be used. NOTE: This field is ignored for applications using Connext DDS Micro.
qos_profile	const char*	The QoS Profile for built-in or XML-defined QoS that will be used to configure the entities created by any connections using this plugin. Can be NULL if external configuration will not be used. NOTE: This field is ignored for applications using Connext DDS Micro.

The example QoS plugin source file that is created by the code generator contains a function that returns a structure of type RTI_TSS_QoSConfigPlugin*, which can then be used to initialize the qos_plugin field for a connection configuration. Multiple QoS configuration structures can be used within a single application to enable tuning of message distribution capabilities to different use-cases.

Please refer to documentation for the underlying DDS implementation (Connext DDS Professional or Micro) to learn more about the QoS configuration options available for each entity.

7.4.3. XML Configuration¶

XML Configuration is available for applications using Connext DDS Professional.

Below is an example XML configuration file:

For setting QoS via XML configuration, please refer to Connext DDS Professional documentation.

7.5. Connections¶

Application developers using Connext TSS can configure connections by populating a connection table in the configuration plugin source code or by using XML configuration (the latter being available only when targeting Connext DDS Professional).

7.5.1. FACE::TS::Create_Connection()¶

A connection is created with FACE::TS::Create_Connection.

void FACE::TS::Create_Connection (
    /* in */  const FACE::CONNECTION_NAME_TYPE   connection_name,
    /* in */  FACE::MESSAGING_PATTERN_TYPE       pattern,
    /* out */ FACE::CONNECTION_ID_TYPE           &connection_id,
    /* out */ FACE::CONNECTION_DIRECTION_TYPE    &connection_direction,
    /* out */ FACE::MESSAGE_SIZE_TYPE            &max_message_size,
    /* in */  FACE::TIMEOUT_TYPE                 timeout,
    /* out */ FACE::RETURN_CODE_TYPE             &return_code
)

Table 7.8 FACE::TS::Create_Connection Parameters¶
Parameter Name	Type	Direction	Description
connection_name	const FACE::CONNECTION_NAME_TYPE	IN	The name of the connection. This value will be converted to uppercase to search against the connections specified in the configuration table for connections.
pattern	FACE::MESSAGING_PATTERN_TYPE	IN	The pattern to use for communication. Only `FACE::PUB_SUB` is supported for Connext 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.
connection_direction	FACE::CONNECTION_DIRECTION_TYPE&	OUT	The direction of the connection that corresponds to the configuration with a matching name. This field is passed by reference and is set upon return from a successful call.
max_message_size	FACE::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.
timeout	FACE::TIMEOUT_TYPE	IN	Specifies a timeout for connection creation. NOTE: This parameter is not used by the RTI TSS.
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.9 FACE::TS::Create_Connection Return Codes¶
Return Code	Description
FACE::NOT_AVAILABLE	Connext TSS was not properly initialized prior to the call to `FACE::TS::Create_Connection`.
FACE::INVALID_MODE	The pattern parameter was not specified as `FACE::PUB_SUB`, as required by Connext TSS.
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.
FACE::NO_ERROR	The operation completed successfully.

The call to FACE::TS::Create_Connection first verifies that Connext TSS was properly initialized. It then converts the supplied connection_name parameter to uppercase to perform a case-insensitive lookup of the connection configuration associated with the name. If that succeeds and a connection has not already been created for that name, one will be created and a new connection ID will be assigned. If a connection for that name already exists, the parameters for the existing connection are returned.

When a new connection is created, the appropriate DDS entities for that connection are also created if necessary, as explained in the following table.

Table 7.10 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 of direction `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 of direction `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 of direction `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 of direction `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 FACE::TS::Create_Connection call is non-blocking.

This function is not thread safe.

7.5.2. FACE::TS::Destroy_Connection¶

void FACE::TS::Destroy_Connection (
    /* in */  FACE::CONNECTION_ID_TYPE           connection_id,
    /* out */ FACE::RETURN_CODE_TYPE             &return_code
)

Table 7.11 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 `FACE::TS::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.12 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_ERROR	The operation completed successfully.

The call to FACE::TS::Destroy_Connection first verifies that the RTI TSS was properly initialized. It then looks up the connection using the provided ID. If a matching connection is found, it is removed from the lookup table and the following checks and operations are performed:

If the direction is FACE::DESTINATION or FACE::BI_DIRECTIONAL

Destroy the DDS WaitSet associated with the connection using DDS_WaitSet_delete()

If the application was using the callback interface

Destroy any internal instances of sample data using the generated type plugin

Remove the listener associated with the DDS DataReader using DDS_DataReader_set_listener()

Destroy the DDS DataReader associated with the connection using DDS_Subscriber_delete_datareader()

Destroy the DDS Subscriber associated with the connection using DDS_DomainParticipant_delete_subscriber()

If the direction is FACE::SOURCE or FACE::BI_DIRECTIONAL

Destroy the DDS DataWriter associated with the connection using DDS_Publisher_delete_datawriter()

Destroy the DDS Publisher associated with the connection using DDS_DomainParticipant_delete_publisher()

Check to see if any entities are still referencing the DDS Topic used for this connection

If not, delete the DDS Topic using DDS_DomainParticipant_delete_topic()

Check to see if any references to the DDS DomainParticipant remain

If not, delete all entities in the DDS Participant using DDS_DomainParticipant_delete_contained_entities and then delete the participant itself using ``DDS_DomainParticipantFactory_delete_participant()

NOTE: FACE::TS::Destroy_Connection does not delete the entities and remove the references to the connection when building for the Safety Base profile. These calls require the ability to free the memory associated with DDS entities and the free() call is not available in this profile.

This function is not thread safe.

7.5.3. FACE::TS::Get_Connection_Parameters()¶

void FACE::TS::Get_Connection_Parameters (
    /* inout */ FACE::CONNECTION_NAME_TYPE            &connection_name,
    /* inout */ FACE::CONNECTION_ID_TYPE              &connection_id,
    /* out */ FACE::TRANSPORT_CONNECTION_STATUS_TYPE  &connection_status,
    /* out */ FACE::RETURN_CODE_TYPE                  &return_code
)

Table 7.13 FACE::TS::Get_Connection_Parameters Parameters¶
Parameter Name	Type	Direction	Description
connection_name	FACE::CONNECTION_NAME_TYPE&	INOUT	The name of the connection. NOTE: Not used by the RTI TSS. Use the `connection_id` field instead.
connection_id	FACE::CONNECTION_ID_TYPE&	INOUT	The ID of the connection.
connection_status	FACE::TRANSPORT_CONNECTION_STATUS_TYPE&	OUT	Connection status.
return_code	FACE::RETURN_CODE_TYPE&	OUT	The return code for the call to `FACE::TS::Get_Connection_Parameters`. 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.14 FACE::TS::Get_Connection_Parameters Return Codes¶
Return Code	Description
FACE::NOT_AVAILABLE	Connext TSS was not properly initialized prior to the call to `FACE::TS::Get_Connection_Parameters`.
FACE::INVALID_PARAM	No connection with the associated ID was found.
FACE::NO_ERROR	The operation completed successfully.

The call to FACE::TS::Get_Connection_Parameters first verifies that the RTI TSS was properly initialized. It then looks up the connection using the provided ID. If one is found, information related to the connection is returned via the connection_status reference field.

NOTE: Currently only the connection direction is populated with valid information.

This function is not thread safe.

7.6. Communication¶

7.6.1. FACE::TS::Send_Message()¶

void FACE::TS::Send_Message (
    /* in */    FACE::CONNECTION_ID_TYPE      connection_id,
    /* in */    FACE::TIMEOUT_TYPE            timeout,
    /* inout */ FACE::TRANSACTION_ID_TYPE     &transaction_id,
    /* inout */ FACE_SPECIFIED_TYPE           &message,
    /* inout */ FACE::MESSAGE_SIZE_TYPE       &message_size,
    /* out */   FACE::RETURN_CODE_TYPE        &return_code
)

Table 7.15 FACE::TS::Send_Message Parameters¶
Parameter Name	Type	Direction	Description
connection_id	FACE::CONNECTION_ID_TYPE	IN	The ID of the connection to be used for sending the message. This ID is returned via a successful call to `FACE::TS::Create_Connection`.
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, which is not currently available in Connext TSS.
message	FACE_SPECIFIED_TYPE	INOUT	The strongly typed message to be sent. An implementer will substitute their type for `FACE_SPECIFIED_TYPE`. NOTE: The type of the message must correspond to the type specified in the connection configuration for the given `connection_id`.
message_size	FACE::MESSAGE_SIZE_TYPE&	INOUT	The size of the message being sent. NOTE: Since this parameter is used for abstract sends (e.g., `void` type) and this implementation only supports strongly typed communication, this parameter is not used by Connext TSS*.
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.16 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::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::INVALID_CONFIG	The DDS DataWriter associated with the `connection_id` parameter was not initialized successfully or does not match the type associated with the FACE Connection configuration.
FACE::NO_ERROR	The operation completed successfully.

The Send_Message API first checks to ensure that the TSS has been properly initialized with a call to FACE::TS::Initialize. It then verifies that the Connection corresponding to the provided connection_id parameter was previously created and that the Connection can be used to send data by confirming that the direction_type is either FACE::SOURCE or FACE::BI_DIRECTIONAL.

The FACE Connection is mapped to a DDS Topic and a type-specific DDS DataWriter. The RTI TSS obtains the type specific DataWriter and calls the write() API.

This function is not thread safe.

7.6.2. FACE::TS::Receive_Message()¶

void FACE::TS::Receive_Message (
    /* in */    FACE::CONNECTION_ID_TYPE      connection_id,
    /* in */    FACE::TIMEOUT_TYPE            timeout,
    /* inout */ FACE::TRANSACTION_ID_TYPE     &transaction_id,
    /* inout */ FACE_SPECIFIED_TYPE           &message,
    /* in */    FACE::MESSAGE_SIZE_TYPE       message_size,
    /* out */   FACE::RETURN_CODE_TYPE        &return_code
)

Table 7.17 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 amount of time 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	FACE_SPECIFIED_TYPE	INOUT	The strongly typed message to be received. An implementer will substitute their type for `FACE_SPECIFIED_TYPE`. NOTE: The type of the message must correspond to the type specified in the connection configuration for the given `connection_id`.
message_size	FACE::MESSAGE_SIZE_TYPE&	INOUT	The size of the message to be received. NOTE: Since this parameter is used for abstract receives (e.g., `void` type) and this implementation only supports strongly typed communication, this parameter is not used 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.

Table 7.18 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::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::INVALID_CONFIG	The DDS Participant, DDS WaitSet, or DDS DataReader associated with the `connection_id` parameter was not initialized successfully or the DDS DataReader does not match the type associated with the FACE Connection configuration.
FACE::TIMED_OUT	The call to `FACE::TS::Receive_Message` timed out before any data was received on the connection.
FACE::NO_ERROR	The operation completed successfully.

The Receive_Message API verifies the following before performing the operations to receive data:

The TSS has been properly initialized with a call to FACE::TS::Initialize.

The Connection corresponding to the provided connection_id parameter was previously created.

The timeout parameter is valid.

The DDS Participant associated with the connection_id parameter is valid.

The DDS WaitSet associated with the connection_id parameter is valid.

The Connection can be used to receive data by confirming the direction_type is either FACE::DESTINATION or FACE::BI_DIRECTIONAL.

The type-specific DDS DataReader associated with the connection_id is valid and the type matches the type associated with the Receive_Message call.

It then performs a DDS take_next_sample() call to attempt retrieval of a sample already at the DataReader. If a sample is available, it is returned via the message reference parameter. Otherwise the DDS wait() call is performed on the DDS WaitSet associated with the connection with the provided timeout parameter. If a sample is received within the timeout period, it is retrieved using the take_next_sample() call for the DataReader and returned via the message reference parameter.

This function is not thread safe.

7.7. Callback Interface¶

The FACE TSS callback interface is only available when using the General Purpose or Safety Extended FACE Profiles. It allows for asynchronous communication patterns.

7.7.1. FACE::Read_Callback::send_event()¶

The optional FACE TSS callback interface for receiving data specifies the following type-specific function prototype for type FACE_SPECIFIED_TYPE. It is generated from a user-defined IDL data type:

void FACE::Read_Callback::send_event(
    /* in */    FACE::TRANSACTION_ID_TYPE     transaction_id,
    /* inout */ FACE_SPECIFIED_TYPE           &message,
    /* in */    FACE::MESSAGE_TYPE_GUID       message_type_id,
    /* in */    FACE::MESSAGE_SIZE_TYPE       message_size,
    /* in */    const FACE::WAITSET_TYPE      waitset,
    /* out */   FACE::RETURN_CODE_TYPE        &return_code
);

This function is a user-defined handler for receiving data via the callback interface. The parameters passed to the function upon receipt of data are listed in the following table:

Table 7.19 FACE::Read_Callback:send_event Parameters¶
Parameter Name	Type	Direction	Description
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 `FACE_SPECIFIED_TYPE`. NOTE: The type of the message must correspond to the type specified in the connection configuration for the given `connection_id`.
message_type_id	FACE::MESSAGE_TYPE_GUID	IN	The type of the message that was received. NOTE: Since this parameter is used for abstract receives (e.g., `void` type) and this implementation only supports strongly typed communication, this parameter is not used by Connext TSS*.
message_size	FACE::MESSAGE_SIZE_TYPE	IN	The size of the message that was received. NOTE: Since this parameter is used for abstract sends (e.g., `void` type) and this implementation only supports strongly typed communication, this parameter is not used by Connext TSS*.
waitset	const FACE::WAITSET_TYPE	IN
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.7.2. FACE::TS::Register_Callback()¶

For each message type, there is a type-specific function for registering a callback with the TSS with the following signature:

void FACE::TS::Register_Callback (
    /* in */  FACE::CONNECTION_ID_TYPE        connection_id,
    /* in */  const FACE::WAITSET_TYPE        waitset,
    /* in */  FACE::Read_Callback::send_event data_callback,
    /* in */  FACE::MESSAGE_SIZE_TYPE         max_message_size,
    /* out */ FACE::RETURN_CODE_TYPE          &return_code
);

Table 7.20 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 `FACE::TS::Create_Connection`.
waitset	const FACE::WAITSET_TYPE	IN	This parameter is not used by Connext TSS.
data_callback	FACE::Read_Callback::send_event	IN	The user-defined callback function to invoke whenever data is received on the connection.
max_message_size	FACE::MESSAGE_SIZE_TYPE	IN	The size of the message that can be received. NOTE: Since this parameter is used for abstract receives (e.g., `void` type) and this implementation only supports strongly typed communication, this parameter is not used by Connext TSS*.
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.21 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 `data_callback` parameter is invalid.

The Register_Callback API verifies the following before registering the callback function with the TSS:

The TSS has been properly initialized with a call to FACE::TS::Initialize.

The Connection corresponding to the provided connection_id parameter was previously created.

The data_callback parameter and the DDS DataReader associated with the connection are not NULL.

If the callback entry does not exist for the specified connection, it is created dynamically and initialized. Once the callback entry has been successfully created, it is updated and activated with the new callback function. Internally, when a callback is registered with the FACE TSS, it is configured to be called by a DDS Listener function that is attached to the DDS DataReader associated with the connection. The event mask is modified to include ON_DATA_AVAILABLE, which will cause the DDS Listener handler for incoming data to be invoked.

When the DDS Listener is invoked, it will attempt to read available samples using the DDS type-specific function take_next_sample(). For each sample it takes, the handler will call the function specified by the data_callback parameter in the call to FACE::TSS::Register_Callback.

This function is not thread safe.

7.7.3. FACE::TS::Unregister_Callback()¶

The FACE::TS::Unregister_Callback function removes a previously registered callback from a connection.

void FACE::TS::Unregister_Callback (
    /* in */  FACE::CONNECTION_ID_TYPE        connection_id,
    /* out */ FACE::RETURN_CODE_TYPE          &return_code
);

Table 7.22 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 `FACE::TS::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.23 FACE::TS::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.

The Unregister_Callback API verifies the following before registering the callback function with the TSS:

The TSS has been properly initialized with a call to FACE::TS::Initialize.

The Connection corresponding to the provided connection_id parameter was previously created.

If a callback has been registered for the connection, it is removed by using the DDS_DataReader_set_listener() call and the associated dynamically allocated callback structure is freed.

This function is not thread safe.

7.8. 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 header is in log/ext_log.h and exposes the following macros for logging:

#define Logger_error(logger, methodName, ...)
#define Logger_warning(logger, methodName, ...)
#define Logger_info(logger, methodName, ...)

Each of these macros takes a struct Logger* as the first parameter, which can be obtained as a singleton for the application using:

struct Logger * Logger_getInstance();

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

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

The logging output behavior is configured at the time of the Connext TSS build. Support is available for writing to STDOUT, a user-defined file, or a timestamp-named file. Logging can also be disabled. All log writing is done using the POSIX write() API. The logger is not thread safe.