DDS C++ API

Description of RTI Connext DDS Micro C++ support. More...

Modules
	Supported API
	A list of APIs natively supported in C++.

Detailed Description

Description of RTI Connext DDS Micro C++ support.

Overview

RTI Connext DDS Micro's support for the C++ language includes native APIs that are built around the C-based core implementation.

The C++ API has been implemented on top of the existing C API in order to minimize duplication of implementation and maximize reuse of existing features.

The two APIs should not be mixed and an application should only include the header file(s) for either one of the two.

The following sections will present in further detail how existing functionalities have been exposed to C++ applications.

Header Files

Users of RTI Connext DDS Micro's C++ API must include the following header:

#include "rti_me_cpp.hxx"

Inclusion of this header file will set up

C++ users should not include the C headers directly.

All public header files present in the C API have a C++ equivalent, as shown in the following table, which C++ users must include in their place:

C Header	C++ Header	Description
disc_dpde/disc_dpde_discovery_plugin.h	dds_cpp/dds_cpp_dpde.h	Dynamic Endpoint Discovery plugin
disc_dpse/disc_dpse_dpsediscovery.h	dds_cpp/dds_cpp_dpse.h	Dynamic Endpoint Discovery plugin
netio/netio_udp.h	dds_cpp/dds_cpp_netio.h	UDP Transport plugin
rh_sm/rh_sm_history.h	dds_cpp/dds_cpp_rh_sm.h	DataReader History plugin
wh_sm/wh_sm_history.h	dds_cpp/dds_cpp_wh_sm.h	DataWriter History plugin

DCPS Entities

The API makes use of C++ object-oriented features to define several classes that represent the entities of the DDS DCPS. These classes will be used by application in place of the data types defined by the C API. The following table provides a list of the C++ classes and the corresponding C type they replace:

C++ Class	C Type
DDSDomainParticipantFactory	DDS_DomainParticipantFactory
DDSDomainParticipant	DDS_DomainParticipant
DDSPublisher	DDS_Publisher
DDSSubscriber	DDS_Subscriber
DDSTopic	DDS_Topic
DDSDataWriter	DDS_DataWriter
DDSDataReader	DDS_DataReader

Supported operations for each entity are exposed as class instance methods. It is important to note that instances of these classes cannot be used as arguments to the corresponding functions that implement the operations in C.

The page Supported API presents a complete list of the operations supported by the C++ API.

Support Data Types

In addition to DCPS entities, RTI Connext DDS Micro C++ API also includes several support data types which are required to fully leverage the DDS API. These data types include:

• QoS structures for DCPS entities (i.e. DDS_DomainParticipantFactoryQos, DDS_DomainParticipantQos, DDS_PublisherQos, DDS_SubscriberQos, DDS_TopicQos, DDS_DataWriterQos, DDS_DataReaderQos).
• Sequence types (e.g. FooSeq)
• DDS_Duration_t
• DDS_EntityNameQosPolicy
• DDS_Locator_t
• DDS_SampleIdentity_t
• DDS_SequenceNumber_t
• DDS_Time_t
• DDS_WriteParams_t
• DPDE_DiscoveryPluginProperty
• DPSE_DiscoveryPluginProperty
• RT_ComponentFactoryId
• UDP_InterfaceFactoryProperty

Differently from DCPS entities, these data types are not defined independently by the C++ API. Instead, their existing declarations, contained in the header files of the underlying C API, have been conditionally modified to include C++ "features" when accessed from a C++ application.

While this makes it possible to use the existing C functions, users must rely only on the corresponding C++ methods that are defined for each data type.

These "converted" data types define a default constructor which automatically initializes an instance of the type by invoking its C initialize function. A destructor is also provided, which relies on the C finalize function.

C++ Data Types

Some functionalities and data types of the C API have been exposed to C++ by introducing new classes, similarly to the approach followed for DCPS entities.

The following data types must be used by C++ users in place of their C equivalents:

C type	C++ type	Notes
DPDE_DiscoveryFactory	DPDEDiscoveryFactory
DPSE_DiscoveryFactory	DPSEDiscoveryFactory
DPSE_RemoteParticipant	DPSERemoteParticipant
DPSE_RemotePublication	DPSERemotePublication
DPSE_RemoteSubscription	DPSERemoteSubscription
OSAPI_Log	OSAPILog
OSAPI_Trace	OSAPITrace
RHSM_HistoryFactory	RHSMHistoryFactory
RT_Registry_T	RTRegistry	Operation register() has been renamed register_component()
UDP_InterfaceFactory	UDPInterfaceFactory
UDP_InterfaceTable	UDPInterfaceTable
WHSM_HistoryFactory	WHSMHistoryFactory

Note that type DDS_InstanceHandle is a "plain old data" C type, and it's the only type for which its C API functions should be used.

C++ Safety Certification Support

With safety certifiability as a future goal, the RTI Connext DDS Micro C++ API has been designed with the following behavior:

• No polymorphic behavior is included in the API.
• Exceptions are not thrown by the API methods.

Polymorphism

Since polymorphism is avoided by the API, some operations required renaming in order to be properly implemented.

In particular, the DDSDataWriter and DDSDataReader classes both expose methods that accept generic arguments of type void*. The DDS DCPS typically allows these methods to be overloaded by typed subclasses that are generated to support user-defined data types. While this pattern is naturally supported by the C++ language, the exclusion of polymorphism forced the renaming of the generic operations by appending the suffix "_untyped".

These untyped operations can be used with arguments of user-defined data types and they in fact provide the implementation for their "typed" counterpart presented by subclasses.