[22682] Add RPC over DDS internal API documentation

code/DDSCodeTester.cpp

@@ -12,6 +12,8 @@
 #include <fastdds/dds/domain/DomainParticipantFactory.hpp>
 #include <fastdds/dds/domain/DomainParticipantListener.hpp>
 #include <fastdds/dds/domain/qos/DomainParticipantQos.hpp>
+#include <fastdds/dds/domain/qos/ReplierQos.hpp>
+#include <fastdds/dds/domain/qos/RequesterQos.hpp>
 #include <fastdds/dds/log/FileConsumer.hpp>
 #include <fastdds/dds/log/Log.hpp>
 #include <fastdds/dds/log/OStreamConsumer.hpp>
@@ -22,6 +24,11 @@
 #include <fastdds/dds/publisher/PublisherListener.hpp>
 #include <fastdds/dds/publisher/qos/DataWriterQos.hpp>
 #include <fastdds/dds/publisher/qos/PublisherQos.hpp>
+#include <fastdds/dds/rpc/Replier.hpp>
+#include <fastdds/dds/rpc/Requester.hpp>
+#include <fastdds/dds/rpc/RequestInfo.hpp>
+#include <fastdds/dds/rpc/Service.hpp>
+#include <fastdds/dds/rpc/ServiceTypeSupport.hpp>
 #include <fastdds/dds/subscriber/DataReader.hpp>
 #include <fastdds/dds/subscriber/DataReaderListener.hpp>
 #include <fastdds/dds/subscriber/qos/DataReaderQos.hpp>
@@ -49,19 +56,20 @@
 #include <fastdds/rtps/transport/network/AllowedNetworkInterface.hpp>
 #include <fastdds/rtps/transport/network/BlockedNetworkInterface.hpp>
 #include <fastdds/rtps/transport/network/NetmaskFilterKind.hpp>
+#include <fastdds/rtps/transport/NetworkBuffer.hpp>
 #include <fastdds/rtps/transport/shared_mem/SharedMemTransportDescriptor.hpp>
 #include <fastdds/rtps/transport/TCPTransportDescriptor.hpp>
 #include <fastdds/rtps/transport/TCPv4TransportDescriptor.hpp>
 #include <fastdds/rtps/transport/TCPv6TransportDescriptor.hpp>
 #include <fastdds/rtps/transport/UDPv4TransportDescriptor.hpp>
 #include <fastdds/rtps/transport/UDPv6TransportDescriptor.hpp>
-#include <fastdds/rtps/transport/NetworkBuffer.hpp>
 #include <fastdds/statistics/dds/domain/DomainParticipant.hpp>
 #include <fastdds/statistics/dds/publisher/qos/DataWriterQos.hpp>
 #include <fastdds/statistics/topic_names.hpp>
 #include <fastdds/utils/IPLocator.hpp>
 
 using namespace eprosima::fastdds::dds;
+using namespace eprosima::fastdds::dds::rpc;
 
 class CustomChainingTransportDescriptor : public eprosima::fastdds::rtps::ChainingTransportDescriptor
 {
@@ -7785,6 +7793,196 @@ void pubsub_api_example_create_entities()
     //!--
 }
 
+void rpcdds_internal_api_examples()
+{
+    {
+        //!--CREATE_DELETE_SERVICE_EXAMPLE
+        TypeSupport request_type_support = TypeSupport(new CustomDataType());
+        TypeSupport reply_type_support = TypeSupport(new CustomDataType());
+        DomainParticipant* participant =
+            DomainParticipantFactory::get_instance()->create_participant(0, PARTICIPANT_QOS_DEFAULT);
+
+        // Create a new ServiceTypeSupport instance
+        ServiceTypeSupport service_type_support(request_type_support, reply_type_support);
+
+        // Register the ServiceTypeSupport instance in a DomainParticipant
+        ReturnCode_t ret;
+        ret = participant->register_service_type(service_type_support, "ServiceType");
+        if (RETCODE_OK != ret)
+        {
+            // Error
+            return;
+        }
+
+        // Create a new Service instance
+        Service* service = participant->create_service("Service", "ServiceType");
+        if (!service)
+        {
+            // Error
+            return;
+        }
+
+        // ... Create Requesters and Repliers here
+
+        // Delete the created Service
+        ret = participant->delete_service(service);
+        if (RETCODE_OK != ret)
+        {
+            // Error
+            return;
+        }
+        //!--
+    }
+
+    {
+        DomainParticipant* participant =
+            DomainParticipantFactory::get_instance()->create_participant(0, PARTICIPANT_QOS_DEFAULT);
+        TypeSupport request_type_support = TypeSupport(new CustomDataType());
+        TypeSupport reply_type_support = TypeSupport(new CustomDataType());
+        ServiceTypeSupport service_type_support(request_type_support, reply_type_support);
+        participant->register_service_type(service_type_support, "ServiceType");
+        participant->create_service("Service", "ServiceType");
+
+        //!--RPC_REQUESTER_EXAMPLE
+        ReturnCode_t ret;
+
+        // Get a valid service
+        Service* service = participant->find_service("Service");
+        if (!service)
+        {
+            // Error
+            return;
+        }
+
+        /* Create a new Requester instance */
+        // Configure the Requester QoS
+        RequesterQos requester_qos;
+        requester_qos.service_name = "Service";
+        requester_qos.request_type = "Foo";
+        requester_qos.reply_type = "Foo";
+        requester_qos.request_topic_name = "Service_Request";
+        requester_qos.reply_topic_name = "Service_Reply";
+        requester_qos.writer_qos.reliability().kind = RELIABLE_RELIABILITY_QOS;
+        requester_qos.reader_qos.reliability().kind = RELIABLE_RELIABILITY_QOS;
+
+        Requester* requester = participant->create_service_requester(service, requester_qos);
+        if (!requester)
+        {
+            // Error
+            return;
+        }
+
+        /* Send a new Request sample and check if a received Reply sample is a match */
+        RequestInfo expected_request_info;
+        RequestInfo received_request_info;
+        // Create a new Request sample
+        void* request_data = request_type_support->create_data();
+        ret = requester->send_request(request_data, expected_request_info);
+        if (RETCODE_OK != ret)
+        {
+            // Error
+            return;
+        }
+
+        // ... Wait here until a Reply sample is received
+
+        void* data = nullptr;
+        ret = requester->take_reply(data, received_request_info); 
+        if (RETCODE_OK != ret)
+        {
+            // Error
+            return;
+        }
+
+        if (expected_request_info.related_sample_identity == received_request_info.related_sample_identity)
+        {
+          // Received Reply sample is associated to the sent Request sample
+        }
+
+        // Delete created Requester
+        ret = participant->delete_service_requester(requester->get_service_name(), requester);
+        if (RETCODE_OK != ret)
+        {
+          // Error
+          return;
+        }
+        //!--
+    }
+
+    {
+        DomainParticipant* participant =
+            DomainParticipantFactory::get_instance()->create_participant(0, PARTICIPANT_QOS_DEFAULT);
+        TypeSupport request_type_support = TypeSupport(new CustomDataType());
+        TypeSupport reply_type_support = TypeSupport(new CustomDataType());
+        ServiceTypeSupport service_type_support(request_type_support, reply_type_support);
+        participant->register_service_type(service_type_support, "ServiceType");
+        participant->create_service("Service", "ServiceType");
+
+        //!--RPC_REPLIER_EXAMPLE
+        ReturnCode_t ret;
+
+        // Get a valid service
+        Service* service = participant->find_service("Service");
+        if (!service)
+        {
+            // Error
+            return;
+        }
+
+        /* Create a new Replier instance */
+        // Configure the Replier QoS
+        ReplierQos replier_qos;
+        replier_qos.service_name = "Service";
+        replier_qos.request_type = "Foo";
+        replier_qos.reply_type = "Foo";
+        replier_qos.request_topic_name = "Service_Request";
+        replier_qos.reply_topic_name = "Service_Reply";
+        replier_qos.writer_qos.reliability().kind = RELIABLE_RELIABILITY_QOS;
+        replier_qos.reader_qos.reliability().kind = RELIABLE_RELIABILITY_QOS;
+
+        Replier* replier = participant->create_service_replier(service, replier_qos);
+        if (!replier)
+        {
+            // Error
+            return;
+        }
+
+        /* Take a received Request sample and send a new Reply sample */
+        RequestInfo received_request_info;
+
+        // ... Wait here until a Request sample is received
+
+        void* received_data = nullptr;
+
+        ret = replier->take_request(received_data, received_request_info);
+        if (RETCODE_OK != ret)
+        {
+            // Error
+            return;
+        }
+
+        // ... Process received data 
+
+        // Send a Reply with the received related_sample_identity
+        void* reply_data = reply_type_support->create_data();
+        ret = replier->send_reply(reply_data, received_request_info);
+        if (RETCODE_OK != ret)
+        {
+            // Error
+            return;
+        }
+
+        /* Delete created Replier */
+        ret = participant->delete_service_replier(replier->get_service_name(), replier);
+        if (RETCODE_OK != ret)
+        {
+          // Error
+          return;
+        }
+        //!--
+    }
+}
+
 int main(
         int argc,
         const char** argv)

docs/03-exports/aliases-api.include

@@ -159,6 +159,17 @@
 .. |DomainParticipant::delete_contained_entities-api| replace:: :cpp:func:`delete_contained_entities()<eprosima::fastdds::dds::DomainParticipant::delete_contained_entities>`
 .. |DomainParticipant::create_topic_with_profile-api| replace:: :cpp:func:`create_topic_with_profile()<eprosima::fastdds::dds::DomainParticipant::create_topic_with_profile>`
 .. |DomainParticipant::find_topic| replace:: :cpp:func:`find_topic()<eprosima::fastdds::dds::DomainParticipant::find_topic>`
+.. |DomainParticipant::create_service-api| replace:: :cpp:func:`DomainParticipant::create_service()<eprosima::fastdds::dds::DomainParticipant::create_service>`
+.. |DomainParticipant::find_service-api| replace:: :cpp:func:`DomainParticipant::find_service()<eprosima::fastdds::dds::DomainParticipant::find_service>`
+.. |DomainParticipant::delete_service-api| replace:: :cpp:func:`DomainParticipant::delete_service()<eprosima::fastdds::dds::DomainParticipant::delete_service>`
+.. |DomainParticipant::create_service_requester-api| replace:: :cpp:func:`DomainParticipant::create_service_requester()<eprosima::fastdds::dds::DomainParticipant::create_service_requester>`
+.. |DomainParticipant::delete_service_requester-api| replace:: :cpp:func:`DomainParticipant::delete_service_requester()<eprosima::fastdds::dds::DomainParticipant::delete_service_requester>`
+.. |DomainParticipant::create_service_replier-api| replace:: :cpp:func:`DomainParticipant::create_service_replier()<eprosima::fastdds::dds::DomainParticipant::create_service_replier>`
+.. |DomainParticipant::delete_service_replier-api| replace:: :cpp:func:`DomainParticipant::delete_service_replier()<eprosima::fastdds::dds::DomainParticipant::delete_service_replier>`
+.. |DomainParticipant::register_service_type-api| replace:: :cpp:func:`register_service_type()<eprosima::fastdds::dds::DomainParticipant::register_service_type>`
+.. |DomainParticipant::unregister_service_type-api| replace:: :cpp:func:`unregister_service_type()<eprosima::fastdds::dds::DomainParticipant::unregister_service_type>`
+.. |DomainParticipant::find_service_type-api| replace:: :cpp:func:`find_service_type()<eprosima::fastdds::dds::DomainParticipant::find_service_type>`
+
 .. |DomainParticipant::ignore_participant-api| replace:: :cpp:func:`ignore_participant()<eprosima::fastdds::dds::DomainParticipant::ignore_participant>`
 .. |DomainParticipant::enable-monitor-service-api| replace:: :cpp:func:`enable_monitor_service()<eprosima::fastdds::dds::DomainParticipant::enable_monitor_service>`
 .. |DomainParticipant::disable-monitor-service-api| replace:: :cpp:func:`disable_monitor_service()<eprosima::fastdds::dds::DomainParticipant::disable_monitor_service>`
@@ -333,6 +344,25 @@
 .. |Entity::get_instance_handle-api| replace:: :cpp:func:`get_instance_handle()<eprosima::fastdds::dds::Entity::get_instance_handle>`
 .. |Entity::get_status_changes-api| replace:: :cpp:func:`get_status_changes()<eprosima::fastdds::dds::Entity::get_status_changes>`
 
+.. |Replier-api| replace:: :cpp:class:`Replier<eprosima::fastdds::dds::rpc::Replier>`
+.. |Replier::get_replier_writer-api| replace:: :cpp:func:`Replier::get_replier_writer()<eprosima::fastdds::dds::Replier::get_replier_writer>`
+.. |Replier::get_replier_reader-api| replace:: :cpp:func:`Replier::get_replier_reader()<eprosima::fastdds::dds::Replier::get_replier_reader>`
+.. |Replier::get_service_name-api| replace:: :cpp:func:`Replier::get_service_name()<eprosima::fastdds::dds::rpc::Replier::get_service_name>`
+.. |Replier::take_request-api| replace:: :cpp:func:`Replier::take_request()<eprosima::fastdds::dds::rpc::Replier::take_request>`
+.. |Replier::send_reply-api| replace:: :cpp:func:`Replier::send_reply()<eprosima::fastdds::dds::rpc::Replier::send_reply>`
+.. |ReplierQos-api| replace:: :cpp:class:`ReplierQos<eprosima::fastdds::dds::ReplierQos>`
+.. |Requester-api| replace:: :cpp:class:`Requester<eprosima::fastdds::dds::rpc::Requester>`
+.. |Requester::get_service_name-api| replace:: :cpp:func:`Requester::get_service_name()<eprosima::fastdds::dds::rpc::Requester::get_service_name>`
+.. |Requester::get_requester_writer-api| replace:: :cpp:func:`Requester::get_requester_writer()<eprosima::fastdds::dds::Requester::get_requester_writer>`
+.. |Requester::get_requester_reader-api| replace:: :cpp:func:`Requester::get_requester_reader()<eprosima::fastdds::dds::Requester::get_requester_reader>`
+.. |Requester::take_reply-api| replace:: :cpp:func:`Requester::take_reply()<eprosima::fastdds::dds::rpc::Requester::take_reply>`
+.. |Requester::send_request-api| replace:: :cpp:func:`Requester::send_request()<eprosima::fastdds::dds::rpc::Requester::send_request>`
+.. |RequesterQos-api| replace:: :cpp:class:`RequesterQos<eprosima::fastdds::dds::RequesterQos>`
+.. |Service-api| replace:: :cpp:class:`Service<eprosima::fastdds::dds::rpc::Service>`
+.. |RPCEntity-api| replace:: :cpp:class:`RPCEntity<eprosima::fastdds::dds::rpc::RPCEntity>`
+.. |RequestInfo-api| replace:: :cpp:type:`RequestInfo<eprosima::fastdds::dds::rpc::RequestInfo>`
+.. |ServiceTypeSupport-api| replace:: :cpp:class:`ServiceTypeSupport<eprosima::fastdds::dds::rpc::ServiceTypeSupport>`
+
 .. |DestinationOrderQosPolicyKind-api| replace:: :cpp:enum:`DestinationOrderQosPolicyKind<eprosima::fastdds::dds::DestinationOrderQosPolicyKind>`
 .. |BY_RECEPTION_TIMESTAMP| replace:: :cpp:enumerator:`BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS<eprosima::fastdds::dds::DestinationOrderQosPolicyKind::BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS>`
 .. |BY_SOURCE_TIMESTAMP| replace:: :cpp:enumerator:`BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS<eprosima::fastdds::dds::DestinationOrderQosPolicyKind::BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS>`

docs/03-exports/aliases.include

@@ -89,3 +89,7 @@
 .. |WireProtocolConfigQos| replace:: :ref:`WireProtocolConfigQos<wireprotocolconfigqos>`
 .. |WriterDataLifecycleQosPolicy| replace:: :ref:`WriterDataLifecycleQosPolicy<writerdatalifecycleqospolicy>`
 .. |WriterResourceLimitsQos| replace:: :ref:`WriterResourceLimitsQos<writerresourcelimitsqos>`
+.. |Service| replace:: :ref:`Service<rpc_service>`
+.. |Replier| replace:: :ref:`Replier<rpc_replier>`
+.. |Listeners| replace:: :ref:`Listeners<dds_layer_core_entity_commonchars_listener>`
+.. |WaitSet| replace:: :ref:`WaitSet<dds_layer_core_waitsets>`

docs/fastdds/api_reference/dds_pim/dds_pim.rst

@@ -14,3 +14,4 @@ Data Distribution Service (DDS) Data-Centric Publish-Subscribe (DCPS) Platform I
    /fastdds/api_reference/dds_pim/subscriber/subscriber.rst
    /fastdds/api_reference/dds_pim/topic/topic.rst
    /fastdds/api_reference/dds_pim/xtypes/xtypes.rst
+   /fastdds/api_reference/dds_pim/rpc/rpc.rst

docs/fastdds/api_reference/dds_pim/rpc/replier.rst

@@ -0,0 +1,10 @@
+.. _api_pim_replier:
+
+.. rst-class:: api-ref
+
+Replier
+----------
+
+.. doxygenclass:: eprosima::fastdds::dds::rpc::Replier
+    :project: FastDDS
+    :members:

docs/fastdds/api_reference/dds_pim/rpc/replierqos.rst

@@ -0,0 +1,10 @@
+.. _api_pim_replierqos:
+
+.. rst-class:: api-ref
+
+ReplierQos
+----------
+
+.. doxygenclass:: eprosima::fastdds::dds::ReplierQos
+    :project: FastDDS
+    :members:

docs/fastdds/api_reference/dds_pim/rpc/requester.rst

@@ -0,0 +1,10 @@
+.. _api_pim_requester:
+
+.. rst-class:: api-ref
+
+Requester
+---------
+
+.. doxygenclass:: eprosima::fastdds::dds::rpc::Requester
+    :project: FastDDS
+    :members:

docs/fastdds/api_reference/dds_pim/rpc/requesterqos.rst

@@ -0,0 +1,10 @@
+.. _api_pim_requesterqos:
+
+.. rst-class:: api-ref
+
+RequesterQos
+------------
+
+.. doxygenclass:: eprosima::fastdds::dds::RequesterQos
+    :project: FastDDS
+    :members:

docs/fastdds/api_reference/dds_pim/rpc/requestinfo.rst

@@ -0,0 +1,9 @@
+.. _api_pim_requestinfo:
+
+.. rst-class:: api-ref
+
+RequestInfo
+-----------
+
+.. doxygentypedef:: eprosima::fastdds::dds::rpc::RequestInfo
+    :project: FastDDS

docs/fastdds/api_reference/dds_pim/rpc/rpc.rst

@@ -0,0 +1,14 @@
+RPC over DDS
+============
+
+.. toctree::
+    :titlesonly:
+
+    /fastdds/api_reference/dds_pim/rpc/replier.rst
+    /fastdds/api_reference/dds_pim/rpc/replierqos.rst
+    /fastdds/api_reference/dds_pim/rpc/requester.rst
+    /fastdds/api_reference/dds_pim/rpc/requesterqos.rst
+    /fastdds/api_reference/dds_pim/rpc/requestinfo.rst
+    /fastdds/api_reference/dds_pim/rpc/rpcentity.rst
+    /fastdds/api_reference/dds_pim/rpc/service.rst
+    /fastdds/api_reference/dds_pim/rpc/servicetypesupport.rst

docs/fastdds/api_reference/dds_pim/rpc/rpcentity.rst

@@ -0,0 +1,10 @@
+.. _api_pim_rpcentity:
+
+.. rst-class:: api-ref
+
+RPCEntity
+---------
+
+.. doxygenclass:: eprosima::fastdds::dds::rpc::RPCEntity
+    :project: FastDDS
+    :members:

docs/fastdds/api_reference/dds_pim/rpc/service.rst

@@ -0,0 +1,10 @@
+.. _api_pim_service:
+
+.. rst-class:: api-ref
+
+Service
+-------
+
+.. doxygenclass:: eprosima::fastdds::dds::rpc::Service
+    :project: FastDDS
+    :members:

docs/fastdds/api_reference/dds_pim/rpc/servicetypesupport.rst

@@ -0,0 +1,10 @@
+.. _api_pim_servicetypesupport:
+
+.. rst-class:: api-ref
+
+ServiceTypeSupport
+-------------------
+
+.. doxygenclass:: eprosima::fastdds::dds::rpc::ServiceTypeSupport
+    :project: FastDDS
+    :members: