FACE::TS Namespace Reference

Functions
void	Create_Connection (const FACE::CONNECTION_NAME_TYPE &connection_name, const FACE::MESSAGING_PATTERN_TYPE &pattern, FACE::CONNECTION_ID_TYPE &connection_id, FACE::CONNECTION_DIRECTION_TYPE &connection_direction, FACE::MESSAGE_SIZE_TYPE &max_message_size, const FACE::TIMEOUT_TYPE &timeout, FACE::RETURN_CODE_TYPE &return_code)
void	Destroy_Connection (const FACE::CONNECTION_ID_TYPE &connection_id, FACE::RETURN_CODE_TYPE &return_code)
void	Get_Connection_Parameters (FACE::CONNECTION_NAME_TYPE &connection_name, FACE::CONNECTION_ID_TYPE &connection_id, FACE::TRANSPORT_CONNECTION_STATUS_TYPE &connection_status, FACE::RETURN_CODE_TYPE &return_code)
void	Initialize (const FACE::CONFIGURATION_RESOURCE &configuration, FACE::RETURN_CODE_TYPE &return_code)
void	Receive_Message (const FACE::CONNECTION_ID_TYPE &connection_id, const FACE::TIMEOUT_TYPE &timeout, FACE::TRANSACTION_ID_TYPE &transaction_id, Data::Type &message, FACE::MESSAGE_TYPE_GUID &message_type_id, FACE::MESSAGE_SIZE_TYPE &message_size, FACE::RETURN_CODE_TYPE &return_code)
void	Register_Callback (const FACE::CONNECTION_ID_TYPE &connection_id, const FACE::WAITSET_TYPE &waitset, FACE::Read_Callback< Data::Type >::send_event data_callback, const FACE::MESSAGE_SIZE_TYPE &max_message_size, FACE::RETURN_CODE_TYPE &return_code)
void	Send_Message (const FACE::CONNECTION_ID_TYPE &connection_id, const FACE::TIMEOUT_TYPE &timeout, FACE::TRANSACTION_ID_TYPE &transaction_id, Data::Type &message, const FACE::MESSAGE_TYPE_GUID &message_type_id, const FACE::MESSAGE_SIZE_TYPE &message_size, FACE::RETURN_CODE_TYPE &return_code)
void	Unregister_Callback (const FACE::CONNECTION_ID_TYPE &connection_id, FACE::RETURN_CODE_TYPE &return_code)

Function Documentation

Create_Connection()

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

The Transport Services Segment (TSS) provides an interface to create a connection. The parameters for the individual connections are determined through the TSS configuration capability which is set by the Initialize function call.

Possible return codes:

• NO_ERROR - Successful completion.
• NO_ACTION - Returned if the participant has already been created and registered. - Type has already been registered.
• INVALID_CONFIG - Could not allocate enough memory. - Policies are not consistent with each other (e.g., configuration data is invalid, QoS attributes not supported).
  • Generic, unspecified error.
  • Attempted to modify an immutable QoSPolicy.
• INVALID_PARAM - Returned under the following conditions: - Could not find topic name associated with the connection.
• NOT_AVAILABLE - Unsupported operation.
• INVALID_MODE - Connection could not be created in the current mode or operation performed at an inappropriate type.

Parameters

connection_name	The connection_name which needs to match one of the configured connection names in the configuration This is an input parameter.
pattern	The pattern set in the connection configuration which for DDS only can be PUB_SUB. This is an input parameter.
connection_id	The connection_id which is generated by DDS and set on successful creation. This is an output parameter.
connection_direction	The connection_direction of the connection that is created. This can be SOURCE or DESTINATION. This is an output parameter.
max_message_size	The max_message_size for DDS this parameter is not relevant. This is an output parameter.
timeout	The timeout for DDS this parameter is not relevant. This is an input parameter.
return_code	The return_code This is an output parameter.

Destroy_Connection()

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

The Destroy_Connection function frees up any resources allocated to the connection.

Possible return codes:

• NO_ERROR - Successful completion.
• NO_ACTION - Object target of this operation has already been deleted.
• INVALID_MODE - An operation was invoked on an inappropriate object or at an inappropriate time.
• INVALID_PARAM - Connection identification (ID) invalid.
• NOT_AVAILABLE - Unsupported operation.
• INVALID_CONFIG - Generic, unspecified error.
• INVALID_MODE - A pre-condition for the operation was not met. Note: In a FACE implementation, this error may imply an implementation problem since the connection is deleted and should clean up all entities/children associated with the connection.

Parameters

connection_id	The connection_id of the connection that needs to be destroyed. This is an input parameter.
return_code	The return_code. This is an output parameter.

Get_Connection_Parameters()

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

The purpose of Get_Connection_Parameters is to get the information regarding the requested connection.

Parameters

connection_name	The connection_name which belongs to the given connection_id. This is an output parameter.
connection_id	The connection_id for which this status needs to return information This is an input parameter.
connection_status	The connection_status which consists of the following settings: MESSAGE - Always 0 MAX_MESSAGE - Always 0. MAX_MESSAGE_SIZE - Always 0. CONNECTION_DIRECTION - SOURCE or DESTINATION WAITING_PROCESSES_OR_MESSAGES - Not implemented REFRESH_PERIOD - The configured refresh period. LAST_MSG_VALIDITY - Whether or not the refresh period of last taken message has expired or not (DESTINATION) This is an output parameter.
return_code	The return_code This is an output parameter.

Initialize()

void FACE::TS::Initialize	(	const FACE::CONFIGURATION_RESOURCE &	configuration,
		FACE::RETURN_CODE_TYPE &	return_code
	)

The Initialize function call allows for the Portable Components Segment (PCS) and Platform-Specific Services Segment (PSSS) component to trigger the initialization of the Transport Services Segment (TSS) component.

Possible return codes:

• INVALID_PARAM - The provided configuration is not valid
• INVALID_CONFIG - The provided configuration contains invalid settings
• NO_ACTION - There is already an initialized configuration.

Parameters

configuration	The configuration defined as an xml file which hold the connection configuration. This is an input parameter
return_code	The return_code

Receive_Message()

void FACE::TS::Receive_Message	(	const FACE::CONNECTION_ID_TYPE &	connection_id,
		const FACE::TIMEOUT_TYPE &	timeout,
		FACE::TRANSACTION_ID_TYPE &	transaction_id,
		Data::Type &	message,
		FACE::MESSAGE_TYPE_GUID &	message_type_id,
		FACE::MESSAGE_SIZE_TYPE &	message_size,
		FACE::RETURN_CODE_TYPE &	return_code
	)

The Receive_Message Function is used to receive data from another source.

Possible return codes:

• NO_ERROR - Successful completion.
• NO_ACTION - Object target of this operation has already been deleted.
• INVALID_MODE - An operation was invoked on an inappropriate object or
• INVALID_PARAM - Illegal parameter value (e.g., connection ID).
• INVALID_CONFIG - Generic, unspecified error.
• NOT_AVAILABLE - Unsupported operation.
• INVALID_MODE
  • A pre-condition for the operation was not met.
  • Operation invoked on an entity that is not yet enabled.
• NO_ACTION - Indicates a transient situation where the operation did

Parameters

connection_id	The connection_id which is used to get the connection where to receive messages on. This is an input parameter.
timeout	The timeout in nanoseconds, this is used to determine how long DDS should wait for new messages to arrive before returning the result. This is an input parameter.
transaction_id	The transaction_id, each time a message is read an unique transaction_id is generated for it. This is an output parameter.
message	The message that is read by DDS This is an output parameter.
message_type_id	The message_type_id for DDS this parameter is not relevant. This is an output parameter.
message_size	The message_type_id for DDS this parameter is not relevant. This is an output parameter.
return_code	The return_code This is an output parameter.

Register_Callback()

void FACE::TS::Register_Callback	(	const FACE::CONNECTION_ID_TYPE &	connection_id,
		const FACE::WAITSET_TYPE &	waitset,
		FACE::Read_Callback< Data::Type >::send_event	data_callback,
		const FACE::MESSAGE_SIZE_TYPE &	max_message_size,
		FACE::RETURN_CODE_TYPE &	return_code
	)

The purpose of Register_Callback is to provide a mechanism to read data without polling. This needs to be called on the generated type interface without using the TS Interface. There can only be one callback registration per connection_id.

Possible return codes:

• NO_ERROR - Successful completion.
• NO_ACTION - Callback already registered for specified type.
• INVALID_PARAM - One or more of the parameters are incorrect (e.g., invalid connection identification (ID), invalid callback, invalid message size).
• NOT_AVAILABLE - Callback/routing function not available (e.g., callback service is not provided in this implementation).
• INVALID_CONFIG - One or more fields in the configuration data for the connection is invalid (e.g., invalid TSS thread parameters).

Register_Callback Example

static void data_callback (const FACE::TRANSACTION_ID_TYPE &transaction_id,
                           Data::Type                      &message,
                           const FACE::MESSAGE_TYPE_GUID   &message_type_id,
                           const FACE::MESSAGE_SIZE_TYPE   &message_size,
                           const FACE::WAITSET_TYPE        &waitset,
                           FACE::RETURN_CODE_TYPE          &return_code)
{
   do your action here
}

then the callback can be registered by calling:
FACE::TS::Register_Callback(connection_id, waitset, data_callback, maxMessageSize, status);

Parameters

connection_id	The connection_id of the connection that needs to be used for the callback. This is an input parameter.
waitset	The waitset for DDS this parameter is not relevant. This is an input parameter.
data_callback	The data_callback class in which an action can be set on how to react when receiving data. This data_callback is the external operation (interface, which must be implemented by the application see example) that is called by the FACE API when new data is available for this connection. This is an input parameter.
max_message_size	The max_message_size for DDS this parameter is not relevant however the max_message_size supplied needs to be less then the max_message_size of the configured connection. This is an input parameter.
return_code	the return_code This is an output parameter.

Send_Message()

void FACE::TS::Send_Message	(	const FACE::CONNECTION_ID_TYPE &	connection_id,
		const FACE::TIMEOUT_TYPE &	timeout,
		FACE::TRANSACTION_ID_TYPE &	transaction_id,
		Data::Type &	message,
		const FACE::MESSAGE_TYPE_GUID &	message_type_id,
		const FACE::MESSAGE_SIZE_TYPE &	message_size,
		FACE::RETURN_CODE_TYPE &	return_code
	)

The Send_Message Function is used to send data to another source.

Possible return codes:

• NO_ERROR - Successful completion.
• NO_ACTION - Object target of this operation has already been deleted.
• INVALID_MODE - An operation was invoked on an inappropriate object or at an inappropriate time.
• INVALID_PARAM - Illegal parameter value (e.g., connection ID).
• INVALID_CONFIG - Generic, unspecified error.
• NOT_AVAILABLE - Unsupported operation.
• INVALID_MODE
  • A pre-condition for the operation was not met.
  • Operation invoked on an entity that is not yet enabled.
• INVALID_CONFIG - Service ran out of resources needed to complete the operation.
• TIMED_OUT - DDS will not return TIMEOUT, but this could be returned by the TSS implementation.

Parameters

connection_id	The connection_id which is used to get the connection where to send messages to. This is an input parameter.
timeout	The timeout in nanoseconds, this is used to determine how long DDS at maximum can wait to send the message. This timeout cannot be greater than max_blocking_time of the supplied DataWriter QoS. This is an input parameter.
transaction_id	The transaction_id, each time a message is send an unique transaction_id is generated for it. This is an output parameter.
message	The message that is read by DDS This is an output parameter.
message_type_id	The message_type_id for DDS this parameter is not relevant. This is an output parameter.
message_size	The message_type_id for DDS this parameter is not relevant. This is an output parameter.
return_code	The return_code This is an output parameter.

Unregister_Callback()

void FACE::TS::Unregister_Callback	(	const FACE::CONNECTION_ID_TYPE &	connection_id,
		FACE::RETURN_CODE_TYPE &	return_code
	)

The purpose of Unregister_Callback is to provide a mechanism to unregister the callback associated with a connection_id.

Parameters

connection_id	The connection_id of the connection where the callback was registered. This is an input parameter.
return_code	The return_code This is an output parameter.