Library API

This API allows you to embed RTI Persistence Service in your application. More...

Modules
	Version API

Data Structures
struct	RTI_PersistenceService
	RTI Persistence Service. More...
struct	RTI_PersistenceServiceProperty
	Configuration of RTI Persistence Service. More...

Enumerations
enum	RTI_PersistenceService_ParticipantKind
	Indicates the different kinds of internal DDS_DomainParticipant created by RTI Persistence Service. More...

Functions
DDS_Boolean	RTI_PersistenceService_get_participant_qos (const struct RTI_PersistenceService *self, struct DDS_DomainParticipantQos *domain_participant_qos, const char *participant_name, RTI_PersistenceService_ParticipantKind participant_kind)
	Get the DDS_DomainParticipantQos for the internal DDS_DomainParticipant created by RTI Persistence Service. More...
DDS_Boolean	RTI_PersistenceService_set_participant_qos (struct RTI_PersistenceService *self, const char *participant_name, RTI_PersistenceService_ParticipantKind participant_kind, const struct DDS_DomainParticipantQos *domain_participant_qos)
	Set the DDS_DomainParticipantQos for the internal DDS_DomainParticipant created by RTI Persistence Service. More...
DDS_Boolean	RTI_PersistenceService_get_publisher_qos (const struct RTI_PersistenceService *self, struct DDS_PublisherQos *publisher_qos, const char *participant_name, const char *persistence_group_name)
	Get the DDS_PublisherQos for the internal DDS_Publisher created by RTI Persistence Service. More...
DDS_Boolean	RTI_PersistenceService_set_publisher_qos (struct RTI_PersistenceService *self, const char *participant_name, const char *persistence_group_name, const struct DDS_PublisherQos *publisher_qos)
	Set the DDS_PublisherQos for the internal DDS_Publisher created by RTI Persistence Service. More...
DDS_Boolean	RTI_PersistenceService_get_subscriber_qos (const struct RTI_PersistenceService *self, struct DDS_SubscriberQos *subscriber_qos, const char *participant_name, const char *persistence_group_name)
	Get the DDS_SubscriberQos for the internal DDS_Subscriber created by RTI Persistence Service. More...
DDS_Boolean	RTI_PersistenceService_set_subscriber_qos (struct RTI_PersistenceService *self, const char *participant_name, const char *persistence_group_name, const struct DDS_SubscriberQos *subscriber_qos)
	Set the DDS_SubscriberQos for the internal DDS_Subscriber created by RTI Persistence Service. More...
DDS_Boolean	RTI_PersistenceService_is_started (struct RTI_PersistenceService *self)
	Indicates if RTI Persistence Service was started by calling RTI_PersistenceService_start. More...
struct RTI_PersistenceService *	RTI_PersistenceService_new (struct RTI_PersistenceServiceProperty *property)
	Create a new RTI Persistence Service instance. More...
void	RTI_PersistenceService_delete (struct RTI_PersistenceService *self)
	Stop and delete RTI Persistence Service instance. More...
DDS_Boolean	RTI_PersistenceService_start (struct RTI_PersistenceService *self)
	Start RTI Persistence Service. More...
DDS_Boolean	RTI_PersistenceService_stop (struct RTI_PersistenceService *self)
	Stop RTI Persistence Service. More...
DDS_Boolean	RTI_PersistenceService_initialize_globals (void)
	Initialize the RTI Persistence Service globals. More...
void	RTI_PersistenceService_finalize_globals (void)
	Finalize the RTI Persistence Service globals. More...

Variables
const struct RTI_PersistenceServiceProperty	RTI_PersistenceServiceProperty_INITIALIZER
	The initial values for an RTI_PersistenceServiceProperty instance. More...
const int	RTI_PERSISTENCE_SERVICE_LOG_VERBOSITY_INFO
	Verbosity level: exceptions + warnings + info. More...
const int	RTI_PERSISTENCE_SERVICE_LOG_VERBOSITY_WARNINGS
	Verbosity level: exceptions + warnings. More...
const int	RTI_PERSISTENCE_SERVICE_LOG_VERBOSITY_EXCEPTIONS
	Verbosity level: exceptions. More...
const int	RTI_PERSISTENCE_SERVICE_LOG_VERBOSITY_SILENT
	Verbosity level: silent. More...
const int	RTI_PERSISTENCE_SERVICE_LOG_VERBOSITY_IGNORE
	Verbosity level: ignore. More...

Detailed Description

This API allows you to embed RTI Persistence Service in your application.

The API allows you to create, configure and start RTI Persistence Service instances from your application. The following code shows the typical use of the API:

struct RTI_PersistenceServiceProperty property =
        RTI_PersistenceServiceProperty_INITIALIZER;
struct RTI_PersistenceService * service = NULL;
 
property.cfg_file = "my_persistence_service_cfg.xml";
property.cfg_name = "default";
...
 
if (!RTI_PersistenceService_initialize_globals()) {
   printf("Error ... \n");
   return -1;
}
 
service = RTI_PersistenceService_new(&property);
if (service == NULL) {
   printf("Error ... \n");
   RTI_PersistenceService_finalize_globals();
   return -1;
}
 
if (!RTI_PersistenceService_start(service)) {
   printf("Error ... \n");
   RTI_PersistenceService_delete(service);
   RTI_PersistenceService_finalize_globals();
   return -1;
}
 
while(keep_running) {
    sleep();
    ...
}
 
RTI_PersistenceService_delete(service);
RTI_PersistenceService_finalize_globals();
 
return 0;

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

To build your application you need to link with the RTI Persistence Service library in $NDDSHOME/lib/<architecture>/

An example is provided at https://github.com/rticommunity/rticonnextdds-examples/tree/release/7.3.0/examples/persistence_service/library_api.

Development Requirements

	Linux Systems	Windows Systems
Link Libraries (Compile Time)	librtipersistenceservice.so	rtipersistenceservice.dll
Shared Libraries (Run Time)	librtidlc.so	rtidlc.dll
	libnddsc.so	nddsc.dll
	libnddscore.so	nddscore.dll
	librtisqlite.so	librtisqlite.dll
	librtimonitoring.so	librtimonitoring.dll
Static Libraries	librtipersistenceservicez.a	rtipersistenceservicez.lib
	librtidlc.a	rtidlc.lib
	libnddsc.a	nddsc.lib
	libnddscore.a	nddscore.lib
	librtisqlite.a	librtisqlite.lib
Headers	persistence/persistence_service.h

NOTE: If you are using debug libraries, remember to add the 'd' suffix to the library name. For shared libraries on macOS systems, the library name is the same as that for Linux except the extension is '.dylib' instead of '.so'.

Enumeration Type Documentation

RTI_PersistenceService_ParticipantKind

enum RTI_PersistenceService_ParticipantKind

Indicates the different kinds of internal DDS_DomainParticipant created by RTI Persistence Service.

For each <participant> tag in the XML configuration, RTI Persistence Service creates two different DDS_DomainParticipant objects.

• RTI_PERSISTENCE_SERVICE_INPUT_PARTICIPANT refers to the DDS_DomainParticipant that contains the DDS_DataReader objects created for a <persistence_group> tag in the XML configuration, that are used by RTI Persistence Service to receive data.
• RTI_PERSISTENCE_SERVICE_OUTPUT_PARTICIPANT refers to the DDS_DomainParticipant that contains the DDS_DataWriter objects created for a <persistence_group> tag in the XML configuration, that are used by RTI Persistence Service to write data.

Function Documentation

RTI_PersistenceService_get_participant_qos()

DDS_Boolean RTI_PersistenceService_get_participant_qos	(	const struct RTI_PersistenceService *	self,
		struct DDS_DomainParticipantQos *	domain_participant_qos,
		const char *	participant_name,
		RTI_PersistenceService_ParticipantKind	participant_kind
	)

Get the DDS_DomainParticipantQos for the internal DDS_DomainParticipant created by RTI Persistence Service.

Parameters

[in]	self	RTI_PersistenceService instance created with RTI_PersistenceService_new
[out]	domain_participant_qos	DDS_DomainParticipantQos the value is copied into. This method returns the value of the first DDS_DomainParticipant found under the <participant> tag identified by participant_name.
[in]	participant_name	Identifies a <participant> tag from the XML configuration
[in]	participant_kind	A RTI_PersistenceService_ParticipantKind that identifies the kind of DDS_DomainParticipant created by RTI Persistence Service

Multi-threading safety:

This method is thread safe as long as the RTI_PersistenceService instance is not deleted at the same time by calling RTI_PersistenceService_delete. Otherwise it is thread safe across calls to any other QoS related Library API methods.

Returns

DDS_BOOLEAN_TRUE on success; DDS_BOOLEAN_FALSE otherwise.

RTI_PersistenceService_set_participant_qos()

DDS_Boolean RTI_PersistenceService_set_participant_qos	(	struct RTI_PersistenceService *	self,
		const char *	participant_name,
		RTI_PersistenceService_ParticipantKind	participant_kind,
		const struct DDS_DomainParticipantQos *	domain_participant_qos
	)

Set the DDS_DomainParticipantQos for the internal DDS_DomainParticipant created by RTI Persistence Service.

Parameters

[in]	self	RTI_PersistenceService instance created with RTI_PersistenceService_new
[in]	participant_name	Identifies a <participant> tag from the XML configuration
[in]	participant_kind	RTI_PersistenceService_ParticipantKind that identifies the kind of DDS_DomainParticipant created by RTI Persistence Service
[in]	domain_participant_qos	DDS_DomainParticipantQos value to set for all DDS_DomainParticipant under the <participant> tag identified by participant_name and participant_kind

Multi-threading safety:

This method is thread safe as long as the RTI_PersistenceService instance is not deleted at the same time by calling RTI_PersistenceService_delete. Otherwise it is thread safe across calls to any other QoS related Library API methods.

Returns

DDS_BOOLEAN_TRUE on success; DDS_BOOLEAN_FALSE otherwise.

RTI_PersistenceService_get_publisher_qos()

DDS_Boolean RTI_PersistenceService_get_publisher_qos	(	const struct RTI_PersistenceService *	self,
		struct DDS_PublisherQos *	publisher_qos,
		const char *	participant_name,
		const char *	persistence_group_name
	)

Get the DDS_PublisherQos for the internal DDS_Publisher created by RTI Persistence Service.

Parameters

[in]	self	RTI_PersistenceService instance created with RTI_PersistenceService_new
[out]	publisher_qos	DDS_PublisherQos the value is copied into. This method returns the value of the first DDS_Publisher found under the <participant>/<persistence_group> tag identified by participant_name and persistence_group_name.
[in]	participant_name	Identifies a <participant> tag from the XML configuration
[in]	persistence_group_name	Identifies a <persistence_group> tag from the XML configuration

Multi-threading safety:

This method is thread safe as long as the RTI_PersistenceService instance is not deleted at the same time by calling RTI_PersistenceService_delete. Otherwise it is thread safe across calls to any other QoS related Library API methods.

Returns

DDS_BOOLEAN_TRUE on success; DDS_BOOLEAN_FALSE otherwise.

RTI_PersistenceService_set_publisher_qos()

DDS_Boolean RTI_PersistenceService_set_publisher_qos	(	struct RTI_PersistenceService *	self,
		const char *	participant_name,
		const char *	persistence_group_name,
		const struct DDS_PublisherQos *	publisher_qos
	)

Set the DDS_PublisherQos for the internal DDS_Publisher created by RTI Persistence Service.

Parameters

[in]	self	RTI_PersistenceService instance created with RTI_PersistenceService_new
[in]	participant_name	Identifies a <participant> tag from the XML configuration
[in]	persistence_group_name	Identifies a <persistence_group> tag from the XML configuration
[in]	publisher_qos	DDS_PublisherQos value to set for all DDS_Publisher under the <participant>/<persistence_group> tag identified by participant_name and persistence_group_name. This value is applied to all the DDS_Publisher created per DDS_Topic if <single_publisher> is set to false.

Multi-threading safety:

This method is thread safe as long as the RTI_PersistenceService instance is not deleted at the same time by calling RTI_PersistenceService_delete. Otherwise it is thread safe across calls to any other QoS related Library API methods.

Returns

DDS_BOOLEAN_TRUE on success; DDS_BOOLEAN_FALSE otherwise.

RTI_PersistenceService_get_subscriber_qos()

DDS_Boolean RTI_PersistenceService_get_subscriber_qos	(	const struct RTI_PersistenceService *	self,
		struct DDS_SubscriberQos *	subscriber_qos,
		const char *	participant_name,
		const char *	persistence_group_name
	)

Get the DDS_SubscriberQos for the internal DDS_Subscriber created by RTI Persistence Service.

Parameters

[in]	self	RTI_PersistenceService instance created with RTI_PersistenceService_new
[out]	subscriber_qos	DDS_SubscriberQos the value is copied into. This method returns the value of the first DDS_Subscriber found under the <participant>/<persistence_group> tag identified by participant_name and persistence_group_name.
[in]	participant_name	Identifies a <participant> tag from the XML configuration
[in]	persistence_group_name	Identifies a <persistence_group> tag from the XML configuration

Multi-threading safety:

This method is thread safe as long as the RTI_PersistenceService instance is not deleted at the same time by calling RTI_PersistenceService_delete. Otherwise it is thread safe across calls to any other QoS related Library API methods.

Returns

DDS_BOOLEAN_TRUE on success; DDS_BOOLEAN_FALSE otherwise.

RTI_PersistenceService_set_subscriber_qos()

DDS_Boolean RTI_PersistenceService_set_subscriber_qos	(	struct RTI_PersistenceService *	self,
		const char *	participant_name,
		const char *	persistence_group_name,
		const struct DDS_SubscriberQos *	subscriber_qos
	)

Set the DDS_SubscriberQos for the internal DDS_Subscriber created by RTI Persistence Service.

Parameters

[in]	self	RTI_PersistenceService instance created with RTI_PersistenceService_new
[in]	participant_name	Identifies a <participant> tag from the XML configuration
[in]	persistence_group_name	Identifies a <persistence_group> tag from the XML configuration
[in]	subscriber_qos	DDS_SubscriberQos value to set for all DDS_Subscriber under the <participant>/<persistence_group> tag identified by participant_name and persistence_group_name. This value is applied to all the DDS_Subscriber created per DDS_Topic if <single_subscriber> is set to false.

Multi-threading safety:

This method is thread safe as long as the RTI_PersistenceService instance is not deleted at the same time by calling RTI_PersistenceService_delete. Otherwise it is thread safe across calls to any other QoS related Library API methods.

Returns

DDS_BOOLEAN_TRUE on success; DDS_BOOLEAN_FALSE otherwise.

RTI_PersistenceService_is_started()

DDS_Boolean RTI_PersistenceService_is_started

(

struct RTI_PersistenceService *

self

)

Indicates if RTI Persistence Service was started by calling RTI_PersistenceService_start.

Parameters

[in]

self

RTI_PersistenceService instance created with RTI_PersistenceService_new

Returns

DDS_BOOLEAN_TRUE if RTI_PersistenceService was started; DDS_BOOLEAN_FALSE otherwise.

RTI_PersistenceService_new()

struct RTI_PersistenceService * RTI_PersistenceService_new

(

struct RTI_PersistenceServiceProperty *

property

)

Create a new RTI Persistence Service instance.

Parameters

[in]

property

The properties to configure RTI Persistence Service

This parameter is copied internally, so the user is responsible for releasing any memory allocated inside this structure.

Returns

An instance of RTI_PersistenceService on success; NULL otherwise.

RTI_PersistenceService_delete()

void RTI_PersistenceService_delete

(

struct RTI_PersistenceService *

self

)

Stop and delete RTI Persistence Service instance.

See also

RTI_PersistenceService_stop

Parameters

[in]

self

RTI_PersistenceService instance created with RTI_PersistenceService_new

RTI_PersistenceService_start()

DDS_Boolean RTI_PersistenceService_start

(

struct RTI_PersistenceService *

self

)

Start RTI Persistence Service.

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

Parameters

[in]

self

RTI_PersistenceService instance created with RTI_PersistenceService_new

Returns

DDS_BOOLEAN_TRUE on success; DDS_BOOLEAN_FALSE otherwise.

Multi-threading safety:

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

RTI_PersistenceService_stop()

DDS_Boolean RTI_PersistenceService_stop

(

struct RTI_PersistenceService *

self

)

Stop RTI Persistence Service.

This function will not return execution control until the instance is fully stopped.

Parameters

[in]

self

RTI_PersistenceService instance created with RTI_PersistenceService_new

Returns

DDS_BOOLEAN_TRUE on success; DDS_BOOLEAN_FALSE otherwise.

Multi-threading safety:

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

RTI_PersistenceService_initialize_globals()

DDS_Boolean RTI_PersistenceService_initialize_globals

(

void

)

Initialize the RTI Persistence Service globals.

This function will initialize RTI Persistence Service globals. This function must be called before creating any RTI Persistence Service instance.

Returns

DDS_BOOLEAN_TRUE on success; DDS_BOOLEAN_FALSE otherwise.

RTI_PersistenceService_finalize_globals()

void RTI_PersistenceService_finalize_globals

(

void

)

Finalize the RTI Persistence Service globals.

This function will finalize RTI Persistence Service globals. This function must be called after all the instances of RTI Persistence Service have been deleted.

Variable Documentation

RTI_PersistenceServiceProperty_INITIALIZER

const struct RTI_PersistenceServiceProperty RTI_PersistenceServiceProperty_INITIALIZER

The initial values for an RTI_PersistenceServiceProperty instance.

RTI_PERSISTENCE_SERVICE_LOG_VERBOSITY_INFO

const int RTI_PERSISTENCE_SERVICE_LOG_VERBOSITY_INFO

Verbosity level: exceptions + warnings + info.

RTI_PERSISTENCE_SERVICE_LOG_VERBOSITY_WARNINGS

const int RTI_PERSISTENCE_SERVICE_LOG_VERBOSITY_WARNINGS

Verbosity level: exceptions + warnings.

RTI_PERSISTENCE_SERVICE_LOG_VERBOSITY_EXCEPTIONS

const int RTI_PERSISTENCE_SERVICE_LOG_VERBOSITY_EXCEPTIONS

Verbosity level: exceptions.

RTI_PERSISTENCE_SERVICE_LOG_VERBOSITY_SILENT

const int RTI_PERSISTENCE_SERVICE_LOG_VERBOSITY_SILENT

Verbosity level: silent.

RTI_PERSISTENCE_SERVICE_LOG_VERBOSITY_IGNORE

const int RTI_PERSISTENCE_SERVICE_LOG_VERBOSITY_IGNORE

Verbosity level: ignore.

This value is meant to be used only with the dds_verbosity field. It instructs RTI Persistence Service to use the existing value set for DDS_DomainParticipantFactory logging verbosity.