.. include:: vars.rst .. _section-api_reference: ******************************************************************************** API Reference ******************************************************************************** ------------- TS Interface ------------- Quick links to descriptions of the FACE TS Interface functions: - :ref:`FACE::TS::Initialize ` - :ref:`FACE::TS::Create_Connection ` - :ref:`FACE::TS::Destroy_Connection ` - :ref:`FACE::TS::Receive_Message ` - :ref:`FACE::TS::Send_Message ` - :ref:`FACE::TS::Register_Callback ` - :ref:`FACE::TS::Unregister_Callback ` - :ref:`FACE::TS::Get_Connection_Parameters ` - :ref:`FACE::Read_Callback::send_event ` -------- Headers -------- Including the below header files will allow you to call FACE TSS API functions that are implemented by the RTI FACE TSS library. - The FACE TSS API is defined in the header file ``include/FACE/TS.hpp``. - The type specific part of the FACE TSS API will be defined by header files generated as part of building from your data model: - ``/gen/.hxx`` - ``/gen/_TSS.hpp`` - ``/gen/.hxx`` should either be replaced by user files from the FACE data modeling tools or be renamed ``/gen/.hpp``. - Any header file prepended with "ext_*" can be included in applications or libraries that use |RTI_TSS|. The section RTI FACE TSS Required Plugins (link TBD)) contains more information on why this is relevant. --------------------------------------- Initialization --------------------------------------- .. _API_init: ^^^^^^^^^^^^^^^^^^^^^^ FACE::TS::Initialize() ^^^^^^^^^^^^^^^^^^^^^^ Before using any other features of |TSS|, the TSS must first be initialized using the ``FACE::TS::Initialize()`` API call. .. code-block:: C++ void FACE::TS::Initialize ( /* in */ const FACE::CONFIGURATION_RESOURCE configuration, /* out */ FACE::RETURN_CODE_TYPE &return_code ) .. list-table:: FACE::TS::Initialize Parameters :name: TableFACETSInitializeParams :widths: 12 20 8 60 :header-rows: 1 * - Parameter Name - Type - Direction - Description * - configuration - const FACE::CONFIGURATION_RESOURCE - IN - The name of the configuration to load. This can either be a filename or a static configuration identifier string. |br| NOTE: Configuration files are only available when using |CONNEXT| *Professional* with the General Purpose Profile. Static configuration for all other profiles is enabled by specifying a configuration parameter in the following format: ``RTI_TSS_STATIC_INITIALIZATION##config_name``, where ``config_name`` is a user-defined value passed into the configuration plugin. See the configuration section for additional details. * - return_code - FACE::RETURN_CODE_TYPE& - OUT - The return code for the call to ``FACE::TS:Initialize``. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure. .. list-table:: FACE::TS::Initialize Return Codes :name: TableFACETSInitializeRetCodes :widths: 40 60 :header-rows: 1 * - Return Code - Description * - FACE::NOT_AVAILABLE - |TSS| internal data could not be properly initialized. * - FACE::INVALID_CONFIG - |TSS| could not be configured with the provided configuration parameter. * - FACE::NO_ERROR - The operation completed successfully. The ``FACE::TS::Initialize`` function gets the |TSS| singleton instance and then calls the ``RTI_TSS_ConfigManager_initialize`` function to configure the TSS. The ``FACE::TS::Initialize`` call is non-blocking. This function is *not* thread safe. ---------------- Configuration ---------------- Configuration can be specified in an XML file using |CONNEXT| *Professional*. When using |CONNEXT_MICRO| (and optionally when using |CONNEXT| *Professional*), the configuration is specified statically in a user-modified plugin source file. Configuration data is used to setup Distribution Capability. The following table lists FACE TSS configuration data elements and what support (if any) is available in |TSS|. Configuration entries that are not applicable to |TSS| are listed as "Excluded". For information on QoS settings used to configure certain elements, please refer to documentation for |CONNEXT| *Professional*/*Micro* and the QoS configuration information later in this documentation. .. list-table:: Configuration Support :name: TableTSSConfigurationSupport :widths: 30 60 :header-rows: 1 * - Configuration Type - Support * - Connection Name - Supported * - Connection Type - Excluded * - Connection Direction - Supported * - Connection Domain - Excluded * - Socket Type - Excluded * - Max Message Size - Excluded (message size is derived from the data type used for a connection) * - Message Range - Excluded * - Message Association - Excluded, Not Supported * - Data Transform Required - Excluded, Not Supported * - Refresh Period - Supported via QoS Settings * - Reliability - Supported via QoS Settings * - ReadWrite Behavior - Excluded * - Queue Discipline - Excluded * - Receive Flag - Excluded * - Send Flag - Excluded * - Source - Supported via QoS Settings * - Destination - Supported via QoS Settings * - Source Port - Supported via QoS Settings * - Destination Port(s) - Supported via QoS Settings * - Filter Specification - Excluded * - Thread List - Excluded (implicitly defined for |CONNEXT|) * - Priority (per thread) - Supported via QoS Settings * - Thread Rate (per thread) - Excluded * - Thread Stack Size (per thread) - Supported via QoS Settings * - Scheduling Policy (per thread) - Excluded ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ RTI_TSS_ConfigData_get_config_data() ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ During the code generation process for FACE, an example configuration plugin is created. If you are running the code generator with an input IDL file named ``MyDataModel.idl``, a configuration file named ``MyDataModel_Config`` will be generated. The configuration plugin has a single function with the following prototype: .. code-block:: C++ RTI_TSS_ExternalConfigData* RTI_TSS_ConfigData_get_config_data(const char* config_name) .. list-table:: RTI_TSS_ConfigData_get_config_data Parameters :name: TableGetConfigDataParams :widths: 12 20 8 60 :header-rows: 1 * - Parameter Name - Type - Direction - Description * - config_name - const char* - IN - Intended to be the name of the configuration to load. The actual meaning and use of this parameter is left up to the implementer of the configuration plugin. The following C structures are used in establishing the configuration for |TSS|: .. code-block:: C typedef struct RTI_TSS_ExternalConfigDataElement { int32_t domain; const char* connection_name; FACE_CONNECTION_DIRECTION_TYPE direction_type; FACE_Boolean bi_dir_ignore_self; struct RTI_TSS_QoSConfigPlugin* qos_plugin; const char* topic_name; const char* type_name; } RTI_TSS_ExternalConfigDataElement; typedef struct RTI_TSS_ExternalConfigData { RTI_TSS_ExternalConfigDataElement* config_elements_ptr; unsigned int length; const char* url_profile; LogVerbosity verbosity; } RTI_TSS_ExternalConfigData; .. list-table:: RTI_TSS_ExternalConfigDataElement :name: TableExternalConfigDataElementFields :widths: 20 20 60 :header-rows: 1 * - Field Name - Type - Description * - domain - int32_t - The DDS domain that the connection will use for communication. An |RTI_TSS| Source and Destination will only be able to communicate if they are operating on the same domain. In practice, this logical separation may determine certain parameters for the underlying transport, such as the ports used for a network connection. See the OMG Specification for Data Distribution Service for Real-time Systems, v1.2 section 7.1.1.2.2 for information about how the domain applies to the conceptual model for DDS. * - connection_name - const char* - The name for the connection configuration. Calls to ``FACE::TS::Create_Connection`` that supply a matching value for the ``connection_name`` field will create a connection using the configuration values specified in that entry. During initialization of |RTI_TSS|, all connection names are converted to uppercase using the ctype library's ``toupper`` function on each lowercase alphabet character in the original name. * - direction_type - FACE_CONNECTION_DIRECTION_TYPE - The direction type of the TSS connection. Can be ``FACE::SOURCE`` for a sender, ``FACE::DESTINATION`` for a receiver, or ``FACE::BI_DIRECTIONAL`` for a connection that will both send and receive messages. When using ``FACE::SOURCE``, a DDS DataWriter is created for the connection. When using ``FACE::DESTINATION``, a DDS DataReader is created for the connection. When using ``FACE::BI_DIRECTIONAL``, both a DataWriter and a DataReader will be created. * - bi_dir_ignore_self - FACE_Boolean - If the connection direction is ``FACE::BI_DIRECTIONAL``, this will allow the application to ignore messages originating from the sending side of this connection. This is accomplished by using the ``DDS_DomainParticipant_ignore_publication`` function of the DDS API. **NOTE**: ``DDS_DomainParticipant_ignore_publication`` is not available in the API for |CONNEXT_MICRO|, so setting this field will have no effect on the connection. * - qos_plugin - struct RTI_TSS_QosConfigPlugin* - A pointer to a structure that will be used to set the QoS parameters for this configuration's side of the connection. Please see the section detailing the QoS plugin for additional information. **NOTE**: Each side of a connection must have QoS that is compatible with the other for communication to work. * - topic_name - const char* - The DDS Topic name that will be used for the connection. Refer to the OMG Specification for Data Distribution Service for Real-time Systems, v1.2 section 7.1.2.3, for information about Topics in DDS. **NOTE**: The name of the DDS Topic must match on both sides of a connection for communication to work. * - type_name - const char* - Connections in the RTI TSS are strongly typed. This field specifies the type name that will be used for this connection. The type support plugin provided by the application developer is responsible for ensuring that type names map to type-specific plugin code required by the underlying DDS implementation. **NOTE**: The type information must match on both sides of a connection for communication to work. .. list-table:: RTI_TSS_ExternalConfigData :name: TableExternalConfigDataFields :widths: 20 20 60 :header-rows: 1 * - Field Name - Type - Description * - config_elements_pointer - RTI_TSS_ExternalConfigDataElement* - A pointer to a table of connection configuration elements. * - length - unsigned int - The number of elements in the config_elements_pointer table. * - url_profile - const char* - URL for specifying XML QoS files. **NOTE**: This field is only used with |CONNEXT| *Professional* and is ignored when using |CONNEXT_MICRO|. * - verbosity - LogVerbosity - An enumerated value indicating the verbosity of log messages from the TSS. ^^^^^^^^^^^^^^^^^^^^^^^ RTI_TSS_QoSConfigPlugin ^^^^^^^^^^^^^^^^^^^^^^^ During the code generation process for FACE, an example quality of service (QoS) plugin is created. If you are running the code generator with an input IDL file named ``MyDataModel.idl``, a configuration file named ``MyDataModel_QosSupport.c`` will be generated. The QoS plugin allows for the implementation of functions for setting quality of service for each of the DDS entities that will be used by the TSS. It also provides a function to retrieve the structure of function pointers to the entity QoS configuration functions. The structure to be provided by the QoS plugin is below: .. code-block:: C typedef struct RTI_TSS_QoSConfigPlugin { DDS_Boolean (*configure_domain_participant_qos_fnc)(struct DDS_DomainParticipantQos*, void*); DDS_Boolean (*configure_publisher_qos_fnc)(struct DDS_PublisherQos*, void*); DDS_Boolean (*configure_subscriber_qos_fnc)(struct DDS_SubscriberQos*, void*); DDS_Boolean (*configure_topic_qos_fnc)(struct DDS_TopicQos*, void*); DDS_Boolean (*configure_datawriter_qos_fnc)(struct DDS_DataWriterQos*, void*); DDS_Boolean (*configure_datareader_qos_fnc)(struct DDS_DataReaderQos*, void*); void* plugin_data; const char* qos_library; const char* qos_profile; } RTI_TSS_QoSConfigPlugin; .. list-table:: RTI_TSS_QosConfigPlugin :name: TableQosConfigPluginFields :widths: 20 20 60 :header-rows: 1 * - Field Name - Type - Description * - configure_domain_participant_qos_fnc - DDS_Boolean (*fnc_ptr) (struct DDS_DomainParticipantQos*, void*) - A function for configuring the QoS of a DDS Domain Participant entity. If NULL, QoS will be set to a default value set for the entity. **NOTE**: There is no default QoS function when building an application aligned to the FACE TSS Safety Base Profile. All QoS values for a profile should be set explicitly in the plugin. * - configure_publisher_qos_fnc - DDS_Boolean (*fnc_ptr) (struct DDS_PublisherQos*, void*) - A function for configuring the QoS of a DDS Publisher entity. If NULL, QoS will be set to a default value set for the entity. **NOTE**: There is no default QoS function when building an application aligned to the FACE TSS Safety Base Profile. All QoS values for a profile should be set explicitly in the plugin. * - configure_subscriber_qos_fnc - DDS_Boolean (*fnc_ptr) (struct DDS_SubscriberQos*, void*) - A function for configuring the QoS of a DDS Subscriber entity. If NULL, QoS will be set to a default value set for the entity. **NOTE**: There is no default QoS function when building an application aligned to the FACE TSS Safety Base Profile. All QoS values for a profile should be set explicitly in the plugin. * - configure_topic_qos_fnc - DDS_Boolean (*fnc_ptr) (struct DDS_TopicQos*, void*) - A function for configuring the QoS of a DDS Topic entity. If NULL, QoS will be set to a default value set for the entity. **NOTE**: There is no default QoS function when building an application aligned to the FACE TSS Safety Base Profile. All QoS values for a profile should be set explicitly in the plugin. * - configure_datawriter_qos_fnc - DDS_Boolean (*fnc_ptr) (struct DDS_DataWriterQos*, void*) - A function for configuring the QoS of a DDS DataWriter entity. If NULL, QoS will be set to a default value set for the entity. **NOTE**: There is no default QoS function when building an application aligned to the FACE TSS Safety Base Profile. All QoS values for a profile should be set explicitly in the plugin. * - configure_datareader_qos_fnc - DDS_Boolean (*fnc_ptr) (struct DDS_DataReaderQos*, void*) - A function for configuring the QoS of a DDS DataReader entity. If NULL, QoS will be set to a default value set for the entity. **NOTE**: There is no default QoS function when building an application aligned to the FACE TSS Safety Base Profile. All QoS values for a profile should be set explicitly in the plugin. * - plugin_data - void* - An opaque user-defined data field that will be passed to each of the entity QoS configuration function pointers. * - qos_library - const char* - The QoS Library for built-in or XML-defined QoS that will be used to configure the entities created by any connections using this plugin. Can be NULL if external configuration will not be used. **NOTE**: This field is ignored for applications using |CONNEXT_MICRO|. * - qos_profile - const char* - The QoS Profile for built-in or XML-defined QoS that will be used to configure the entities created by any connections using this plugin. Can be NULL if external configuration will not be used. **NOTE**: This field is ignored for applications using |CONNEXT_MICRO|. The example QoS plugin source file that is created by the code generator contains a function that returns a structure of type ``RTI_TSS_QoSConfigPlugin*``, which can then be used to initialize the ``qos_plugin`` field for a connection configuration. Multiple QoS configuration structures can be used within a single application to enable tuning of message distribution capabilities to different use-cases. Please refer to documentation for the underlying DDS implementation (|CONNEXT| *Professional* or *Micro*) to learn more about the QoS configuration options available for each entity. ^^^^^^^^^^^^^^^^^ XML Configuration ^^^^^^^^^^^^^^^^^ XML Configuration is available for applications using |CONNEXT| *Professional*. Below is an example XML configuration file: .. code-block: XML My_Qos.xml INFO 0 FACE_SOURCE true MyQosLibrary::FooProfile Foo FACE::DM::Foo 0 FACE_DESTINATION MyQosLibrary::BarProfile Bar FACE::DM::Bar For setting QoS via XML configuration, please refer to |CONNEXT| *Professional* documentation. ------------ Connections ------------ Application developers using |TSS| can configure connections by populating a connection table in the configuration plugin source code or by using XML configuration (the latter being available only when targeting |CONNEXT| *Professional*). .. _API_create_conn: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ FACE::TS::Create_Connection() ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A connection is created with ``FACE::TS::Create_Connection``. .. code-block:: C++ void FACE::TS::Create_Connection ( /* in */ const FACE::CONNECTION_NAME_TYPE connection_name, /* in */ FACE::MESSAGING_PATTERN_TYPE pattern, /* out */ FACE::CONNECTION_ID_TYPE &connection_id, /* out */ FACE::CONNECTION_DIRECTION_TYPE &connection_direction, /* out */ FACE::MESSAGE_SIZE_TYPE &max_message_size, /* in */ FACE::TIMEOUT_TYPE timeout, /* out */ FACE::RETURN_CODE_TYPE &return_code ) .. list-table:: FACE::TS::Create_Connection Parameters :name: TableFACETSCreateConnectionParams :widths: 12 20 8 60 :header-rows: 1 * - Parameter Name - Type - Direction - Description * - connection_name - const FACE::CONNECTION_NAME_TYPE - IN - The name of the connection. This value will be converted to uppercase to search against the connections specified in the configuration table for connections. * - pattern - FACE::MESSAGING_PATTERN_TYPE - IN - The pattern to use for communication. Only ``FACE::PUB_SUB`` is supported for |TSS|. * - connection_id - FACE::CONNECTION_ID_TYPE& - OUT - A unique connection ID. This ID will be used to refer to the connection in all other TSS API calls. This field is passed by reference and is set upon return from a successful call. * - connection_direction - FACE::CONNECTION_DIRECTION_TYPE& - OUT - The direction of the connection that corresponds to the configuration with a matching name. This field is passed by reference and is set upon return from a successful call. * - max_message_size - FACE::MESSAGE_SIZE_TYPE& - OUT - The maximum size of a message for this connection. This field is passed by reference and is set upon return from a successful call. **NOTE**: This parameter is not supported by RTI TSS and consequently is set to 0. * - timeout - FACE::TIMEOUT_TYPE - IN - Specifies a timeout for connection creation. **NOTE**: This parameter is not used by the RTI TSS. * - return_code - FACE::RETURN_CODE_TYPE& - OUT - The return code for the call to ``FACE::TS::Create_Connection``. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure. .. list-table:: FACE::TS::Create_Connection Return Codes :name: TableFACETSCreateConnectionRetCodes :widths: 40 60 :header-rows: 1 * - Return Code - Description * - FACE::NOT_AVAILABLE - |TSS| was not properly initialized prior to the call to ``FACE::TS::Create_Connection``. * - FACE::INVALID_MODE - The pattern parameter was not specified as ``FACE::PUB_SUB``, as required by |TSS|. * - FACE::INVALID_PARAM - A configuration with a name matching the provided ``connection_name`` parameter was not found. **NOTE**: Because both strings will have been converted to uppercase prior to the matching process, the matching is case-insensitive, as required by the FACE TSS specification. * - FACE::INVALID_CONFIG - |TSS| was unable to create the connection due to an invalid configuration. * - FACE::NO_ERROR - The operation completed successfully. The call to ``FACE::TS::Create_Connection`` first verifies that |TSS| was properly initialized. It then converts the supplied ``connection_name`` parameter to uppercase to perform a case-insensitive lookup of the connection configuration associated with the name. If that succeeds and a connection has not already been created for that name, one will be created and a new connection ID will be assigned. If a connection for that name already exists, the parameters for the existing connection are returned. When a new connection is created, the appropriate DDS entities for that connection are also created if necessary, as explained in the following table. .. list-table:: DDS Entity Creation :name: TableConnectionDDSEntityCreation :widths: 20 80 :header-rows: 1 * - DDS Entity - Creation Requirements * - DomainParticipant - Created if there is no existing DomainParticipant for the new connection's configured ``domain`` parameter. Otherwise the existing DomainParticipant on that domain will be reused by the new connection. See the OMG Specification for Data Distribution Service for Real-time Systems, v1.2 section 7.1.2.2.1, for information on the DomainParticipant entity class. **NOTE**: DomainParticipant reuse does not allow for new connections to modify DomainParticipant QoS after the initial creation of the DomainParticipant. Any connection created with the same domain as an existing connection will use the DomainParticipant QoS of the original connection, regardless of the QoS plugin specified for the new connection. * - Topic - Created if there is no existing Topic matching the new connection's topic name in the connection configuration. Otherwise the existing Topic will be reused by the new connection. See the OMG Specification for Data Distribution Service for Real-time Systems, v1.2 section 7.1.2.3.2, for information on the Topic entity class. **NOTE**: Topic reuse does not allow for connections to modify Topic QoS after the initial creation of the Topic. Any connection created with the same topic name as an existing connection will use the Topic QoS of the original connection, regardless of the QoS plugin specified for the new connection. * - Publisher - Created if the connection is of direction ``FACE::SOURCE`` or ``FACE::BI_DIRECTIONAL``. See the OMG Specification for Data Distribution Service for Real-time Systems, v1.2 section 7.1.2.4.1, for information on the Publisher entity class. **NOTE**: Although DDS allows for Publishers to contain multiple DataWriters, in |TSS| Publishers are not shared by connections. * - Subscriber - Created if the connection is of direction ``FACE::DESTINATION`` or ``FACE::BI_DIRECTIONAL``. See the OMG Specification for Data Distribution Service for Real-time Systems, v1.2 section 7.1.2.5.2, for information on the Subscriber entity class. **NOTE**: Although DDS allows for Subscribers to contain multiple DataReaders, in |TSS| Subscribers are not shared by connections. * - DataWriter - Created if the connection is of direction ``FACE::SOURCE`` or ``FACE::BI_DIRECTIONAL``. See the OMG Specification for Data Distribution Service for Real-time Systems, v1.2 section 7.1.2.4.2, for information on the DataWriter entity class. * - DataReader - Created if the connection is of direction ``FACE::DESTINATION`` or ``FACE::BI_DIRECTIONAL``. See the OMG Specification for Data Distribution Service for Real-time Systems, v1.2 section 7.1.2.5.3, for information on the DataReader entity class. The ``FACE::TS::Create_Connection`` call is non-blocking. This function is *not* thread safe. .. _API_destroy_conn: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ FACE::TS::Destroy_Connection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: C++ void FACE::TS::Destroy_Connection ( /* in */ FACE::CONNECTION_ID_TYPE connection_id, /* out */ FACE::RETURN_CODE_TYPE &return_code ) .. list-table:: FACE::TS::Destroy_Connection Parameters :name: TableFACETSDestroyConnectionParams :widths: 12 20 8 60 :header-rows: 1 * - Parameter Name - Type - Direction - Description * - connection_id - FACE::CONNECTION_ID_TYPE - IN - The ID of the connection to be destroyed. * - return_code - FACE::RETURN_CODE_TYPE& - OUT - The return code for the call to ``FACE::TS::Destroy_Connection``. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure. .. list-table:: FACE::TS::Destroy_Connection Return Codes :name: TableFACETSDestroyConnectionRetCodes :widths: 40 60 :header-rows: 1 * - Return Code - Description * - FACE::NOT_AVAILABLE - |TSS| was not properly initialized prior to the call to ``FACE::TS::Destroy_Connection``. * - FACE::NO_ERROR - The operation completed successfully. The call to ``FACE::TS::Destroy_Connection`` first verifies that the RTI TSS was properly initialized. It then looks up the connection using the provided ID. If a matching connection is found, it is removed from the lookup table and the following checks and operations are performed: - If the direction is ``FACE::DESTINATION`` or ``FACE::BI_DIRECTIONAL`` - Destroy the DDS WaitSet associated with the connection using ``DDS_WaitSet_delete()`` - If the application was using the callback interface - Destroy any internal instances of sample data using the generated type plugin - Remove the listener associated with the DDS DataReader using ``DDS_DataReader_set_listener()`` - Destroy the DDS DataReader associated with the connection using ``DDS_Subscriber_delete_datareader()`` - Destroy the DDS Subscriber associated with the connection using ``DDS_DomainParticipant_delete_subscriber()`` - If the direction is ``FACE::SOURCE`` or ``FACE::BI_DIRECTIONAL`` - Destroy the DDS DataWriter associated with the connection using ``DDS_Publisher_delete_datawriter()`` - Destroy the DDS Publisher associated with the connection using ``DDS_DomainParticipant_delete_publisher()`` - Check to see if any entities are still referencing the DDS Topic used for this connection - If not, delete the DDS Topic using ``DDS_DomainParticipant_delete_topic()`` - Check to see if any references to the DDS DomainParticipant remain - If not, delete all entities in the DDS Participant using ``DDS_DomainParticipant_delete_contained_entities and then delete the participant itself using ``DDS_DomainParticipantFactory_delete_participant()`` **NOTE**: ``FACE::TS::Destroy_Connection`` does not delete the entities and remove the references to the connection when building for the Safety Base profile. These calls require the ability to free the memory associated with DDS entities and the ``free()`` call is not available in this profile. This function is *not* thread safe. .. _API_get_conn_params: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ FACE::TS::Get_Connection_Parameters() ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: C++ void FACE::TS::Get_Connection_Parameters ( /* inout */ FACE::CONNECTION_NAME_TYPE &connection_name, /* inout */ FACE::CONNECTION_ID_TYPE &connection_id, /* out */ FACE::TRANSPORT_CONNECTION_STATUS_TYPE &connection_status, /* out */ FACE::RETURN_CODE_TYPE &return_code ) .. list-table:: FACE::TS::Get_Connection_Parameters Parameters :name: TableFACETSGetConParamsParams :widths: 12 20 8 60 :header-rows: 1 * - Parameter Name - Type - Direction - Description * - connection_name - FACE::CONNECTION_NAME_TYPE& - INOUT - The name of the connection. **NOTE**: Not used by the RTI TSS. Use the ``connection_id`` field instead. * - connection_id - FACE::CONNECTION_ID_TYPE& - INOUT - The ID of the connection. * - connection_status - FACE::TRANSPORT_CONNECTION_STATUS_TYPE& - OUT - Connection status. * - return_code - FACE::RETURN_CODE_TYPE& - OUT - The return code for the call to ``FACE::TS::Get_Connection_Parameters``. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure. .. list-table:: FACE::TS::Get_Connection_Parameters Return Codes :name: TableFACETSGetConnParamsRetCodes :widths: 40 60 :header-rows: 1 * - Return Code - Description * - FACE::NOT_AVAILABLE - |TSS| was not properly initialized prior to the call to ``FACE::TS::Get_Connection_Parameters``. * - FACE::INVALID_PARAM - No connection with the associated ID was found. * - FACE::NO_ERROR - The operation completed successfully. The call to ``FACE::TS::Get_Connection_Parameters`` first verifies that the RTI TSS was properly initialized. It then looks up the connection using the provided ID. If one is found, information related to the connection is returned via the ``connection_status`` reference field. NOTE: Currently only the connection direction is populated with valid information. This function is *not* thread safe. ---------------- Communication ---------------- .. _API_send_msg: ^^^^^^^^^^^^^^^^^^^^^^^^^ FACE::TS::Send_Message() ^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: C++ void FACE::TS::Send_Message ( /* in */ FACE::CONNECTION_ID_TYPE connection_id, /* in */ FACE::TIMEOUT_TYPE timeout, /* inout */ FACE::TRANSACTION_ID_TYPE &transaction_id, /* inout */ FACE_SPECIFIED_TYPE &message, /* inout */ FACE::MESSAGE_SIZE_TYPE &message_size, /* out */ FACE::RETURN_CODE_TYPE &return_code ) .. list-table:: FACE::TS::Send_Message Parameters :name: TableFACETSSendMessageParams :widths: 12 20 8 60 :header-rows: 1 * - Parameter Name - Type - Direction - Description * - connection_id - FACE::CONNECTION_ID_TYPE - IN - The ID of the connection to be used for sending the message. This ID is returned via a successful call to ``FACE::TS::Create_Connection``. * - timeout - FACE::TIMEOUT_TYPE - IN - The ``timeout`` parameter is not used by |TSS|. * - transaction_id - FACE::TRANSACTION_ID_TYPE& - INOUT - The ``transaction_id`` parameter is used in the request/reply communication pattern, which is not currently available in |TSS|. * - message - FACE_SPECIFIED_TYPE - INOUT - The strongly typed message to be sent. An implementer will substitute their type for ``FACE_SPECIFIED_TYPE``. **NOTE**: The type of the message must correspond to the type specified in the connection configuration for the given ``connection_id``. * - message_size - FACE::MESSAGE_SIZE_TYPE& - INOUT - The size of the message being sent. **NOTE**: Since this parameter is used for abstract sends (e.g., ``void*`` type) and this implementation only supports strongly typed communication, this parameter is not used by |TSS|. * - return_code - FACE::RETURN_CODE_TYPE& - OUT - The return code for the call to ``FACE::TS::Send_Message``. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure. .. list-table:: FACE::TS::Send_Message Return Codes :name: TableFACETSSendMsgRetCodes :widths: 40 60 :header-rows: 1 * - Return Code - Description * - FACE::NOT_AVAILABLE - |TSS| was not properly initialized prior to the call to ``FACE::TS::Send_Message``. * - FACE::INVALID_PARAM - The provided ``connection_id`` parameter does not correspond to an active connection or the DDS DataWriter's write call returned an error. * - FACE::INVALID_MODE - The connection associated with the ``connection_id`` is of direction ``FACE::DESTINATION``. ``FACE::TS::Send_Message`` only works with connections using direction ``FACE::SOURCE`` or ``FACE::BI_DIRECTIONAL``. * - FACE::INVALID_CONFIG - The DDS DataWriter associated with the ``connection_id`` parameter was not initialized successfully or does not match the type associated with the FACE Connection configuration. * - FACE::NO_ERROR - The operation completed successfully. The ``Send_Message`` API first checks to ensure that the TSS has been properly initialized with a call to ``FACE::TS::Initialize``. It then verifies that the Connection corresponding to the provided ``connection_id`` parameter was previously created and that the Connection can be used to send data by confirming that the ``direction_type`` is either ``FACE::SOURCE`` or ``FACE::BI_DIRECTIONAL``. The FACE Connection is mapped to a DDS Topic and a type-specific DDS DataWriter. The RTI TSS obtains the type specific DataWriter and calls the ``write()`` API. This function is *not* thread safe. .. _API_recv_msg: ^^^^^^^^^^^^^^^^^^^^^^^^^^^ FACE::TS::Receive_Message() ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: C++ void FACE::TS::Receive_Message ( /* in */ FACE::CONNECTION_ID_TYPE connection_id, /* in */ FACE::TIMEOUT_TYPE timeout, /* inout */ FACE::TRANSACTION_ID_TYPE &transaction_id, /* inout */ FACE_SPECIFIED_TYPE &message, /* in */ FACE::MESSAGE_SIZE_TYPE message_size, /* out */ FACE::RETURN_CODE_TYPE &return_code ) .. list-table:: FACE::TS::Receive_Message Parameters :name: TableFACETSReceiveMessageParams :widths: 12 20 8 60 :header-rows: 1 * - Parameter Name - Type - Direction - Description * - connection_id - FACE::CONNECTION_ID_TYPE - IN - The ID of the connection to be used for receiving the message. This ID is returned via a successful call to ``FACE::TS::Create_Connection``. * - timeout - FACE::TIMEOUT_TYPE - IN - The amount of time to wait for an incoming message before returning to the calling application with a return code indicating the call has timed out. * - transaction_id - FACE::TRANSACTION_ID_TYPE& - INOUT - The ``transaction_id`` parameter is used in the request/reply communication pattern, which is not currently available in |TSS|. * - message - FACE_SPECIFIED_TYPE - INOUT - The strongly typed message to be received. An implementer will substitute their type for ``FACE_SPECIFIED_TYPE``. **NOTE**: The type of the message must correspond to the type specified in the connection configuration for the given ``connection_id``. * - message_size - FACE::MESSAGE_SIZE_TYPE& - INOUT - The size of the message to be received. **NOTE**: Since this parameter is used for abstract receives (e.g., ``void*`` type) and this implementation only supports strongly typed communication, this parameter is not used by |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. .. list-table:: FACE::TS::Receive_Message Return Codes :name: TableFACETSReceiveMsgRetCodes :widths: 40 60 :header-rows: 1 * - Return Code - Description * - FACE::NOT_AVAILABLE - |TSS| was not properly initialized prior to the call to ``FACE::TS::Receive_Message`` or no data was received. * - FACE::INVALID_PARAM - The provided ``connection_id`` parameter does not correspond to an active connection or the timeout value is invalid. * - FACE::INVALID_MODE - The connection associated with the ``connection_id`` is of direction ``FACE::SOURCE``. ``FACE::TS::Receive_Message`` only works with connections using direction ``FACE::DESTINATION`` or ``FACE::BI_DIRECTIONAL``. * - FACE::INVALID_CONFIG - The DDS Participant, DDS WaitSet, or DDS DataReader associated with the ``connection_id`` parameter was not initialized successfully or the DDS DataReader does not match the type associated with the FACE Connection configuration. * - FACE::TIMED_OUT - The call to ``FACE::TS::Receive_Message`` timed out before any data was received on the connection. * - FACE::NO_ERROR - The operation completed successfully. The ``Receive_Message`` API verifies the following before performing the operations to receive data: - The TSS has been properly initialized with a call to ``FACE::TS::Initialize``. - The Connection corresponding to the provided ``connection_id`` parameter was previously created. - The timeout parameter is valid. - The DDS Participant associated with the ``connection_id`` parameter is valid. - The DDS WaitSet associated with the ``connection_id`` parameter is valid. - The Connection can be used to receive data by confirming the ``direction_type`` is either ``FACE::DESTINATION`` or ``FACE::BI_DIRECTIONAL``. - The type-specific DDS DataReader associated with the ``connection_id`` is valid and the type matches the type associated with the ``Receive_Message`` call. It then performs a DDS ``take_next_sample()`` call to attempt retrieval of a sample already at the DataReader. If a sample is available, it is returned via the message reference parameter. Otherwise the DDS ``wait()`` call is performed on the DDS WaitSet associated with the connection with the provided timeout parameter. If a sample is received within the timeout period, it is retrieved using the ``take_next_sample()`` call for the DataReader and returned via the message reference parameter. This function is *not* thread safe. ------------------- Callback Interface ------------------- The FACE TSS callback interface is *only* available when using the General Purpose or Safety Extended FACE Profiles. It allows for asynchronous communication patterns. .. _API_send_event: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ FACE::Read_Callback::send_event() ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The optional FACE TSS callback interface for receiving data specifies the following type-specific function prototype for type ``FACE_SPECIFIED_TYPE``. It is generated from a user-defined IDL data type: .. code-block:: C++ void FACE::Read_Callback::send_event( /* in */ FACE::TRANSACTION_ID_TYPE transaction_id, /* inout */ FACE_SPECIFIED_TYPE &message, /* in */ FACE::MESSAGE_TYPE_GUID message_type_id, /* in */ FACE::MESSAGE_SIZE_TYPE message_size, /* in */ const FACE::WAITSET_TYPE waitset, /* out */ FACE::RETURN_CODE_TYPE &return_code ); This function is a user-defined handler for receiving data via the callback interface. The parameters passed to the function upon receipt of data are listed in the following table: .. list-table:: FACE::Read_Callback:send_event Parameters :name: TableFACECallbackSendEventParams :widths: 12 20 8 60 :header-rows: 1 * - Parameter Name - Type - Direction - Description * - transaction_id - FACE::TRANSACTION_ID_TYPE - IN - The ``transaction_id`` parameter is used in the request/reply communication pattern, which is not currently available in |TSS|. * - message - FACE_SPECIFIED_TYPE& - INOUT - The strongly typed message that was received. An implementer will substitute their type for ``FACE_SPECIFIED_TYPE``. **NOTE**: The type of the message must correspond to the type specified in the connection configuration for the given ``connection_id``. * - message_type_id - FACE::MESSAGE_TYPE_GUID - IN - The type of the message that was received. **NOTE**: Since this parameter is used for abstract receives (e.g., ``void*`` type) and this implementation only supports strongly typed communication, this parameter is not used by |TSS|. * - message_size - FACE::MESSAGE_SIZE_TYPE - IN - The size of the message that was received. **NOTE**: Since this parameter is used for abstract sends (e.g., ``void*`` type) and this implementation only supports strongly typed communication, this parameter is not used by |TSS|. * - waitset - const FACE::WAITSET_TYPE - IN - * - return_code - FACE::RETURN_CODE_TYPE& - OUT - The return code for the call to ``FACE::TS::Receive_Message``. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure. .. _API_reg_call: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ FACE::TS::Register_Callback() ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For each message type, there is a type-specific function for registering a callback with the TSS with the following signature: .. code-block:: C++ void FACE::TS::Register_Callback ( /* in */ FACE::CONNECTION_ID_TYPE connection_id, /* in */ const FACE::WAITSET_TYPE waitset, /* in */ FACE::Read_Callback::send_event data_callback, /* in */ FACE::MESSAGE_SIZE_TYPE max_message_size, /* out */ FACE::RETURN_CODE_TYPE &return_code ); .. list-table:: FACE::TS:Register_Callback Parameters :name: TableFACETSRegCallbackParams :widths: 12 20 8 60 :header-rows: 1 * - Parameter Name - Type - Direction - Description * - connection_id - FACE::CONNECTION_ID_TYPE - IN - The ID of the connection on which the messages shall be received. This ID is returned via a successful call to ``FACE::TS::Create_Connection``. * - waitset - const FACE::WAITSET_TYPE - IN - This parameter is not used by |TSS|. * - data_callback - FACE::Read_Callback::send_event - IN - The user-defined callback function to invoke whenever data is received on the connection. * - max_message_size - FACE::MESSAGE_SIZE_TYPE - IN - The size of the message that can be received. **NOTE**: Since this parameter is used for abstract receives (e.g., ``void*`` type) and this implementation only supports strongly typed communication, this parameter is not used by |TSS|. * - return_code - FACE::RETURN_CODE_TYPE& - OUT - The return code for the call to ``FACE::TS::Register_Callback``. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure. .. list-table:: FACE::TS::Register_Callback Return Codes :name: TableFACETSRegCallbackRetCodes :widths: 40 60 :header-rows: 1 * - Return Code - Description * - FACE::NOT_AVAILABLE - |TSS| was not properly initialized prior to the call to ``FACE::TS::Receive_Message`` or no data was received. * - FACE::INVALID_PARAM - The provided ``connection_id`` parameter does not correspond to an active connection or the ``data_callback`` parameter is invalid. The ``Register_Callback`` API verifies the following before registering the callback function with the TSS: - The TSS has been properly initialized with a call to ``FACE::TS::Initialize``. - The Connection corresponding to the provided ``connection_id`` parameter was previously created. - The ``data_callback`` parameter and the DDS DataReader associated with the connection are not NULL. If the callback entry does not exist for the specified connection, it is created dynamically and initialized. Once the callback entry has been successfully created, it is updated and activated with the new callback function. Internally, when a callback is registered with the FACE TSS, it is configured to be called by a DDS Listener function that is attached to the DDS DataReader associated with the connection. The event mask is modified to include ``ON_DATA_AVAILABLE``, which will cause the DDS Listener handler for incoming data to be invoked. When the DDS Listener is invoked, it will attempt to read available samples using the DDS type-specific function ``take_next_sample()``. For each sample it takes, the handler will call the function specified by the ``data_callback`` parameter in the call to ``FACE::TSS::Register_Callback``. This function is *not* thread safe. .. _API_unreg_call: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ FACE::TS::Unregister_Callback() ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``FACE::TS::Unregister_Callback`` function removes a previously registered callback from a connection. .. code-block:: C++ void FACE::TS::Unregister_Callback ( /* in */ FACE::CONNECTION_ID_TYPE connection_id, /* out */ FACE::RETURN_CODE_TYPE &return_code ); .. list-table:: FACE::TS:Unregister_Callback Parameters :name: TableFACETSUnregCallbackParams :widths: 12 20 8 60 :header-rows: 1 * - Parameter Name - Type - Direction - Description * - connection_id - FACE::CONNECTION_ID_TYPE - IN - The ID of the connection with the callback that will be unregistered. * - return_code - FACE::RETURN_CODE_TYPE& - OUT - The return code for the call to ``FACE::TS::Unregister_Callback``. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure. .. list-table:: FACE::TS::Unregister_Callback Return Codes :name: TableFACETSUnregCallbackRetCodes :widths: 40 60 :header-rows: 1 * - Return Code - Description * - FACE::NOT_AVAILABLE - The RTI TSS was not properly initialized prior to the call to ``FACE::TS::Receive_Message`` or no data was received. * - FACE::INVALID_PARAM - The call failed to unregister a callback on a connection with the provided ID. This could be the result of an invalid ID or that no callback was associated with the connection. * - FACE::INVALID_PARAM - The provided ``connection_id`` parameter does not correspond to an active connection or the ``data_callback`` parameter is invalid. The ``Unregister_Callback`` API verifies the following before registering the callback function with the TSS: - The TSS has been properly initialized with a call to ``FACE::TS::Initialize``. - The Connection corresponding to the provided ``connection_id`` parameter was previously created. If a callback has been registered for the connection, it is removed by using the ``DDS_DataReader_set_listener()`` call and the associated dynamically allocated callback structure is freed. This function is *not* thread safe. ------- Logging ------- |TSS| provides a logging mechanism that can be used by applications using |TSS| headers and linking against the |TSS| libraries. The logging header is in ``log/ext_log.h`` and exposes the following macros for logging: .. code-block:: C++ #define Logger_error(logger, methodName, ...) #define Logger_warning(logger, methodName, ...) #define Logger_info(logger, methodName, ...) Each of these macros takes a ``struct Logger*`` as the first parameter, which can be obtained as a singleton for the application using: .. code-block:: C++ struct Logger * Logger_getInstance(); Messages can be logged using the macros which offer usage similar to an ``fprintf()`` call. .. code-block:: C++ Logger_error(rti_tss->logger, THIS_METHOD_NAME, "Unable to register callback for connection id (%llu)", connection_id); The logging output behavior is configured at the time of the |TSS| build. Support is available for writing to STDOUT, a user-defined file, or a timestamp-named file. Logging can also be disabled. All log writing is done using the POSIX ``write()`` API. The logger is not thread safe.