RTI Routing Library API

Prototype of the function that gets called upon reception of the shutdown command. More...

Data Structures
struct	RTI_RoutingService
	RTI Routing Service. More...
struct	RTI_RoutingServiceTransportConfig
	Association between a transport alias and its create function pointer. More...
struct	RTI_RoutingServiceProperty
	Configuration of RTI Routing Service. More...

Macros
#define	RTI_RoutingServiceProperty_INITIALIZER
	The initial values for an RTI_RoutingServiceProperty instance. More...

Functions
struct RTI_RoutingService *	RTI_RoutingService_new (const struct RTI_RoutingServiceProperty *property)
	Create a new RTI Routing Service instance. More...
void	RTI_RoutingService_delete (struct RTI_RoutingService *self)
	Stop and delete an RTI Routing Service instance. More...
DDS_Boolean	RTI_RoutingService_start (struct RTI_RoutingService *self)
	Start RTI Routing Service. More...
DDS_Boolean	RTI_RoutingService_stop (struct RTI_RoutingService *self)
	Stop RTI Routing Service. More...
DDS_Boolean	RTI_RoutingService_attach_adapter_plugin (struct RTI_RoutingService *self, void *adapter, const char *plugin_name)
	Attach an adapter to be used by routing service when it is started. More...
DDS_Boolean	RTI_RoutingService_attach_transformation_plugin (struct RTI_RoutingService *self, struct RTI_RoutingServiceTransformationPlugin *transformation_plugin, const char *plugin_name)
	Attach a transformation plugin to be used by Routing Service when it is started. More...
DDS_Boolean	RTI_RoutingService_attach_processor_plugin (struct RTI_RoutingService *self, void *processor_plugin, const char *plugin_name)
	Attach a processor to be used by Routing Service when it is started. More...
DDS_Boolean	RTI_RoutingService_set_remote_shutdown_hook (struct RTI_RoutingService *self, const struct RTI_RoutingServiceRemoteShutdownHook *shutdown_hook)
	Set the remote shutdown hook in this Routing Service instance. More...
void	RTI_RoutingService_execute_command (struct RTI_RoutingService *self, struct RTI_Service_Admin_CommandReply **reply, const struct RTI_Service_Admin_CommandRequest *request)
	Executes an Administration command on this service. More...
void	RTI_RoutingService_return_reply (struct RTI_RoutingService *self, struct RTI_Service_Admin_CommandReply *reply)
	Returns the reply object that is obtained as result of executing a command. More...
DDS_Boolean	RTI_RoutingService_initialize_globals (void)
DDS_Boolean	RTI_RoutingService_finalize_globals (void)
const char *	RTI_RoutingService_get_build_number_string (void)
	Return the build ID of this library. More...
DDS_Boolean	RTI_RoutingService_is_started (struct RTI_RoutingService *self)
	Query whether this Routing Service is currently started. More...

Variables
const int	RTI_ROUTING_SERVICE_LOG_VERBOSITY_DEBUG
	Verbosity level: exceptions + warnings + info + periodic + content. More...
const int	RTI_ROUTING_SERVICE_LOG_VERBOSITY_ALL
	Verbosity level: exceptions + warnings + info + periodic. More...
const int	RTI_ROUTING_SERVICE_LOG_VERBOSITY_INFO
	Verbosity level: exceptions + warnings + info. More...
const int	RTI_ROUTING_SERVICE_LOG_VERBOSITY_WARNINGS
	Verbosity level: exceptions + warnings. More...
const int	RTI_ROUTING_SERVICE_LOG_VERBOSITY_EXCEPTIONS
	Verbosity level: exceptions. More...
const int	RTI_ROUTING_SERVICE_LOG_VERBOSITY_SILENT
	Verbosity level: silent. More...

Detailed Description

Prototype of the function that gets called upon reception of the shutdown command.

Routing Service can be deployed as a C library linked into your application on select architectures.

Definition of the interface that handles the remote shutdown.

This API allows you to create, configure and start RTI Routing Service instances from your application.

The following code shows the typical use of the API:

struct RTI_RoutingServiceProperty property = RTI_RoutingServiceProperty_INITIALIZER;
struct RTI_RoutingService * service = NULL;
 
property.cfg_file = "my_routing_service_cfg.xml";
property.service_name = "my_routing_service";
...
 
service = RTI_RoutingService_new(&property);
if(service == NULL) {
   printf("Error...");
   return -1;
}
 
if(!RTI_RoutingService_start(service)) {
   printf("Error...");
   RTI_RoutingService_delete(service);
   return -1;
}
 
while(keep_running) {
    sleep();
    ...
}
 
RTI_RoutingService_delete(service);
 
return 0;

Instead of a file, you can use XML strings to configure RTI Routing Service. See RTI_RoutingServiceProperty for more information.

To build your application you need to link with the RTI Routing Service library in <RTI Routing Service home>/bin/<architecture>/

If you are using the C API on a Windows, Linux, MAC or INTEGRITY platform: See the example in <RTI Routing Service home>/example/wrapperApp Example makefiles and project files for several architecures are provided. Also see the README.txt file in the wrapperApp/src directory.

Development Requirements

	Linux/macOS Systems	Windows Systems
Shared Libraries	librtirsinfrastructure.so	rtirsinfrastructure.dll
	librtidlc.so	rtidlc.dll
	librtiapputilsc.so	rtiapputilsc.dll
	libnddsmetp.so	nddsmetp.dll
	librticonnextmsgc.so	rticonnextmsgc.dll
	libnddsc.so	nddsc.dll
	librtixml2.so	rtixml2.dll
	libnddscore.so	nddscore.dll
Headers	routingservice/routingservice_service.h

Macro Definition Documentation

RTI_RoutingServiceProperty_INITIALIZER

#define RTI_RoutingServiceProperty_INITIALIZER

The initial values for an RTI_RoutingServiceProperty instance.

Function Documentation

RTI_RoutingService_new()

struct RTI_RoutingService * RTI_RoutingService_new

(

const struct RTI_RoutingServiceProperty *

property

)

Create a new RTI Routing Service instance.

Parameters

property

The properties to configure RTI Routing Service. This parameter is copied internally, so the user is responsible for releasing any memory allocated inside this structure.

MT Safety:

On non-Linux, non-Windows systems (i.e. VxWorks): UNSAFE for multiple threads to simultaneously make the FIRST call to RTI_RoutingService_new(). Subsequent calls are thread safe. On Windows and Linux systems, these calls are thread-safe.

RTI_RoutingService_delete()

void RTI_RoutingService_delete

(

struct RTI_RoutingService *

self

)

Stop and delete an RTI Routing Service instance.

See also

RTI_RoutingService_stop

Parameters

self	An RTI_RoutingService instance created with RTI_RoutingService_new

MT Safety:

This method is not thread-safe. Calling this method from different threads for the same Routing Service instance may result in undefined behavior.

RTI_RoutingService_start()

DDS_Boolean RTI_RoutingService_start

(

struct RTI_RoutingService *

self

)

Start RTI Routing Service.

This is a non-blocking operation. RTI Routing Service will create its own set of threads to perform its tasks.

Parameters

self	An RTI_RoutingService instance created with RTI_RoutingService_new

RTI_RoutingService_stop()

DDS_Boolean RTI_RoutingService_stop

(

struct RTI_RoutingService *

self

)

Stop RTI Routing Service.

This function won't return the execution control until the instance is fully stopped.

Parameters

self	An RTI_RoutingService instance created with RTI_RoutingService_new

MT Safety:

This method is not thread-safe. Calling this method from different threads for the same Routing Service instance may result in undefined behavior.

RTI_RoutingService_attach_adapter_plugin()

DDS_Boolean RTI_RoutingService_attach_adapter_plugin	(	struct RTI_RoutingService *	self,
		void *	adapter,
		const char *	plugin_name
	)

Attach an adapter to be used by routing service when it is started.

By using this function, an adapter can be statically compiled, created in your application and have routing service load it, instead of registering a shared library and a create function in the configuration. The name passed into this function is the name that has to be used in the configuration to instantiate connections from the plugin.

Example:

service = RTI_RoutingService_new(&property);
myAdapter = MyAdapter_create();
 
RTI_RoutingService_attach_adapter_plugin(service, myAdapter, "MyAdapter");
 
RTI_RoutingService_start(service);
...

And our configuration would look like this:

<dds>
 <!-- No need to register the plugin in
      <plugin_library><adapter_plugin>
 -->
 <routing_service name="example">
  <domain_route name="myadapter_to_dds">
 
    <connection name="MyConnection" plugin_name="MyAdapter">
       ...
    </connection>
 
    ...
  </domain_route>
 </routing_service>
</dds>

This function can be called as many times as desired to attach several plugins.

Note: The RTI Routing Service Adapter SDK is required.

Precondition

Routing Service must not be started.

Parameters

self	An RTI_RoutingService instance not started yet (or stopped)
adapter	The adapter plugin to be attached
plugin_name	The name used for this plugin in the <connection> tags in the configuration

RTI_RoutingService_attach_transformation_plugin()

DDS_Boolean RTI_RoutingService_attach_transformation_plugin	(	struct RTI_RoutingService *	self,
		struct RTI_RoutingServiceTransformationPlugin *	transformation_plugin,
		const char *	plugin_name
	)

Attach a transformation plugin to be used by Routing Service when it is started.

See also

RTI_RoutingService_attach_adapter_plugin

RTI_RoutingService_attach_processor_plugin()

DDS_Boolean RTI_RoutingService_attach_processor_plugin	(	struct RTI_RoutingService *	self,
		void *	processor_plugin,
		const char *	plugin_name
	)

Attach a processor to be used by Routing Service when it is started.

See also

RTI_RoutingService_attach_adapter_plugin

RTI_RoutingService_set_remote_shutdown_hook()

DDS_Boolean RTI_RoutingService_set_remote_shutdown_hook	(	struct RTI_RoutingService *	self,
		const struct RTI_RoutingServiceRemoteShutdownHook *	shutdown_hook
	)

Set the remote shutdown hook in this Routing Service instance.

The shutdown hook will be notified upon reception of a remote shutdown command.

The operation will fail if the RS is already started.

RTI_RoutingService_execute_command()

void RTI_RoutingService_execute_command	(	struct RTI_RoutingService *	self,
		struct RTI_Service_Admin_CommandReply **	reply,
		const struct RTI_Service_Admin_CommandRequest *	request
	)

Executes an Administration command on this service.

This operation directly executes the specified request in this service as if it was directly received from an administration requester.

The request can represent any of the available administration operations as documented in the Administration chapter in the user's manual. This operation gives you an alternative way to control the service using the same remote administration interface but allowing you to call the operation directly.

Parameters

self	In. The Routing Service instance.
reply	out. Result of the processing of the command request.
request	In. Request to be processed.

RTI_RoutingService_return_reply()

void RTI_RoutingService_return_reply	(	struct RTI_RoutingService *	self,
		struct RTI_Service_Admin_CommandReply *	reply
	)

Returns the reply object that is obtained as result of executing a command.

This operation allows the service to release the memory associated to the reply if needed.

Parameters

self	In. The Routing Service instance
reply	In. Reply result of the processing of the command request.

RTI_RoutingService_initialize_globals()

DDS_Boolean RTI_RoutingService_initialize_globals

(

void

)

[DEPRECATED]

This operation has been deprecated and will be removed in future releases. Routing Service does not require external initialization of the global state.

RTI_RoutingService_finalize_globals()

DDS_Boolean RTI_RoutingService_finalize_globals

(

void

)

[DEPRECATED]

This operation has been deprecated and will be removed in future releases. Routing Service does not require external finalization of the global state.

RTI_RoutingService_get_build_number_string()

const char * RTI_RoutingService_get_build_number_string

(

void

)

Return the build ID of this library.

The build ID uniquely identifies a specific build of the Routing Service library.

RTI_RoutingService_is_started()

DDS_Boolean RTI_RoutingService_is_started

(

struct RTI_RoutingService *

self

)

Query whether this Routing Service is currently started.

Variable Documentation

RTI_ROUTING_SERVICE_LOG_VERBOSITY_DEBUG

const int RTI_ROUTING_SERVICE_LOG_VERBOSITY_DEBUG

extern

Verbosity level: exceptions + warnings + info + periodic + content.

RTI_ROUTING_SERVICE_LOG_VERBOSITY_ALL

const int RTI_ROUTING_SERVICE_LOG_VERBOSITY_ALL

extern

Verbosity level: exceptions + warnings + info + periodic.

RTI_ROUTING_SERVICE_LOG_VERBOSITY_INFO

const int RTI_ROUTING_SERVICE_LOG_VERBOSITY_INFO

extern

Verbosity level: exceptions + warnings + info.

RTI_ROUTING_SERVICE_LOG_VERBOSITY_WARNINGS

const int RTI_ROUTING_SERVICE_LOG_VERBOSITY_WARNINGS

extern

Verbosity level: exceptions + warnings.

RTI_ROUTING_SERVICE_LOG_VERBOSITY_EXCEPTIONS

const int RTI_ROUTING_SERVICE_LOG_VERBOSITY_EXCEPTIONS

extern

Verbosity level: exceptions.

RTI_ROUTING_SERVICE_LOG_VERBOSITY_SILENT

const int RTI_ROUTING_SERVICE_LOG_VERBOSITY_SILENT

extern

Verbosity level: silent.