9. 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.
9.1. Thread Safety Model
This section summarizes thread-safety behavior validated against the current library implementations for Connext Micro in C and C++ and Connext Professional in C.
9.1.1. API Thread Safety
Connext TSS is thread-safe for concurrent calls on the same Base/TypedTS instance,
such as Initialize(), Create_Connection(), Destroy_Connection(),
Send_Message(), Receive_Message(), Register_Callback(), and
Unregister_Callback().
Set_Reference() APIs are internally synchronized, but should still be
called during initialization before message traffic starts.
Read_Callback::Callback_Handler() executes on middleware receive threads.
Your application callback code must be thread-safe.
Concurrent calls are always safe, but some briefly delay others; see Product Thread Safety for the timing consequence.
9.1.2. Product Thread Safety
Connext TSS serializes work at two levels: at the level of structural
operations, which consist of creating and destroying a connection,
registering and unregistering a callback, initializing and finalizing the
Transport Protocol Module, and constructing and destroying a Base; and at the level of
message operations, which consist of Send_Message(), Receive_Message(),
and Is_Data_Available(). Structural operations run one at a time, and
alone. Message operations run concurrently with each other.
A message operation that is issued while a structural operation is pending, waits then completes; it never fails in this case. A healthy connection does not report an error because another thread is creating or destroying an unrelated one. The error codes these calls return always describe the connection or the caller, never the timing of an unrelated operation.
The message operation’s wait is bounded by one receive wait slice plus the duration of the
structural operation itself. A wait slice is the longest interval Connext TSS leaves
a “receive” parked in the transport: rather than hand a blocking
Receive_Message() its caller’s timeout whole, Connext TSS composes that timeout
from slices of FACE_RECEIVE_WAIT_SLICE_NS (see DDS Defaults)
and rechecks state between them. Such a receive therefore delays a structural
operation by at most one slice rather than by its full timeout, and the timeout
the caller observes is unchanged. No framework lock is held across transport
I/O.
Two calling contexts are refused rather than made to wait, because each would
otherwise wait on the operation it is already running inside. Connext TSS invokes an
injected Configuration implementation during a structural operation: a call
back into Connext TSS from inside that implementation is refused, whether it is a
structural or a message operation. A structural operation called from inside a
callback is refused for the same reason; a message operation from a callback is
not. Both refusals return FACE::NOT_AVAILABLE.
This serialization is process-wide per language binding: two Base instances in one process contend with each other, and the C and C++ bindings are independent. Under the SafetyBase profile, the control plane is create-only—structural operations occur during startup and not afterward—so steady-state message traffic is never paused.
9.2. 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 initialization 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.
9.2.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.hppdefines the FACE TSS Type-Specific Typed Interface for the user datatype, and the generated header file<modules>/<user_datatype_name>/TypedTS_Impl.hppdefines the implementation of that interface.
For a reference on including headers, see the example application in
the <RTITSSHOME>\examples directory.
9.2.2. 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.
9.2.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
)
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 |
transaction_id |
FACE::TRANSACTION_ID_TYPE |
INOUT |
The |
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
|
return_code |
FACE::RETURN_CODE_TYPE |
OUT |
The return code for the call to |
Return Code |
Description |
|---|---|
FACE::NOT_AVAILABLE |
Connext TSS was not properly initialized prior to the call to
|
FACE::INVALID_PARAM |
The provided |
FACE::CONNECTION_CLOSED |
The provided |
FACE::INVALID_MODE |
The connection associated with the |
FACE::NO_ACTION |
The underlying 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 thread-safe [2].
9.2.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
)
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 |
message |
DATATYPE_TYPE |
INOUT |
The strongly typed message to be received. An implementer will
substitute their type for NOTE: The type of the message must correspond to the type specified
in the connection configuration for the given |
header |
FACE::TSS::HEADER_TYPE |
OUT |
The |
qos_parameters |
FACE::TSS::QoS_EVENT_TYPE |
OUT |
The |
return_code |
FACE::RETURN_CODE_TYPE |
OUT |
The return code for the call to |
Return Code |
Description |
|---|---|
FACE::NOT_AVAILABLE |
Connext TSS was not properly initialized prior to the call to
|
FACE::INVALID_PARAM |
The provided |
FACE::CONNECTION_CLOSED |
The provided |
FACE::INVALID_MODE |
The connection associated with the |
FACE::TIMED_OUT |
The call to |
FACE::MESSAGE_STALE |
The instance was disposed. |
FACE::NO_ACTION |
The underlying TPMs returned an error. |
FACE::NO_ERROR |
The operation completed successfully. |
Users will poll with this function for received data.
This function is thread-safe [2].
9.2.3. Callback Interface
The FACE TSS callback interface allows for messages to be received without polling.
9.2.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
)
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 |
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 |
Return Code |
Description |
|---|---|
FACE::NOT_AVAILABLE |
Connext TSS was not properly initialized prior to the call to
|
FACE::INVALID_PARAM |
The provided |
FACE::CONNECTION_CLOSED |
The provided |
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.
A connection may be registered and unregistered repeatedly. NO_ACTION means
a callback is registered on the connection right now, not that one was ever
registered on it: once Unregister_Callback has returned successfully, a
further Register_Callback on the same connection installs a new callback and
returns NO_ERROR.
This function is thread-safe for concurrent callers.
9.2.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
)
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 |
message |
FACE_SPECIFIED_TYPE |
INOUT |
The strongly typed message that was received. An implementer will
substitute their type for NOTE: The type of the message must correspond to the type specified
in the connection configuration for the given |
header |
FACE::TSS::HEADER_TYPE |
OUT |
The |
qos_parameters |
FACE::TSS::QoS_EVENT_TYPE |
OUT |
The |
return_code |
FACE::RETURN_CODE_TYPE |
OUT |
The return code for the call to |
9.2.3.3. 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
)
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 |
Return Code |
Description |
|---|---|
FACE::NOT_AVAILABLE |
The RTI TSS was not properly initialized prior to the call to
|
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::NO_ERROR |
The operation completed successfully. On a connection spanning more
than one channel, this is returned if any channel’s callback was
removed; a channel whose callback the transport reports as already
absent counts as removed, since the requested end state – no callback
on that channel – holds either way. Channels whose callbacks could not
be removed stay registered and keep dispatching, and a repeated
|
This function is thread-safe for concurrent callers.
Unregister_Callback may return while a final callback invocation is still
completing on another thread. No new invocation begins once it has returned:
the callback is closed to further dispatch before the listener is detached, so
every later delivery is discarded. What is not guaranteed is that a callback
already in progress has finished. The FACE 3.2 Unregister_Callback
semantics permit this, and Connext TSS takes it deliberately, in exchange for an
Unregister_Callback that never blocks waiting on application callback code.
An application that releases resources its callback captures – a buffer the
callback writes into, an object whose method it calls – must therefore tolerate
one last invocation overlapping the return of Unregister_Callback, and must
not free those resources on the assumption that the callback is already
finished. Where an application needs that assurance, it should have the callback
itself signal completion, and wait for that signal after Unregister_Callback
returns.
Calling Unregister_Callback – or any other control-plane operation, such as
Create_Connection, Destroy_Connection or Register_Callback – from
inside a callback is a programming error, and Connext TSS reports it rather than
performing it: the call returns FACE::NOT_AVAILABLE and changes nothing. A
callback therefore cannot unregister itself, and must ask an application thread
to do it instead.
The restriction is not arbitrary. A control operation that closed the callback’s
own channel would delete the DDS entity whose listener is running that very
callback, and deleting a DDS entity waits for a running listener to return –
so the operation would wait for the callback that is waiting for the operation.
Refusing is what turns that deadlock into a return code. Data-plane calls
(Send_Message, Receive_Message, Is_Data_Available) are not
restricted this way and may be made freely from a callback.
9.3. TSS TA Base
Connext TSS implements the FACE TSS Type-Specific Base and Typed Interfaces in the
C++ programming language as the RTI::TSS::Base class.
RTI::TSS::Base also implements the FACE Configuration Injectable,
TPM_Injectable, and the Logging_Injectable interfaces
for Connext TSS configuration.
For applications requiring all resources to be allocated and configured
during an initialization 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.
9.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/FACE/TSS/RTI/Base_impl.hppdefines 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.
9.3.2. Initialization
9.3.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);
)
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 |
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 thread-safe for concurrent callers.
9.3.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);
)
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 |
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 thread-safe for concurrent callers.
9.3.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);
)
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 |
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 thread-safe for concurrent callers.
9.3.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
)
Parameter Name |
Type |
Direction |
Description |
|---|---|---|---|
return_code |
FACE::RETURN_CODE_TYPE& |
OUT |
The return code for the call to |
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 thread-safe for concurrent callers.
9.3.3. Connections
9.3.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
)
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 |
Return Code |
Description |
|---|---|
FACE::NO_ERROR |
The operation completed successfully. |
FACE::NOT_AVAILABLE |
Base was not properly initialized prior to the call to
|
FACE::INVALID_PARAM |
A configuration with a name matching the provided 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 thread-safe for concurrent callers.
9.3.3.2. Destroy_Connection
void Destroy_Connection(
const FACE::TSS::CONNECTION_ID_TYPE connection_id,
FACE::RETURN_CODE_TYPE::Value &return_code
)
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 |
Return Code |
Description |
|---|---|
FACE::NOT_AVAILABLE |
Base was not properly initialized prior to the call to
|
FACE::NO_ACTION |
The connection was already destroyed |
FACE::INVALID_PARAM |
The connection does not exist. |
FACE::NO_ERROR |
The operation completed successfully. Every channel of the connection was closed and the connection no longer exists. |
A connection may span more than one channel, and Destroy_Connection
succeeds only if every one of them closes. FACE::NO_ERROR means the
connection was destroyed; it is never returned for a partial close.
If any channel refuses to close, the call returns FACE::NOT_AVAILABLE and
the connection survives: its record, its channel list, and the channels
that are still open all remain, while the channels that did close stay closed.
The connection is marked as closing from the moment the call is made, so it
refuses data operations from then on – a subsequent Send_Message or
Receive_Message on it returns FACE::CONNECTION_CLOSED – but the
connection id remains valid.
The call is therefore retryable, and should be retried: calling
Destroy_Connection again with the same id attempts only the channels still
open, and returns FACE::NO_ERROR once the last of them closes. An
application that treats FACE::NOT_AVAILABLE here as a permanent failure and
does not retry leaks the connection and its open channels for the lifetime of
the process.
This function is thread-safe for concurrent callers.
9.3.3.3. Enable_Runtime()
Future functionality.
9.3.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.
9.3.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
)
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 |
transaction_id |
FACE::TSS::TRANSACTION_ID_TYPE |
INOUT |
The |
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 |
Return Code |
Description |
|---|---|
FACE::NOT_AVAILABLE |
Connext TSS was not properly initialized prior to the call to
|
FACE::INVALID_PARAM |
The provided |
FACE::CONNECTION_CLOSED |
The provided |
FACE::INVALID_MODE |
The connection associated with the |
FACE::NO_ACTION |
The underlying 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 thread-safe [2].
9.3.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
)
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 |
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 |
size_limit |
FACE::TSS::MESSAGE_SIZE_TYPE |
IN |
The maximum size of a message to be received. This parameter is not currently used by Connext TSS. |
message |
FACE::TSS::MESSAGE_TYPE |
INOUT |
The typed message to be sent. |
header |
FACE::TSS::HEADER_TYPE |
OUT |
The |
qos_parameters |
FACE::TSS::QoS_EVENT_TYPE |
OUT |
The |
return_code |
FACE::RETURN_CODE_TYPE |
OUT |
The return code for the call to |
Return Code |
Description |
|---|---|
FACE::NOT_AVAILABLE |
Connext TSS was not properly initialized prior to the call to
|
FACE::INVALID_PARAM |
The provided |
FACE::CONNECTION_CLOSED |
The provided |
FACE::INVALID_MODE |
The connection associated with the |
FACE::TIMED_OUT |
The call to |
FACE::MESSAGE_STALE |
The instance was disposed. |
FACE::NO_ACTION |
The underlying 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 thread-safe [2].
9.3.5. Callback Interface
The FACE TSS callback interface allows for messages to be received without polling.
9.3.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
)
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 |
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 |
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 |
Return Code |
Description |
|---|---|
FACE::NOT_AVAILABLE |
Connext TSS was not properly initialized prior to the call to
|
FACE::INVALID_PARAM |
The provided |
FACE::CONNECTION_CLOSED |
The provided |
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.
A connection may be registered and unregistered repeatedly. NO_ACTION means
a callback is registered on the connection right now, not that one was ever
registered on it: once Unregister_Callback has returned successfully, a
further Register_Callback on the same connection installs a new callback and
returns NO_ERROR.
This function is thread-safe for concurrent callers.
9.3.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
)
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 |
message |
MESSAGE_TYPE |
INOUT |
The message that was received. |
header |
FACE::TSS::HEADER_TYPE |
OUT |
The |
qos_parameters |
FACE::TSS::QoS_EVENT_TYPE |
OUT |
The |
return_code |
FACE::RETURN_CODE_TYPE |
OUT |
The return code for the call to |
9.3.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
)
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 |
Return Code |
Description |
|---|---|
FACE::NOT_AVAILABLE |
The RTI TSS was not properly initialized prior to the call to
|
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::NO_ERROR |
The operation completed successfully. On a connection spanning more
than one channel, this is returned if any channel’s callback was
removed; a channel whose callback the transport reports as already
absent counts as removed, since the requested end state – no callback
on that channel – holds either way. Channels whose callbacks could not
be removed stay registered and keep dispatching, and a repeated
|
This function is thread-safe for concurrent callers.
Unregister_Callback may return while a final callback invocation is still
completing on another thread. No new invocation begins once it has returned:
the callback is closed to further dispatch before the listener is detached, so
every later delivery is discarded. What is not guaranteed is that a callback
already in progress has finished. The FACE 3.2 Unregister_Callback
semantics permit this, and Connext TSS takes it deliberately, in exchange for an
Unregister_Callback that never blocks waiting on application callback code.
An application that releases resources its callback captures – a buffer the
callback writes into, an object whose method it calls – must therefore tolerate
one last invocation overlapping the return of Unregister_Callback, and must
not free those resources on the assumption that the callback is already
finished. Where an application needs that assurance, it should have the callback
itself signal completion, and wait for that signal after Unregister_Callback
returns.
Calling Unregister_Callback – or any other control-plane operation, such as
Create_Connection, Destroy_Connection or Register_Callback – from
inside a callback is a programming error, and Connext TSS reports it rather than
performing it: the call returns FACE::NOT_AVAILABLE and changes nothing. A
callback therefore cannot unregister itself, and must ask an application thread
to do it instead.
The restriction is not arbitrary. A control operation that closed the callback’s
own channel would delete the DDS entity whose listener is running that very
callback, and deleting a DDS entity waits for a running listener to return –
so the operation would wait for the callback that is waiting for the operation.
Refusing is what turns that deadlock into a return code. Data-plane calls
(Send_Message, Receive_Message, Is_Data_Available) are not
restricted this way and may be made freely from a callback.
9.4. TSS TPM Interfaces
Note
These interfaces are internal to Connext TSS and are intended for Transport Protocol Module integrators. The application-facing FACE surface reaches them through the Base/Type Abstraction layer, which provides the serialization described in Product Thread Safety. The Transport Protocol Module layer carries no synchronization of its own: a direct caller bypasses that protection and is responsible for serializing its own calls.
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.
9.4.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.hppdefines 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.
9.4.2. Initialization
9.4.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);
)
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 |
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].
9.4.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);
)
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 |
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].
9.4.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);
)
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 |
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].
9.4.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);
)
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 |
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].
9.4.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
)
Parameter Name |
Type |
Direction |
Description |
|---|---|---|---|
return_code |
FACE::RETURN_CODE_TYPE& |
OUT |
The return code for the call to |
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].
9.4.3. Connections
9.4.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
)
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 |
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::INVALID_PARAM |
A configuration with a name matching the provided 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:
DDS Entity |
Creation Requirements |
|---|---|
DomainParticipant |
Created if there is no existing DomainParticipant for the new
connection’s configured 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 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 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 |
DataReader |
Created if the connection is configured as |
The Open_Channel function is non-blocking.
This function is not thread-safe [1].
9.4.3.2. Close_Channel
void Close_Channel(
const FACE::TSS::CONNECTION_ID_TYPE channel_id,
FACE::RETURN_CODE_TYPE::Value &return_code
)
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 |
Return Code |
Description |
|---|---|
FACE::NOT_AVAILABLE |
Connext TSS was not properly initialized prior to the call to
|
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.
9.4.4. TPM Status and State
9.4.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
)
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 |
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. |
9.4.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);
)
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 |
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::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.
9.4.4.3. Get_TPM_Status
void Get_TPM_Status(
EVENT_TYPE::Value& status,
RETURN_CODE_TYPE::Value& return_code
)
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 |
Return Code |
Description |
|---|---|
FACE::NOT_AVAILABLE |
Transport Protocol Module was not properly initialized prior to the call to
|
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.
9.4.5. 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.
9.4.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
)
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 |
message |
FACE::TSS::MESSAGE_TYPE |
INOUT |
The message to be sent. |
TSS_Header |
FACE::TSS::HEADER_TYPE |
INOUT |
The |
transaction_id |
FACE::TRANSACTION_ID_TYPE |
INOUT |
The |
return_code |
FACE::RETURN_CODE_TYPE |
OUT |
The return code for the call to |
Return Code |
Description |
|---|---|
FACE::NOT_AVAILABLE |
Transport Protocol Module was not properly initialized prior to the call to
|
FACE::INVALID_PARAM |
The provided |
FACE::CONNECTION_CLOSED |
The provided |
FACE::NO_ACTION |
The underlying 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 thread-safe against concurrent data flow: it may run
concurrently with itself and with Read_From_Transport(). It is not safe
against a concurrent Transport Protocol Module control operation issued by a direct caller.
9.4.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
)
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 |
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 |
message |
FACE::TSS::MESSAGE_TYPE |
INOUT |
The message to be received. |
header |
FACE::TSS::HEADER_TYPE |
OUT |
The |
qos_parameters |
FACE::TSS::QoS_EVENT_TYPE |
OUT |
The |
return_code |
FACE::RETURN_CODE_TYPE |
OUT |
The return code for the call to |
Return Code |
Description |
|---|---|
FACE::NOT_AVAILABLE |
Transport Protocol Module was not properly initialized prior to the call to
|
FACE::INVALID_PARAM |
The provided |
FACE::CONNECTION_CLOSED |
The provided |
FACE::INVALID_MODE |
The channel associated with the |
FACE::TIMED_OUT |
The call to |
FACE::MESSAGE_STALE |
The instance was disposed. |
FACE::NO_ACTION |
The underlying 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 thread-safe against concurrent data flow: it may run
concurrently with itself and with Write_To_Transport(). It is not safe
against a concurrent Transport Protocol Module control operation issued by a direct caller.
9.4.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.
9.4.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
)
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 |
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 |
Return Code |
Description |
|---|---|
FACE::NOT_AVAILABLE |
Transport Protocol Module was not properly initialized prior to the call. |
FACE::INVALID_PARAM |
The provided |
FACE::CONNECTION_CLOSED |
The provided |
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].
9.4.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
)
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 |
message |
FACE::TSS::MESSAGE_TYPE |
INOUT |
The message that was received. |
header |
FACE::TSS::HEADER_TYPE |
OUT |
The |
qos_parameters |
FACE::TSS::QoS_EVENT_TYPE |
OUT |
The |
return_code |
FACE::RETURN_CODE_TYPE |
OUT |
The return code for the call to |
Return Code |
Description |
|---|---|
FACE::NO_ERROR |
The callback was successfully called. |
FACE::INVALID_PARAM |
One of the parameters was invalid. |
9.4.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 example 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);
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 |
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 |
9.4.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
)
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 |
Return Code |
Description |
|---|---|
FACE::NOT_AVAILABLE |
The RTI TSS was not properly initialized prior to the call to
|
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 |
This function is not thread-safe [1].
9.4.7. FACE String
Connext TSS provides a FACE compliant String API.
9.4.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.
9.4.7.2. FACE::String::String()
Default Constructor:
String()
Managed Constructor:
String(
FACE::UnsignedLong bound,
RETURN_CODE& return_code)
Unmanaged Constructor:
String(const char * str)
Managed Copy Constructor:
String(const String& str)
Managed C-String Constructor:
String(
const char *str,
RETURN_CODE& return_code)
Unmanaged Constructor:
String(
char* str,
FACE::UnsignedLong length,
FACE::UnsignedLong bound,
RETURN_CODE& return_code)
9.4.7.3. FACE::String::~String()
Default Destructor:
~String()
9.4.7.4. FACE::String::clear()
Clears this string’s data:
void clear()
9.4.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)
9.4.7.6. FACE::String::reserve()
Attempts to reserve memory for capacity number of characters:
RETURN_CODE reserve(FACE::UnsignedLong capacity);
9.4.7.7. FACE::String::buffer()
Returns C-string representation of string data:
char * buffer();
const char * buffer() const;
9.4.7.8. FACE::String::length()
Returns the length of this String:
FACE::UnsignedLong length() const;
9.4.7.9. FACE::String::capacity()
Returns the capacity of this String:
FACE::UnsignedLong capacity() const;
9.4.7.10. FACE::String::bound()
Returns the bound of this String:
FACE::UnsignedLong bound() const;
9.4.7.11. FACE::String::is_managed()
Returns whether or not this String is managed:
FACE::Boolean is_managed() const;
9.4.7.12. FACE::String::is_bounded()
Returns whether or not this String is bounded:
FACE::Boolean is_bounded() const;
9.4.7.13. FACE::String::is_valid()
Returns whether or not this String is in the invalid state:
FACE::Boolean is_valid() const;
9.4.8. FACE Sequence
Connext TSS provides a FACE compliant Sequence API.
9.4.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.
9.4.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)
Unmanaged Constructor:
Sequence(
const T * arr,
FACE::UnsignedLong length,
FACE::UnsignedLong bound,
RETURN_CODE& return_code)
9.4.8.3. FACE::Sequence::~Sequence()
Default Destructor:
~Sequence()
9.4.8.4. FACE::Sequence::clear()
Clears this Sequence’s data:
void clear()
9.4.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)
9.4.8.6. FACE::Sequence::reserve()
Attempts to reserve memory for capacity number of characters:
RETURN_CODE reserve(FACE::UnsignedLong capacity);
9.4.8.7. FACE::Sequence::buffer()
Returns C-Sequence representation of Sequence data:
T * buffer();
const T * buffer() const;
9.4.8.8. FACE::Sequence::length()
Returns the length of this Sequence:
FACE::UnsignedLong length() const;
9.4.8.9. FACE::Sequence::capacity()
Returns the capacity of this Sequence:
FACE::UnsignedLong capacity() const;
9.4.8.10. FACE::Sequence::bound()
Returns the bound of this Sequence:
FACE::UnsignedLong bound() const;
9.4.8.11. FACE::Sequence::is_managed()
Returns whether or not this Sequence is managed:
FACE::Boolean is_managed() const;
9.4.8.12. FACE::Sequence::is_bounded()
Returns whether or not this Sequence is bounded:
FACE::Boolean is_bounded() const;
9.4.8.13. FACE::Sequence::is_valid()
Returns whether or not this Sequence is in the invalid state:
FACE::Boolean is_valid() const;
9.5. 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.
9.5.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
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. |
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. |
9.5.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
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. |
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. |
9.6. TSS Configuration Defaults
Connext TSS provides a central configuration header file,
RTI_Connext_TSS_Config.h, located in the code/ directory. This
file defines default values for compile-time parameters that control
resource limits, buffer sizes, hash-table tuning, and other internal
constants.
Every definition is guarded with #ifndef so that you can override any
value by passing a -D flag to the compiler (or via CMake
add_definitions / target_compile_definitions). If no override is
provided the default value is used.
Include the configuration header in your source files with the following code:
#include "RTI_Connext_TSS_Config.h"
The following subsections define the default parameters in more detail.
9.6.1. Type Bounds
These defaults control the maximum sizes of unbounded IDL strings and sequences generated by rtiddsgen.
Define |
Default |
Description |
|---|---|---|
|
255 |
Maximum length of unbounded strings. |
|
4096 |
Maximum element count of unbounded sequences. |
9.6.2. Resource Limits
These limits govern the maximum number of connections, channels, callbacks, and TPM references managed by Connext TSS.
Define |
Default |
Description |
|---|---|---|
|
10000 |
Maximum connections a single Base instance can own. |
|
50 |
Maximum Transport Protocol Module references a Base instance can hold. |
|
10000 |
Maximum channels within a single connection. |
|
50 |
Maximum channels per channel manager (used when no system configuration specifies a different value). |
|
32 |
Maximum callbacks that can be registered on a single connection. |
9.6.3. Buffer Sizes
These defines set the sizes of internal buffers used for messages, configuration strings, and logging.
Define |
Default |
Description |
|---|---|---|
|
256 |
General-purpose buffer for log messages, temporary strings, etc. |
|
1024 |
Message buffer size. |
|
8192 |
Buffer for configuration strings and bulk data operations. |
|
1024 |
Maximum length of the TSS XML configuration string. Increase this if your configuration exceeds the default. |
|
256 |
Maximum length of the log file name when logging is enabled. |
|
4096 |
Size of the internal log message buffer. |
9.6.4. Hash Table Tuning
Connext TSS uses hash tables internally for entity lookup. These constants control initial sizing, growth, and the hash algorithms used.
Define |
Default |
Description |
|---|---|---|
|
128 |
Initial bucket count for hash tables. |
|
64 |
Lower bound for hash table bucket counts. |
|
75 |
Load factor percentage that triggers rehashing. |
|
2 |
Multiplier applied when expanding hash table capacity. |
|
100 |
Maximum iterations for hash operations (prevents infinite loops). |
|
5381 |
Initial value for the DJB2 hash algorithm. |
|
33 |
Multiplier for the DJB2 hash calculation ( |
|
0x811c9dc5 |
Initial value for the FNV-1a hash algorithm. |
|
0x01000193 |
Prime multiplier for the FNV-1a hash calculation. |
9.6.5. DDS Defaults
This section defines the default DDS configuration values used by Connext TSS when no explicit values are provided.
Define |
Default |
Description |
|---|---|---|
|
0 |
DDS domain ID used when no specific domain is configured. |
|
1000 |
Default timeout in milliseconds for general operations. |
|
100000000 |
Length in nanoseconds of one bounded wait slice. A blocking
|
9.6.6. Overriding Defaults
To override any value at build time by defining it before the header is included (or via a compiler flag), use one of the following commands:
# CMake
add_definitions(-DMAX_CONNECTIONS_PER_BASE_INSTANCE=500)
# Command line
gcc -DMAX_CONNECTIONS_PER_BASE_INSTANCE=500 ...
Or, include the following in your source before the include:
#define MAX_CONNECTIONS_PER_BASE_INSTANCE 500
#include "RTI_Connext_TSS_Config.h"
Footnotes