Documentation for should_endpoints_match callback (#1238)

* Add documentation for custom endpoint matching logic

Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com>

* Apply review

Co-authored-by: Miguel Company <miguelcompany@eprosima.com>
Signed-off-by: Emilio Cuesta Fernandez <emiliocuesta@eprosima.com>

---------

Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com>
Signed-off-by: Emilio Cuesta Fernandez <emiliocuesta@eprosima.com>
Co-authored-by: Miguel Company <miguelcompany@eprosima.com>

Author: emiliocuestaf

code/DDSCodeTester.cpp

@@ -289,6 +289,18 @@ class CustomDomainParticipantListener : public DomainParticipantListener
         }
     }
 
+    bool should_endpoints_match(
+            const DomainParticipant* participant,
+            const eprosima::fastdds::rtps::SubscriptionBuiltinTopicData& reader_info,
+            const eprosima::fastdds::dds::PublicationBuiltinTopicData& writer_info) override
+    {
+        static_cast<void>(participant);
+        // For example, only allow matching between endpoints belonging to different participants.
+        // This prevents intra-participant communication while still allowing
+        // cross-participant communication for endpoints that pass standard QoS checks.
+        return reader_info.participant_guid.guidPrefix != writer_info.participant_guid.guidPrefix;
+    }
+
 };
 //!--
 

docs/03-exports/aliases-api.include

@@ -205,6 +205,7 @@
 .. |DomainParticipantListener::on_data_reader_discovery-api| replace:: :cpp:func:`on_data_reader_discovery()<eprosima::fastdds::dds::DomainParticipantListener::on_data_reader_discovery>`
 .. |DomainParticipantListener::on_data_writer_discovery-api| replace:: :cpp:func:`on_data_writer_discovery()<eprosima::fastdds::dds::DomainParticipantListener::on_data_writer_discovery>`
 .. |DomainParticipantListener::onParticipantAuthentication-api| replace:: :cpp:func:`onParticipantAuthentication()<eprosima::fastdds::dds::DomainParticipantListener::onParticipantAuthentication>`
+.. |DomainParticipantListener::should_endpoints_match-api| replace:: :cpp:func:`should_endpoints_match()<eprosima::fastdds::dds::DomainParticipantListener::should_endpoints_match>`
 
 .. |DomainParticipantQos-api| replace:: :cpp:class:`DomainParticipantQos<eprosima::fastdds::dds::DomainParticipantQos>`
 .. |DomainParticipantQos::allocation-api| replace:: :cpp:func:`allocation()<eprosima::fastdds::dds::DomainParticipantQos::allocation>`

docs/fastdds/dds_layer/domain/domainParticipantListener/domainParticipantListener.rst

@@ -48,6 +48,16 @@ Additionally, DomainParticipantListener adds the following non-standard callback
 * |DomainParticipantListener::onParticipantAuthentication-api|: Informs about the result of the authentication process
   of a remote DomainParticipant (either on failure or success).
 
+* |DomainParticipantListener::should_endpoints_match-api|: Called after standard QoS matching rules have been
+  evaluated for a pair of endpoints (a :ref:`dds_layer_subscriber_dataReader` and a
+  :ref:`dds_layer_publisher_dataWriter` on the same topic with compatible QoS).
+  It allows the application to apply custom matching logic as an additional filter on top of the standard rules.
+  The callback receives the |DomainParticipant-api| calling the listener, a
+  ``SubscriptionBuiltinTopicData`` with the reader information, and a ``PublicationBuiltinTopicData`` with the
+  writer information.
+  Returning ``true`` allows the match to proceed; returning ``false`` prevents it.
+  The default implementation always returns ``true``.
+
 .. important::
 
    For more information about callbacks and its hierarchy, please refer to