.. include:: vars.rst .. _section-api_reference: ******************************************************************************** API Reference ******************************************************************************** .. note:: This API Reference for |RTI_TSS| contains examples and is easier for a beginner to use. However, |TSS| also comes bundled with a separate `TSS API Reference <../api/index.html>`_ with only the functions and parameters defined. Both API References are complete and up-to-date. -------------------------------------------- TSS Type-Specific Base and Typed Interfaces -------------------------------------------- |TSS| implements the FACE TSS Type-Specific Base and Typed interfaces in the C++ programming language as the RTI::TSS::Base class. RTI::TSS::Base also implements the FACE Configuration Injectable interface for |TSS| configuration. For applications requiring all resources to be allocated and configured during an intialization phase, an extended function pf RTI::TSS::Base, Enable_DDS_Entities(), allows |TSS| users first to create disabled DDS entities during initialization and then to enable them after initialization. - :ref:`Set_Reference (Configuration) ` - :ref:`Initialize (Base TS) Function ` - :ref:`Create_Connection (Base TS) Function ` - :ref:`Enable_DDS_Entities (RTI) ` - :ref:`Destroy_Connection (Base TS) Function ` - :ref:`Send_Message (Typed TS) ` - :ref:`Receive_Message (Typed TS) Function ` - :ref:`Register_Callback (Typed TS) ` - :ref:`Callback_Handler (Typed TS) Function ` - :ref:`Unregister_Callback (Base TS) Function ` -------- Headers -------- Include these header files to allow your application to call the FACE TSS APIs implemented by the RTI FACE TSS library. - ``RTI/TSS/Base.hpp`` defines the |TSS| implementation of the FACE TSS Type-Specific Base interface. - Given a user datatype, once the RTI FACE TSS library has been built and the rtiddsgen tool has been run, the generated header file ``//TypedTS.hpp`` defines the FACE TSS Type-Specific Typed interface for the user datatype, and the generated header file ``//TypedTS_Impl.hpp`` defines the implementation of that interface. For a reference on including headers, see the example application(s) in the ``examples`` directory. --------------------------------------- Initialization --------------------------------------- .. _API_cfg_setref: ^^^^^^^^^^^^^^^^^^^^^^ Set_Reference() ^^^^^^^^^^^^^^^^^^^^^^ A new Base instance must set its reference to a Configuration Interface before the Base is initialized. .. code-block:: C++ 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); ) .. list-table:: FACE::Configuration_Injectable::Set_Reference Parameters :name: TableFACETSSBaseSetRefParams :widths: 12 20 8 60 :header-rows: 1 * - Parameter Name - Type - Direction - Description * - interface_name - const FACE::STRING_TYPE - IN - Unused by |TSS| |br| * - interface_reference - const FACE::Configuration - IN - A reference to an FACE Configuration instance for |TSS|. * - id - const FACE::GUID_TYPE - OUT - Unused by |TSS| |br| * - return_code - FACE::RETURN_CODE_TYPE - OUT - The return code for the call to ``Set_Reference(Base)``. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure. .. list-table:: FACE::Configuration_Injectable::Set_Reference Return Codes :name: TableFACETSSBaseSetRefRetCodes :widths: 40 60 :header-rows: 1 * - Return Code - Description * - FACE::NO_ERROR - The operation completed successfully. * - FACE::NO_ACTION - A configuration reference was previously set successfully. The ``Set_Reference`` function sets the FACE Configuration instance that a Base instance will use to configure the TSS connections it will create, as well as the underlying DDS. The ``interface_reference`` must be a configured instance of RTI::Configuration implementing the FACE 3.x Configuration interface. For help in creating and setting the configuration data in the configuration interface, see :ref:`Configuration Interface `. The ``Set_Reference`` function is non-blocking. This function is *not* thread safe. .. _API_init: ^^^^^^^^^^^^^^^^^^^^^^ Initialize() ^^^^^^^^^^^^^^^^^^^^^^ Once the Configuration interface reference is set, the TSS is initialized by calling the Base interface ``Initialize(TS)`` function. .. code-block:: C++ void Initialize ( /* in */ const FACE::CONFIGURATION_RESOURCE &configuration, /* out */ FACE::RETURN_CODE_TYPE::Value &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. Passed to the Configuration Interface's Initialize() member function. |br| NOTE: Configuration files are only available when using |CONNEXT| *Professional* with the General Purpose Profile. * - return_code - FACE::RETURN_CODE_TYPE& - OUT - The return code for the call to ``Initialize(TS)``. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure. .. list-table:: FACE::TS::Initialize Return Codes :name: TableFACETSInitializeRetCodes :widths: 40 60 :header-rows: 1 * - Return Code - Description * - FACE::NO_ERROR - The operation completed successfully. * - FACE::NO_ACTION - |TSS| was successfully initialized previously. * - FACE::NOT_AVAILABLE - |TSS| internal data could not be properly initialized. * - FACE::INVALID_CONFIG - |TSS| could not be configured with the provided configuration parameter. The ``Initialize(TS)`` function will initialize |TSS| and its supporting DDS with configuration data from its set configuration interface. It will load the system configuration the first time it is called, idempotently. The ``Initialize(TS)`` function is non-blocking. This function is *not* thread safe. ------------ Connections ------------ .. _API_create_conn: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Create_Connection() ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A connection is created with the RTI::TSS::Base ``Create_Connection`` function. .. code-block:: C++ 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 ) .. list-table:: FACE::TSS::Create_Connection Parameters :name: TableFACETSCreateConnectionParams :widths: 12 20 8 60 :header-rows: 1 * - Parameter Name - Type - Direction - Description * - connection_name - const FACE::TSS::CONNECTION_NAME_TYPE - IN - The name of the connection to create. Must match the name (case-insensitive) of a connection in configuration data. * - timeout - FACE::TIMEOUT_TYPE - IN - Specifies a timeout for connection creation. **NOTE**: This parameter is not used by the RTI TSS. * - connection_id - FACE::CONNECTION_ID_TYPE - OUT - A unique connection ID. This ID will be used to refer to the connection in all other TSS API calls. This field is passed by reference and is set upon return from a successful call. * - max_message_size - FACE::TSS::MESSAGE_SIZE_TYPE - OUT - The maximum size of a message for this connection. This field is passed by reference and is set upon return from a successful call. **NOTE**: This parameter is not supported by RTI TSS and consequently is set to 0. * - return_code - FACE::RETURN_CODE_TYPE - OUT - The return code for the call to ``FACE::TS::Create_Connection``. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure. .. list-table:: FACE::TS::Create_Connection Return Codes :name: TableFACETSCreateConnectionRetCodes :widths: 40 60 :header-rows: 1 * - Return Code - Description * - FACE::NO_ERROR - The operation completed successfully. * - FACE::NOT_AVAILABLE - |TSS| was not properly initialized prior to the call to ``FACE::TS::Create_Connection``. * - FACE::INVALID_PARAM - A configuration with a name matching the provided ``connection_name`` parameter was not found. **NOTE**: Because both strings will have been converted to uppercase prior to the matching process, the matching is case-insensitive, as required by the FACE TSS specification. * - FACE::INVALID_CONFIG - |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: .. 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 configured as ``FACE::SOURCE`` or ``FACE::BI_DIRECTIONAL``. See the OMG Specification for Data Distribution Service for Real-time Systems, v1.2 section 7.1.2.4.1, for information on the Publisher entity class. **NOTE**: Although DDS allows for Publishers to contain multiple DataWriters, in |TSS| Publishers are not shared by connections. * - Subscriber - Created if the connection is configured as ``FACE::DESTINATION`` or ``FACE::BI_DIRECTIONAL``. See the OMG Specification for Data Distribution Service for Real-time Systems, v1.2 section 7.1.2.5.2, for information on the Subscriber entity class. **NOTE**: Although DDS allows for Subscribers to contain multiple DataReaders, in |TSS| Subscribers are not shared by connections. * - DataWriter - Created if the connection is configured as ``FACE::SOURCE`` or ``FACE::BI_DIRECTIONAL``. See the OMG Specification for Data Distribution Service for Real-time Systems, v1.2 section 7.1.2.4.2, for information on the DataWriter entity class. * - DataReader - Created if the connection is configured as ``FACE::DESTINATION`` or ``FACE::BI_DIRECTIONAL``. See the OMG Specification for Data Distribution Service for Real-time Systems, v1.2 section 7.1.2.5.3, for information on the DataReader entity class. The ``Create_Connection`` function is non-blocking. This function is *not* thread safe for Connext DDS Pro and Connext Micro. .. _API_destroy_conn: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Destroy_Connection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: C++ void Destroy_Connection( const FACE::TSS::CONNECTION_ID_TYPE connection_id, FACE::RETURN_CODE_TYPE::Value &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 ``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_ACTION - The connection was already destroyed * - FACE::INVALID_PARAM - The connection does not exist. * - FACE::NO_ERROR - The operation completed successfully. .. note:: **NOTE**: |TSS| built with Connext DDS Micro for Safety Base or Security OSS profiles does not reclaim any |TSS| connection or DDS resources. This function is *not* thread safe for Connext DDS Pro and is thread safe for Connext Micro. .. _API_enable_dds: ^^^^^^^^^^^^^^^^^^^^^^ Enable_DDS_Entities() ^^^^^^^^^^^^^^^^^^^^^^ The DDS entities underlying |TSS| connections can have their QoS configured such that they are disabled upon connection creation, with resources allocated but no processes running or discovery messages sent. This would be necessary for platforms with explicit intialization phases (e.g. ARINC 653). Consequently, after all connections have been created and the platform is done with intialization, the first call after initialization must be to this function, so that DDS processes can run and DDS discovery can be done. .. code-block:: C++ void Enable_DDS_Entities ( /* out */ FACE::RETURN_CODE_TYPE::Value &return_code); ) .. list-table:: RTI::TSS::Base::Enable_DDS_Entities Parameters :name: TableFACETSSBaseEnableDDSParams :widths: 12 20 8 60 :header-rows: 1 * - Parameter Name - Type - Direction - Description * - return_code - FACE::RETURN_CODE_TYPE - OUT - The return code for the call to ``Enable_DDS_Entities()``. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure. .. list-table:: RTI::TSS::Base::Enable_DDS_Entities Return Codes :name: TableFACETSSBaseEnableDDSRetCodes :widths: 40 60 :header-rows: 1 * - Return Code - Description * - FACE::NO_ERROR - The operation completed successfully. * - FACE::NOT_AVAILABLE - |TSS| was not initialized before this operation, or the operation failed to enable DDS entities. This function is non-blocking. This function is *not* thread safe for Connext DDS Pro. It is thread safe for Connext DDS Micro. ---------------- Communication ---------------- For each user defined type, |TSS| rtiddsegn generates a class implementing the Typed-Specific Typed Inteface. Its functions are responsible for sending and receiving the typed messages. .. _API_send_msg: ^^^^^^^^^^^^^^^^^^^^^^^^^ Send_Message() ^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: C++ 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 ) .. 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 a created connection to use to send the message. * - 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. It is not used or set by |TSS|. * - message - DATATYPE_TYPE - INOUT - The typed message to be sent. **NOTE**: The type of the message must correspond to the type specified in the connection configuration for the given ``connection_id``. * - return_code - FACE::RETURN_CODE_TYPE - OUT - The return code for the call to ``FACE::TS::Send_Message``. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure. .. 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::CONNECTION_CLOSED - The provided ``connection_id`` existed at some point but its associated connection was already destroyed. * - FACE::INVALID_MODE - The connection associated with the ``connection_id`` is of direction ``FACE::DESTINATION``. ``FACE::TS::Send_Message`` only works with connections using direction ``FACE::SOURCE`` or ``FACE::BI_DIRECTIONAL``. * - FACE::NO_ACTION - The underliying DDS-level API returned an error. * - FACE::NO_ERROR - The operation completed successfully. Upon a successful call, the DDS DataWriter corresponding to the connection with the matching connection ID will have written one message. This function is *not* thread safe. .. _API_recv_msg: ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Receive_Message() ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: C++ 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 ) .. 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 duration to wait for an incoming message before returning to the calling application with a return code indicating the call has timed out. * - transaction_id - FACE::TRANSACTION_ID_TYPE - INOUT - The ``transaction_id`` parameter is used in the request/reply communication pattern, which is not currently available in |TSS|. * - message - DATATYPE_TYPE - INOUT - The strongly typed message to be received. An implementer will substitute their type for ``DATATYPE_TYPE``. **NOTE**: The type of the message must correspond to the type specified in the connection configuration for the given ``connection_id``. * - header - FACE::TSS::HEADER_TYPE - OUT - The ``header`` parameter is not currently set or supported by |TSS|. * - qos_parameters - FACE::TSS::QoS_EVENT_TYPE - OUT - The ``qos_parameters`` parameter is not currently set or supported by |TSS|. * - return_code - FACE::RETURN_CODE_TYPE - OUT - The return code for the call to ``Receive_Message``. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure. .. 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::CONNECTION_CLOSED - The provided ``connection_id`` existed at some point but its associated connection was already destroyed. * - FACE::INVALID_MODE - The connection associated with the ``connection_id`` is of direction ``FACE::SOURCE``. ``FACE::TS::Receive_Message`` only works with connections using direction ``FACE::DESTINATION`` or ``FACE::BI_DIRECTIONAL``. * - FACE::TIMED_OUT - The call to ``FACE::TS::Receive_Message`` timed out before any data was received on the connection. * - FACE::MESSAGE_STALE - The instance was disposed. * - FACE::NO_ACTION - The underliying DDS-level API returned an error. * - FACE::NO_ERROR - The operation completed successfully. Users will poll with this function for received data. Upon a successful call, the DDS DataReader corresponding to the connection with the matching connection ID will have received and taken one message. This function is *not* thread safe. ------------------- Callback Interface ------------------- The FACE TSS callback interface allows for messages to be received without polling. .. _API_reg_call: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Register_Callback() ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The TypedTS instance supports the Register_Callback function to receive data without polling. Each received message will invoke the registered callback. .. code-block:: C++ void Register_Callback( FACE::TSS::CONNECTION_ID_TYPE connection_id, Read_Callback& callback, FACE::RETURN_CODE_TYPE::Value& 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 ``Create_Connection``. * - callback - DATATYPE_TYPE::Read_Callback - IN - The user-defined callback function to invoke whenever data is received on the connection. * - return_code - FACE::RETURN_CODE_TYPE - OUT - The return code for the call to ``FACE::TS::Register_Callback``. Upon return of the call, this parameter will be populated with a value that will indicate either success or a reason for failure. .. 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 ``callback`` parameter is invalid. * - FACE::CONNECTION_CLOSED - The provided ``connection_id`` existed at some point but its associated connection was already destroyed. * - FACE::NO_ACTION - There is a callback already registered. * - FACE::NO_ERROR - The callback was successfully registered. The registered callback is invoked in the context of the DDS DataReader's receive thread. Only one callback can be registered per connection. This function is *not* thread safe. .. _API_call_handler: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Read_Callback::Callback_Handler ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This function is a user defined handler for receiving data via callback instead of polling. .. code-block:: C++ 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 ) .. list-table:: FACE::Read_Callback:Callback_Handler Parameters :name: TableFACECallbackSendEventParams :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 message was received. * - transaction_id - FACE::TRANSACTION_ID_TYPE - IN - The ``transaction_id`` parameter is used in the request/reply communication pattern, which is not currently available in |TSS|. * - message - FACE_SPECIFIED_TYPE - INOUT - The strongly typed message that was received. An implementer will substitute their type for ``DATATYPE_TYPE``. **NOTE**: The type of the message must correspond to the type specified in the connection configuration for the given ``connection_id``. * - header - FACE::TSS::HEADER_TYPE - OUT - The ``header`` parameter is not currently set or supported by |TSS|. * - qos_parameters - FACE::TSS::QoS_EVENT_TYPE - OUT - The ``qos_parameters`` parameter is not currently set or supported 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. .. _API_unreg_call: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ FACE::TSS::BASE::Unregister_Callback() ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This function removes a registered callback from a connection. .. code-block:: C++ void Unregister_Callback( const FACE::TSS::CONNECTION_ID_TYPE connection_id, FACE::RETURN_CODE_TYPE::Value &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 ``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::TSS::BASE::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. 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 output behavior is configured at the time of the |TSS| build. It is configured by the RTI_LOG_VERBOSITY and RTI_TSS_LOG_FILE_TYPE CMake variable, and are set to warning and stdout by default. The following logging options are available: .. list-table:: FACE TSS Logging File Type Options :name: TableFACETSLoggingFileTypeOptions :widths: 15 85 :header-rows: 1 * - Option - Description * - none - Disables logging. * - stdout - Enables logging to the operating system STDOUT file descriptor. This is the default behavior if RTI_TSS_LOG_FILE_TYPE is not defined. * - file - Enables logging to a named file. The file name is defined with the LOG_FILE_NAME variable. If LOG_FILE_NAME is not defined, it is set to ``rtifacetss.log`` by default. * - timestamp - Enables logging to a file named with a timestamp created at application startup. This filename is formatted as ``rtifacetss__.log``. .. list-table:: FACE TSS Logging Verbosity Options :name: TableFACETSLoggingVerbosityOptions :widths: 15 85 :header-rows: 1 * - Option - Description * - Silent - Disables logging. * - Error - Enables logging for error messages * - Warning - Enables logging for error and warning messages. This is the default behavior if RTI_TSS_LOG_FILE_TYPE is not defined. * - Info - Enables logging for error, warning, and info messages. * - Debug - Enables logging for error, warning, info, and debug messages. All log writing is done using the POSIX ``write()`` API. The logging header is in ``log/ext_log.h`` and exposes the following macros for logging: .. code-block:: C++ #define Logger_error(methodName, message_, ...) #define Logger_warning(methodName, message_, ...) #define Logger_info(methodName, message_, ...) #define Logger_debug(methodName, message_, ...) Messages can be logged using the macros which offer usage similar to an ``fprintf()`` call: .. code-block:: C++ Logger_error(THIS_METHOD_NAME, "Unable to register callback for connection id (%llu)", connection_id); Notes: * The logger is *not* thread safe. * The logger is *not* available (compiled out, not part of the build) for FACE OS profiles Safety Base or stricter.