7. API Reference

Note

The complete RTI Connext TSS C API Documentation and RTI Connext TSS C++ API Documentation are included separately in your Connext TSS bundle. However, this API Reference for Connext TSS contains examples and is easier to use for a beginner.

Note

This API section refers only to C++. For the C API, replace all instances of :: with _ and add the FACE object as the first argument.

7.1. Typed TS Interfaces

Connext TSS implements the FACE TSS Type-Specific interfaces in the C++ programming language.

The RTI::TSS::Base class 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 of RTI::TSS::Base, Enable_Runtime(), allows Connext TSS users first to create disabled DDS Entities during initialization and then to enable them after initialization.

• Send_Message (Typed TS)

• Receive_Message (Typed TS) Function

• Register_Callback (Typed TS)

• Callback_Handler (Typed TS) Function

• Unregister_Callback (Typed TS) Function

7.1.1. Headers

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

• 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 in the <RTITSSHOME>\examples directory.

7.1.2. Communication

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

7.1.2.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.1 FACE::TS::Send_Message Parameters

Parameter Name	Type	Direction	Description
connection_id	FACE::TSS::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.2 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.
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 TPMs 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 [2].

7.1.2.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.3 FACE::TS::Receive_Message Parameters

Parameter Name	Type	Direction	Description
connection_id	FACE::TSS::CONNECTION_ID_TYPE	IN	The ID of the connection to be used for receiving the message.
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.4 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 TPMs returned an error.
FACE::NO_ERROR	The operation completed successfully.

Users will poll with this function for received data.

This function is not thread safe [2].

7.1.3. Callback Interface

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

7.1.3.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.5 FACE::TS::Register_Callback Parameters

Parameter Name	Type	Direction	Description
connection_id	FACE::TSS::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.6 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.

Only one callback can be registered per connection.

This function is not thread safe [1].

7.1.3.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.7 FACE::Read_Callback:Callback_Handler Parameters

Parameter Name	Type	Direction	Description
connection_id	FACE::TSS::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.1.3.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.8 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.9 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 [1].

7.2. TSS TA Base

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

RTI::TSS::Base also implements the FACE Configuration Injectable, TPM_Injectable, and the Logging_Injectable interfaces for Connext TSS configuration.

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

• Set_Reference (Configuration)

• Set_Reference (TPM)

• Set_Reference (Logging)

• Initialize (Base TS) Function

• Create_Connection (Base TS) Function

• Destroy_Connection (Base TS) Function

• Enable_Runtime (RTI)

• Send_Message (Base TS)

• Receive_Message (Base TS) Function

• Register_Callback (Base TS)

• Callback_Handler (Base TS) Function

• Unregister_Callback (Base TS) Function

7.2.1. Headers

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

• code/C++/include/FACE/TSS/RTI/Base_impl.hpp defines the Connext TSS implementation of the FACE TSS Type-Specific Base interface.

For a reference on including headers, see the example application in the <RTITSSHOME>\examples directory.

7.2.2. Initialization

7.2.2.1. Set_Reference() Configuration

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.10 FACE::Configuration_Injectable::Set_Reference Parameters

Parameter Name	Type	Direction	Description
interface_name	FACE::STRING_TYPE	IN	Unused by Connext TSS.
interface_reference	FACE::Configuration	IN	A reference to a FACE Configuration instance for Connext TSS.
id	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.11 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.

The interface_reference must be a configured instance of FACE::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 [1].

7.2.2.2. Set_Reference() TPM

If Logging is to be enabled, a new Base instance must set its reference to a Logging Interface before the Base is initialized.

void Set_Reference (
    /* in */  const FACE::STRING_TYPE &interface_name,
    /* in */  FACE::TSS::TPM::TPMTS **interface_reference,
    /* out */ const FACE::GUID_TYPE id,
    /* out */ FACE::RETURN_CODE_TYPE::Value &return_code);
)

Table 7.12 FACE::Configuration_Injectable::Set_Reference Parameters

Parameter Name	Type	Direction	Description
interface_name	FACE::STRING_TYPE	IN	Unused by Connext TSS.
interface_reference	FACE::TSS::TPM::TPMTS	IN	A reference to a FACE TPM instance for Connext TSS.
id	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.13 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 TPM instance that a Base instance will use.

The interface_reference must be a configured instance of FACE::TSS::TPM::TPMTS implementing the FACE 3.x TPM interface.

The Set_Reference function is non-blocking.

This function is not thread safe [1].

7.2.2.3. Set_Reference() Logging

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

void Set_Reference (
    /* in */  const FACE::STRING_TYPE &interface_name,
    /* in */  FACE::Logging **interface_reference,
    /* out */ const FACE::GUID_TYPE id,
    /* out */ FACE::RETURN_CODE_TYPE::Value &return_code);
)

Table 7.14 FACE::Configuration_Injectable::Set_Reference Parameters

Parameter Name	Type	Direction	Description
interface_name	FACE::STRING_TYPE	IN	Unused by Connext TSS.
interface_reference	FACE::Logging	IN	A reference to a FACE Logging instance for Connext TSS.
id	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.15 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 Logging instance that a Base instance will use to log.

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

The Set_Reference function is non-blocking.

This function is not thread safe [1].

7.2.2.4. 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.16 FACE::Base::Initialize Parameters

Parameter Name	Type	Direction	Description
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.17 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 TPMs 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 [1].

7.2.3. Connections

7.2.3.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.18 FACE::Base::Create_Connection Parameters

Parameter Name	Type	Direction	Description
connection_name	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 Connext TSS.
connection_id	FACE::TSS::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::Base::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.19 FACE::Base::Create_Connection Return Codes

Return Code	Description
FACE::NO_ERROR	The operation completed successfully.
FACE::NOT_AVAILABLE	Base 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: String matching is case-insensitive, as required by the FACE TSS specification.
FACE::INVALID_CONFIG	Base was unable to create the connection due to an invalid configuration.

The Create_Connection function is non-blocking.

This function is not thread safe [1] for Connext Micro.

7.2.3.2. Destroy_Connection

void Destroy_Connection(
    const FACE::TSS::CONNECTION_ID_TYPE connection_id,
    FACE::RETURN_CODE_TYPE::Value &return_code
)

Table 7.20 FACE::Base::Destroy_Connection Parameters

Parameter Name	Type	Direction	Description
connection_id	FACE::TSS::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.21 FACE::TS::Destroy_Connection Return Codes

Return Code	Description
FACE::NOT_AVAILABLE	Base 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.

7.2.3.3. Enable_Runtime()

Future functionality.

7.2.4. Communication

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

7.2.4.1. Send_Message()

void Send_Message(
  FACE::TSS::CONNECTION_ID_TYPE connection_id,
  FACE::TIMEOUT_TYPE timeout,
  FACE::TSS::TRANSACTION_ID_TYPE& transaction_id,
  const FACE::TSS::MESSAGE_TYPE& message,
  FACE::TSS::MESSAGE_SIZE_TYPE& size_sent,
  FACE::RETURN_CODE_TYPE::Value& return_code
)

Table 7.22 FACE::TSS::TypeAbstraction::TypeAbstractionTS::Send_Message Parameters

Parameter Name	Type	Direction	Description
connection_id	FACE::TSS::CONNECTION_ID_TYPE	IN	The ID of a created connection to use to send the message.
timeout	FACE::TSS::TIMEOUT_TYPE	IN	The timeout parameter is not used by Connext TSS.
transaction_id	FACE::TSS::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	FACE::TSS::MESSAGE_TYPE	IN	The typed message to be sent.
size_sent	FACE::TSS::MESSAGE_SIZE_TYPE	OUT	The size sent over the wire.
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.23 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.
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 in an invalid mode.
FACE::NO_ACTION	The underliying TPMs have 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 [2].

7.2.4.2. Receive_Message()

void Receive_Message(
  FACE::TSS::CONNECTION_ID_TYPE connection_id,
  FACE::TIMEOUT_TYPE timeout,
  FACE::TSS::TRANSACTION_ID_TYPE& transaction_id,
  FACE::TSS::MESSAGE_SIZE_TYPE size_limit,
  FACE::TSS::MESSAGE_TYPE& message,
  FACE::TSS::HEADER_TYPE& header,
  FACE::TSS::QoS_EVENT_TYPE& qos_parameters,
  FACE::RETURN_CODE_TYPE::Value& return_code
)

Table 7.24 FACE::TS::Receive_Message Parameters

Parameter Name	Type	Direction	Description
connection_id	FACE::TSS::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.
size_sent	FACE::TSS::MESSAGE_SIZE_TYPE	IN	The qos_parameters parameter is not currently set or supported by Connext TSS.
message	FACE::TSS::MESSAGE_TYPE	INOUT	The typed message to be sent.
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.25 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 [2].

7.2.5. Callback Interface

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

7.2.5.1. Register_Callback()

The Type Abstraction 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,
  FACE::TSS::TypeAbstraction::Read_Callback** data_callback,
  FACE::TSS::MESSAGE_SIZE_TYPE max_message_size,
  FACE::TSS::MESSAGE_GUID_TYPE message_guid,
  FACE::RETURN_CODE_TYPE::Value& return_code
)

Table 7.26 FACE::TSS::TypeAbstractions::TypedAbtractionTS::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	FACE::TSS::TypeAbstraction::Read_Callback::Read_Callback	INOUT	The user-defined callback function to invoke whenever data is received on the connection.
max_message_size	FACE::TSS::MESSAGE_SIZE_TYPE	IN	The max_message_size parameter is not currently set or supported by Connext TSS.
message_guid	FACE::TSS::MESSAGE_GUID_TYPE	IN	The guid associated with the message DATA_TYPE.
return_code	FACE::RETURN_CODE_TYPE	OUT	The return code for the call to FACE::TSS::TypeAbstractions::TypedAbtractionTS::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.27 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 [1].

7.2.5.2. Read_Callback::Callback_Handler

This function is a user-defined handler for receiving data via callback instead of polling. Typed TS callbacks are triggered by a call from a Type Abstraction Callback Handler for a specific Type Abstraction channel that has been registered with the Type Abstraction. The Typed TS callback is implemented by the end user; triggering it calls the provided end user code. The Typed TS callback handlers must be registered via the callback registration FACE API on the Type Abstraction. The outline of a Typed TS callback is provided by the generated code.

void Callback_Handler(
  FACE::TSS::CONNECTION_ID_TYPE connection_id,
  FACE::TSS::TRANSACTION_ID_TYPE transaction_id,
  const MESSAGE_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.28 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	MESSAGE_TYPE	INOUT	The message that was received.
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.2.5.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.29 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.30 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::TSS::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 [1].

7.3. TSS TPM Interfaces

Connext TSS implements the FACE TSS TPM interfaces in the C++ programming language as the FACE::TSS::TPM::TPMTS_Impl class.

FACE::TSS::TPM::TPMTS_Impl also implements the FACE Configuration Injectable Interface for Connext TSS configuration.

• Set_Reference (Configuration)

• Set_Reference (Serialization)

• Set_Reference (Primtive Marshalling)

• Set_Reference (Logging)

• Initialize (TPM) Function

• Open_Channel (TPM) Function

• Close_Channel (TPM)

• Request_TPM_State_Change (TPM) Function

• Is_Data_Available (TPM)

• Get_TPM_Status (TPM) Function

• Write_To_Transport (TPM) Function

• Read_From_Transport (TPM) Function

• Register_Callback (TPM)

• Data_Callback_Handler (TPM) Function

• Event_Callback_Handler (TPM) Function

• Unregister_Callback (TPM) Function

7.3.1. Headers

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

• code/C++/include/RTI/TSS/RTI_TPM_DDS_Micro.hpp defines the Connext TSS implementation of the FACE TSS TPM interface.

For a reference on including headers, see the example application in the <RTITSSHOME>\examples directory.

7.3.2. Initialization

7.3.2.1. Set_Reference(Configuration)

A new TPM instance must set its reference to a Configuration Interface before the TPM 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.31 FACE::Configuration_Injectable::Set_Reference Parameters

Parameter Name	Type	Direction	Description
interface_name	FACE::STRING_TYPE	IN	Unused by Connext TSS.
interface_reference	FACE::Configuration	IN	A reference to a FACE Configuration instance for Connext TSS.
id	FACE::GUID_TYPE	OUT	Unused by Connext TSS.
return_code	FACE::RETURN_CODE_TYPE	OUT	The return code for the call to Set_Reference(TPM). 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.32 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 TPM instance will use to configure the TSS channels 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 [1].

7.3.2.2. Set_Reference(Serialization)

If Serialization is required, a new TPM instance must set its reference to a Serialization Interface before the TPM is initialized.

void Set_Reference (
    /* in */  const FACE::STRING_TYPE &interface_name,
    /* in */  FACE::TSS::Serialization **interface_reference,
    /* out */ const FACE::GUID_TYPE id,
    /* out */ FACE::RETURN_CODE_TYPE::Value &return_code);
)

Table 7.33 FACE::TSS::Serialization_Injectable::Set_Reference Parameters

Parameter Name	Type	Direction	Description
interface_name	FACE::STRING_TYPE	IN	Unused by Connext TSS.
interface_reference	FACE::TSS::Serialization	IN	A reference to a FACE Serialization instance for Connext TSS.
id	FACE::GUID_TYPE	OUT	Unused by Connext TSS.
return_code	FACE::RETURN_CODE_TYPE	OUT	The return code for the call to Set_Reference(TPM). 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.34 FACE::Serialization_Injectable::Set_Reference Return Codes

Return Code	Description
FACE::NO_ERROR	The operation completed successfully.
FACE::NO_ACTION	A Serialization reference was previously set successfully.

The Set_Reference function sets the FACE Serialization instance that a TPM instance will use.

The interface_reference must be a configured instance of FACE::TSS::Serialization implementing the FACE 3.x Serialization Interface.

The Set_Reference function is non-blocking.

This function is not thread safe [1].

7.3.2.3. Set_Reference(Primitive_Marshalling)

If Serialization that requires Primitive_Marshalling is required, a new TPM instance must set its reference to a Primitive_Marshalling Interface before the TPM is initialized.

void Set_Reference (
    /* in */  const FACE::STRING_TYPE &interface_name,
    /* in */  FACE::TSS::Primitive_Marshalling **interface_reference,
    /* out */ const FACE::GUID_TYPE id,
    /* out */ FACE::RETURN_CODE_TYPE::Value &return_code);
)

Table 7.35 FACE::Primitive_Marshalling_Injectable::Set_Reference Parameters

Parameter Name	Type	Direction	Description
interface_name	FACE::STRING_TYPE	IN	Unused by Connext TSS.
interface_reference	FACE::TSS::Primitive_Marshalling	IN	A reference to a FACE Primitive_Marshalling instance for Connext TSS.
id	FACE::GUID_TYPE	OUT	Unused by Connext TSS.
return_code	FACE::RETURN_CODE_TYPE	OUT	The return code for the call to Set_Reference(TPM). 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.36 FACE::Primitive_Marshalling_Injectable::Set_Reference Return Codes

Return Code	Description
FACE::NO_ERROR	The operation completed successfully.
FACE::NO_ACTION	A Primitive_Marshalling reference was previously set successfully.

The Set_Reference function sets the FACE Primitive_Marshalling instance that a TPM instance will use.

The interface_reference must be a configured instance of FACE::TSS::Primitive_Marshalling implementing the FACE 3.x Primitive_Marshalling Interface.

The Set_Reference function is non-blocking.

This function is not thread safe [1].

7.3.2.4. Set_Reference(Logging_Interface)

A new TPM instance must set its reference to a Logging Interface before the TPM is initialized to enable logging.

void Set_Reference (
    /* in */  const FACE::STRING_TYPE &interface_name,
    /* in */  FACE::Logging **interface_reference,
    /* out */ const FACE::GUID_TYPE id,
    /* out */ FACE::RETURN_CODE_TYPE::Value &return_code);
)

Table 7.37 FACE::Logging::Set_Reference Parameters

Parameter Name	Type	Direction	Description
interface_name	FACE::STRING_TYPE	IN	Unused by Connext TSS.
interface_reference	FACE::Logging	IN	A reference to a FACE Logging instance for Connext TSS.
id	FACE::GUID_TYPE	OUT	Unused by Connext TSS.
return_code	FACE::RETURN_CODE_TYPE	OUT	The return code for the call to Set_Reference(TPM). 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.38 FACE::Logging_Injectable::Set_Reference Return Codes

Return Code	Description
FACE::NO_ERROR	The operation completed successfully.
FACE::NO_ACTION	A Logging reference was previously set successfully.

The Set_Reference function sets the FACE Logging instance that a TPM instance will use.

The interface_reference must be a configured instance of FACE::Logging implementing the FACE 3.x Logging Interface.

The Set_Reference function is non-blocking.

This function is not thread safe [1].

7.3.2.5. Initialize()

Once the Configuration Interface reference is set, the TPM is initialized by calling the TPM interface Initialize(TPM) function.

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

Table 7.39 FACE::TPM::Initialize Parameters

Parameter Name	Type	Direction	Description
return_code	FACE::RETURN_CODE_TYPE&	OUT	The return code for the call to Initialize(TPM). 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.40 FACE::TS::Initialize Return Codes

Return Code	Description
FACE::NO_ERROR	The operation completed successfully.
FACE::NO_ACTION	Transport Protocol Module was successfully initialized previously.
FACE::NOT_AVAILABLE	Transport Protocol Module internal data could not be properly initialized.
FACE::INVALID_CONFIG	Transport Protocol Module could not be configured with the provided configuration parameter.

The Initialize(TPM) function will initialize Transport Protocol Module 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(TPM) function is non-blocking.

This function is not thread safe [1].

7.3.3. Connections

7.3.3.1. Open_Channel()

A channel is created with the RTI::TSS::TPM Open_Channel function.

void Open_Channel(
  const FACE::TSS::CONNECTION_NAME_TYPE& endpoint_name,
  const FACE::TSS::DATA_BUFFER_TYPE& transport_config,
  const FACE::TSS::DATA_BUFFER_TYPE& security_config,
  FACE::TSS::TPM::CHANNEL_ID_TYPE& channel_id,
  RETURN_CODE_TYPE::Value& return_code
)

Table 7.41 FACE::TSS::Open_Channel Parameters

Parameter Name	Type	Direction	Description
endpoint_name	FACE::TSS::CONNECTION_NAME_TYPE	IN	The name of the channel to create. Must match the name (case-insensitive) of a connection in configuration data.
transport_config	FACE::TSS::DATA_BUFFER_TYPE	IN	Reference to implementation-defined transport metadata. NOTE: This parameter is not supported by RTI TSS and consequently is set to 0.
security_config	FACE::TSS::DATA_BUFFER_TYPE	OUT	Reference to implementation-defined security metadata such as certificates, public keys, or enabling encryption for a channel. NOTE: This parameter is not supported by RTI TSS. Security is set in Configuration.
channel_id	FACE::TSS::TPM::CHANNEL_ID_TYPE	OUT	A unique channel ID. This ID will be used to refer to the connection in all other TPM API calls for this TPM. This field is passed by reference and is set upon return from a successful call.
return_code	FACE::RETURN_CODE_TYPE	OUT	The return code for the call to FACE::TSS::TPM::Open_Channel. 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.42 FACE::TSS::TPM::Open_Channel 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::TSS::TPM::Open_Channel.
FACE::INVALID_PARAM	A configuration with a name matching the provided endpoint_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.43 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 Publisher to contain multiple DataWriters, in Connext TSS Publisher 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 [1] for Connext Micro.

7.3.3.2. Close_Channel

void Close_Channel(
    const FACE::TSS::CONNECTION_ID_TYPE channel_id,
    FACE::RETURN_CODE_TYPE::Value &return_code
)

Table 7.44 FACE::TSS::TPM::Close_Channel Parameters

Parameter Name	Type	Direction	Description
channel_id	FACE::TSS::TPM::CHANNEL_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 Close_Channel(). 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.45 FACE::TSS::TPM::Close_Channel 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

Transport Protocol Module built with Connext Micro for Safety Base or Security OSS profiles does not reclaim any Transport Protocol Module channels or DDS resources.

7.3.4. TPM Status and State

7.3.4.1. Request_TPM_State_Change

void Request_TPM_State_Change(
  const TPM_STATE_TYPE::Value& new_state,
  const FACE::TSS::TPM::TPMTS::STATE_CHANGE_DATA_TYPE& data,
  RETURN_CODE_TYPE::Value& return_code
  )

Table 7.46 FACE::TSS::TPM::Request_TPM_State_Change Parameters

Parameter Name	Type	Direction	Description
new_state	FACE::TSS::TPM_STATE_TYPE	IN	The new state to which the TPM should transition.
data	FACE::TSS::TPM::TPMTS::STATE_CHANGE_DATA_TYPE	IN	Reference to data associated with requests to change the test or secure states.
return_code	FACE::RETURN_CODE_TYPE	OUT	The return code for the call to Request_TPM_State_Change(). 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.47 FACE::TSS::TPM::Request_TPM_State_Change

Return Code	Description
FACE::NOT_AVAILABLE	Transport Protocol Module does support the requested state change.
FACE::NO_ACTION	The connection was already destroyed.
FACE::NO_ERROR	The operation completed successfully.

7.3.4.2. Is_Data_Available

void Is_Data_Available(
  CHANNEL_ID_SEQ_TYPE channel_ids,
  FACE::TIMEOUT_TYPE timeout,
  CHANNEL_ID_SEQ_TYPE available_ids,
  RETURN_CODE_TYPE return_code);
  )

Table 7.48 FACE::tss::TPM::TPMTS::Is_Data_Available

Parameter Name	Type	Direction	Description
channel_ids	FACE::tss::TPM::TPMTS::CHANNEL_ID_SEQ_TYPE	IN	The list of channels to be checked for data.
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.
available_ids	FACE::tss::TPM::TPMTS::CHANNEL_ID_SEQ_TYPE	OUT	The list of channels for which data is available.
return_code	FACE::RETURN_CODE_TYPE	OUT	The return code for the call to Is_Data_Available(). 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.49 FACE::TS::Is_Data_Available Return Codes

Return Code	Description
FACE::NO_ACTION	Transport Protocol Module had an unknown failure.
FACE::NOT_AVAILABLE	Transport Protocol Module was not properly initialized prior to the call to FACE::tss::TPM::TPMTS::Is_Data_Available().
FACE::INVALID_PARAM	The list of channel_ids was null or did not contain any valid ids.
FACE::NO_ERROR	The operation completed successfully.

Note

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

7.3.4.3. Get_TPM_Status

void Get_TPM_Status(
  EVENT_TYPE::Value& status,
  RETURN_CODE_TYPE::Value& return_code
  )

Table 7.50 FACE::TSS::TPM::TPMTS::Get_TPM_Status Parameters

Parameter Name	Type	Direction	Description
status	FACE::TSS::TPM::EVENT_TYPE::Value	out	The ID of the connection to be destroyed.
return_code	FACE::RETURN_CODE_TYPE	OUT	The return code for the call to Get_TPM_Status(). 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.51 FACE::TS::Get_TPM_Status Return Codes

Return Code	Description
FACE::NOT_AVAILABLE	Transport Protocol Module was not properly initialized prior to the call to FACE::TSS::TPM::TPMTS::Get_TPM_Status().
FACE::NO_ERROR	The operation completed successfully.

Note

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

7.3.5. Communication

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

7.3.5.1. Write_To_Transport()

void Write_To_Transport(
  FACE::TSS::TPM::CHANNEL_ID_TYPE channel_id,
  FACE::TIMEOUT_TYPE max_delay,
  const FACE::TSS::MESSAGE_TYPE& message,
  const FACE::TSS::HEADER_TYPE& TSS_header,
  FACE::TSS::TRANSACTION_ID_TYPE transaction_id,
  FACE::RETURN_CODE_TYPE::Value& return_code
  )

Table 7.52 FACE::TSS::TPM::TPMTS::Write_To_Transport Parameters

Parameter Name	Type	Direction	Description
channel_id	FACE::TSS::TPM::CHANNEL_ID_TYPE	IN	The ID of a created connection to use to send the message.
max_delay	FACE::TIMEOUT_TYPE	IN	The timeout parameter is not used by Connext TSS.
message	FACE::TSS::MESSAGE_TYPE	INOUT	The message to be sent.
TSS_Header	FACE::TSS::HEADER_TYPE	INOUT	The header 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.
return_code	FACE::RETURN_CODE_TYPE	OUT	The return code for the call to FACE::TSS::TPM::TPMTS::Write_To_Transport. 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.53 FACE::TSS::TPM::TPMTS::Write_To_Transport Return Codes

Return Code	Description
FACE::NOT_AVAILABLE	Transport Protocol Module was not properly initialized prior to the call to FACE::TSS::TPM::TPMTS::Write_To_Transport.
FACE::INVALID_PARAM	The provided channel_id parameter does not correspond to an active channel or the DDS DataWriter’s write call returned an error.
FACE::CONNECTION_CLOSED	The provided channel_id existed at some point but its associated channel was already destroyed.
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 channel with the matching channel ID will have written one message.

This function is not thread safe [2].

7.3.5.2. Read_From_Transport()

void Read_From_Transport(
  FACE::TSS::TPM::CHANNEL_ID_TYPE channel_id,
  FACE::TIMEOUT_TYPE timeout,
  FACE::TSS::TRANSACTION_ID_TYPE& transaction_id,
  FACE::TSS::MESSAGE_TYPE& message,
  FACE::TSS::HEADER_TYPE& TSS_header,
  FACE::TSS::QoS_EVENT_TYPE& qos_parameters,
  RETURN_CODE_TYPE::Value& return_code
)

Table 7.54 FACE::TSS::TPM::TPMTS::Read_From_Transport Parameters

Parameter Name	Type	Direction	Description
connection_id	FACE::TSS::TPM::CHANNEL_ID_TYPE	IN	The ID of the channel to be used for receiving the message. This ID is returned via a successful call to FACE::TSS::TPM::TPMTS::Open_Channel.
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::TSS::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::TSS::MESSAGE_TYPE	INOUT	The message to be received.
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::TSS::TPM::TPMTS::Read_From_Transport. 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.55 FACE::TSS::TPM::TPMTS::Read_From_Transport Return Codes

Return Code	Description
FACE::NOT_AVAILABLE	Transport Protocol Module was not properly initialized prior to the call to FACE::TSS::TPM::TPMTS::Read_From_Transport or no data was received.
FACE::INVALID_PARAM	The provided channel_id parameter does not correspond to an active channel or the timeout value is invalid.
FACE::CONNECTION_CLOSED	The provided channel_id existed at some point but its associated channel was already destroyed.
FACE::INVALID_MODE	The channel associated with the channel_id is of direction FACE::SOURCE. FACE::TSS::TPM::TPMTS::Read_From_Transport only works with channels using direction FACE::DESTINATION or FACE::BI_DIRECTIONAL.
FACE::TIMED_OUT	The call to FACE::TSS::TPM::TPMTS::Read_From_Transport timed out before any data was received on the channel.
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 channel with the matching channel ID will have received and taken one message.

This function is not thread safe [2].

7.3.6. Callback Interface

Type Abstraction callbacks are triggered by a call from a Transport Protocol Module Data Callback Handler for a specific Type Abstraction connection. The Type Abstraction callback is internally implemented in the RTI implementation of the Type Abstraction; triggering it calls the associated Typed TS Callback handler. Type Abstraction callback registration happens automatically when a Typed TS callback is registered.

7.3.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_TPM_Callback(
  FACE::TSS::CONNECTION_ID_TYPE   channel_id,
  FACE::TSS::TPM::TPM_Callback**   callback,
  FACE::RETURN_CODE_TYPE::Value&  return_code
)

Table 7.56 FACE::TSS::TPM::TMPTS::Register_TPM_Callback Parameters

Parameter Name	Type	Direction	Description
channel_id	FACE::CONNECTION_ID_TYPE	IN	The ID of the channel on which the messages shall be received. This ID is returned via a successful call to Open_Channel.
callback	FACE::TSS::TPM::TPM_Callback	IN	The user-defined callback function(s) to invoke.
return_code	FACE::RETURN_CODE_TYPE	OUT	The return code for the call to FACE::TSS::TPM::TMPTS::Register_TPM_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.57 FACE::TSS::TPM::TMPTS::Register_TPM_Callback Return Codes

Return Code	Description
FACE::NOT_AVAILABLE	Transport Protocol Module was not properly initialized prior to the call.
FACE::INVALID_PARAM	The provided channel_id parameter does not correspond to an active channel or the callback parameter is invalid.
FACE::CONNECTION_CLOSED	The provided channel_id existed at some point but its associated channel 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 channel.

This function is not thread safe [1].

7.3.6.2. TPM_Callback::Data_Callback_Handler

TPM Data callbacks are called on DDS Data events which are triggered by the DDS Listener on_data_available callback. The end user is responsible for implementing the DDS Data on_data_available callback and a generated example is provided for each of the high level types. The on_data_available callback calls the TPM Data Callback handler. The TPM Data Callback handler is implemented by the end user and must be injected into the TPM via FACE Injectable APIs for it to be used. RTI TSS provides a default implementation of the TPM Data Callback handler that calls up to Type Abstraction->Typed TS layers. When setting up a Data Callback, the end user must register the on_data_available callback with the DDS Listener in the Transport Protocol Module configuration. The underlying Connext APIs should be consulted for more information about registering a DDS Listener on_data_available callback.

void Data_Callback_Handler(
  FACE::TSS::TPM::CHANNEL_ID_TYPE channel_id,
  FACE::TSS::TRANSACTION_ID_TYPE transaction_id,
  const FACE::TSS::MESSAGE_TYPE& message,
  const FACE::TSS::HEADER_TYPE& tss_header,
  const FACE::TSS::QoS_EVENT_TYPE& qos_parameters,
  RETURN_CODE_TYPE::Value& return_code
  )

Table 7.58 FACE::Read_Callback:Data_Callback_Handler_Parameters

Parameter Name	Type	Direction	Description
channel_id	FACE::TSS::TPM::CHANNEL_ID_TYPE	IN	The ID of the channel on which the message was received.
transaction_id	FACE::TSS::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::TSS::MESSAGE_TYPE	INOUT	The message that was received.
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 Data_Callback_Handler. 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.59 FACE::Unregister_Callback Return Codes

Return Code	Description
FACE::NO_ERROR	The callback was successfully called.
FACE::INVALID_PARAM	One of the parameters was invalid.

7.3.6.3. TPM_Callback::Event_Callback_Handler

Event callbacks are called on DDS Listener events with the end user being responsible for implementing the DDS Listener Event callbacks. In this DDS Listener callback the user calls the TPM Event Callback handler that has been injected into the TPM. The event Callback handler also implemented by the end user will be called and the user code executed upon DDS Listener event callbacks being triggered. For a list of exmaple DDS Listener events see the DDS Listener API documentation. When setting up an Event Callback, the end user must register the DDS Listener event callbacks with the DDS Listener in the Transport Protocol Module configuration. The underlying Connext APIs should be consulted for more information about registering a DDS Listener event callback.

void Event_Callback_Handler(
  FACE::TSS::TPM::CHANNEL_ID_TYPE channel_id,
  FACE::TSS::TRANSACTION_ID_TYPE transaction_id,
  const EVENT_TYPE::Value& event,
  FACE::TSS::TPM::TPM_Callback::EVENT_CODE_TYPE event_code,
  const FACE::TSS::TPM::TPM_Callback::DIAGNOSTIC_MSG_TYPE& diagnostic_msg,
  RETURN_CODE_TYPE::Value& return_code);

Table 7.60 FACE::Read_Callback:Event_Callback_Handler_Parameters

Parameter Name	Type	Direction	Description
channel_id	FACE::TSS::TPM::CHANNEL_ID_TYPE	IN	The ID of the channel 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.
event	EVENT_TYPE::Value	IN	The event that was received.
event_code	FACE::TSS::TPM::TPM_Callback::EVENT_CODE_TYPE	OUT	Event Code returned by the underlying transport.
diagnostic_msg	FACE::TSS::TPM::TPM_Callback::DIAGNOSTIC_MSG_TYPE	OUT	The associated diagnostic message from the event.
return_code	FACE::RETURN_CODE_TYPE	OUT	The return code for the call to Event_Callback_Handler. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure.

7.3.6.4. 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.61 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.62 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 [1].

7.3.7. FACE String

Connext TSS provides a FACE compliant String API.

• Constructors

• Destructor

• clear

• append

• reserve

• buffer

• length

• capacity

• bound

• is_managed

• is_bounded

• is_valid

7.3.7.1. Headers

Include code/C++/include/FACE/String.hpp to allow your application to call the FACE String APIs implemented by the RTI FACE String library. This file defines the Connext TSS implementation of the FACE String Interface.

For a reference on including headers, see the example application in the <RTITSSHOME>\examples directory.

7.3.7.2. FACE::String::String()

Default Constructor:

String()

Managed Constructor:

String(
  FACE::UnsignedLong bound,
  RETURN_CODE& return_code)

Umanaged Constructor:

String(const char * str)

Managed Copy Constructor:

String(const String& str)

Managed C-String Constructor:

String(
 const char *str,
 RETURN_CODE& return_code)

Umanaged Constructor:

String(
  char* str,
  FACE::UnsignedLong length,
  FACE::UnsignedLong bound,
  RETURN_CODE& return_code)

7.3.7.3. FACE::String::~String()

Default Destructor:

~String()

7.3.7.4. FACE::String::clear()

Clears this string’s data:

void clear()

7.3.7.5. FACE::String::append()

Appends a string or an element to the string:

RETURN_CODE append(const String& str)

RETURN_CODE append(const FACE::Char& elem)

7.3.7.6. FACE::String::reserve()

Attempts to reserve memory for capacity number of characters:

RETURN_CODE reserve(FACE::UnsignedLong capacity);

7.3.7.7. FACE::String::buffer()

Returns C-string representation of string data:

char * buffer();
const char * buffer() const;

7.3.7.8. FACE::String::length()

Returns the length of this String:

FACE::UnsignedLong length() const;

7.3.7.9. FACE::String::capacity()

Returns the capacity of this String:

FACE::UnsignedLong capacity() const;

7.3.7.10. FACE::String::bound()

Returns the bound of this String:

FACE::UnsignedLong bound() const;

7.3.7.11. FACE::String::is_managed()

Returns whether or not this String is managed:

FACE::Boolean is_managed() const;

7.3.7.12. FACE::String::is_bounded()

Returns whether or not this String is bounded:

FACE::Boolean is_bounded() const;

7.3.7.13. FACE::String::is_valid()

Returns whether or not this String is in the invalid state:

FACE::Boolean is_valid() const;

7.3.8. FACE Sequence

Connext TSS provides a FACE compliant Sequence API.

• Constructors

• Destructor

• clear

• append

• reserve

• buffer

• length

• capacity

• bound

• is_managed

• is_bounded

• is_valid

7.3.8.1. Headers

Include code/C++/include/FACE/Sequence.hpp to allow your application to call the FACE Sequence APIs implemented by the RTI FACE Sequence library. This file defines the TSS implementation of the FACE Sequence Interface.

For a reference on including headers, see the example application in the <RTITSSHOME>\examples directory.

7.3.8.2. FACE::Sequence::Sequence()

Default Constructor:

Sequence()

Managed Constructor:

Sequence(
  FACE::UnsignedLong bound,
  RETURN_CODE& return_code)

Managed C-style array Constructor:

Sequence(const T * arr,
              FACE::UnsignedLong length,
              RETURN_CODE& return_code)

Managed Copy Constructor:

Sequence(const Sequence& seq)

Umanaged Constructor:

Sequence(
  const T * arr,
  FACE::UnsignedLong length,
  FACE::UnsignedLong bound,
  RETURN_CODE& return_code)

7.3.8.3. FACE::Sequence::~Sequence()

Default Destructor:

~Sequence()

7.3.8.4. FACE::Sequence::clear()

Clears this Sequence’s data:

void clear()

7.3.8.5. FACE::Sequence::append()

Appends a Sequence or an element to the Sequence:

RETURN_CODE append(const Sequence& seq)

RETURN_CODE append(const T& elem)

7.3.8.6. FACE::Sequence::reserve()

Attempts to reserve memory for capacity number of characters:

RETURN_CODE reserve(FACE::UnsignedLong capacity);

7.3.8.7. FACE::Sequence::buffer()

Returns C-Sequence representation of Sequence data:

T * buffer();
const T * buffer() const;

7.3.8.8. FACE::Sequence::length()

Returns the length of this Sequence:

FACE::UnsignedLong length() const;

7.3.8.9. FACE::Sequence::capacity()

Returns the capacity of this Sequence:

FACE::UnsignedLong capacity() const;

7.3.8.10. FACE::Sequence::bound()

Returns the bound of this Sequence:

FACE::UnsignedLong bound() const;

7.3.8.11. FACE::Sequence::is_managed()

Returns whether or not this Sequence is managed:

FACE::Boolean is_managed() const;

7.3.8.12. FACE::Sequence::is_bounded()

Returns whether or not this Sequence is bounded:

FACE::Boolean is_bounded() const;

7.3.8.13. FACE::Sequence::is_valid()

Returns whether or not this Sequence is in the invalid state:

FACE::Boolean is_valid() const;

7.4. Logging

Connext TSS utilizes the logging interface found in FACE CR 748 to implement logging. Connext TSS by defaults does not log until a Logging Injectable has been injected into each UoC that requires logging to be enabled. To log, Connext TSS calls the injected logger via the FACE logging APIs. You are responsible for providing the FACE Log type to be injected.

The Hello_Goodbye Example, included in Connext TSS in both C and C++, provides a basic FACE logger that prints any log message sent to it regardless of logging level. You can choose to modify the example or provide your own logger.

Note

If no FACE Logger is injected, Connext TSS will not perform any logging.

7.4.1. Log_Text(LOGGING)

module FACE {
interface Logging {
void Log_Text (
in TEXT_MESSAGE_TYPE message,
in SEVERITY_LEVEL severity,
out RETURN_CODE_TYPE return_code
}; // interface Logging
}; module FACE

Table 7.63 FACE Log_Text(LOGGING) Parameters

Parameter Name	Description
message	Contains the log message to be logged.
severity	Contains the applicable logging level of the message.
return_code	Upon return, this parameter will be populated with a value that will indicate either success or a reason for failure.

Table 7.64 FACE Log_Text(LOGGING) Return Codes

Return Code	Description
NO_ERROR	Indicates successful completion of the operation.
INVALID_CONFIG	Indicates that the interface is not properly configured for use.
INVALID_PARAM	Indicates that either the buffer or return_code pointer (in appropriate languages) is invalid or the message is of zero length.

7.4.2. Log_Binary(LOGGING)

module FACE {
interface Logging {
void Log_Binary (
in SYSTEM_ADDRESS_TYPE message,
in LENGTH_TYPE length,
in SEVERITY_LEVEL severity,
out RETURN_CODE_TYPE return_code
}; // interface Logging
}; module FACE

Table 7.65 FACE Log_Binary(LOGGING) Parameters

Parameter Name	Description
buffer	Contains the binary log message to be logged.
severity	Specifies the applicable logging level of the message.
return_code	Upon return, this parameter will be populated with a value that will indicate either success or a reason for failure.

Table 7.66 FACE Log_Binary(LOGGING) Return Codes

Return Code	Description
NO_ERROR	Indicates successful completion of the operation.
INVALID_CONFIG	Indicates that the interface is not properly configured for use.
INVALID_PARAM	Indicates that either the buffer or return_code pointer (in appropriate languages) is invalid or the message is of zero length.

Footnotes

[1] (1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17)

It is not safe to call multiple non-thread-safe APIs at the same time in the same memory space. This is because they share an underlying global object.

[2] (1,2,3,4,5,6)

Send_Message() and Receive_Message() functions are thread safe relative to each other if they are on different connection IDs (set with the “connection_id” parameter).