[21051] Documentation to serialize DynamicTypes to IDL

code/DDSCodeTester.cpp

@@ -1,3 +1,4 @@
+#include <iostream>
 #include <memory>
 #include <sstream>
 #include <thread>
@@ -41,6 +42,7 @@
 #include <fastdds/rtps/attributes/ThreadSettings.hpp>
 #include <fastdds/rtps/common/WriteParams.hpp>
 #include <fastdds/rtps/history/IPayloadPool.hpp>
+#include <fastdds/rtps/reader/ReaderDiscoveryInfo.hpp>
 #include <fastdds/rtps/transport/ChainingTransport.hpp>
 #include <fastdds/rtps/transport/ChainingTransportDescriptor.hpp>
 #include <fastdds/rtps/transport/network/AllowedNetworkInterface.hpp>
@@ -53,6 +55,7 @@
 #include <fastdds/rtps/transport/UDPv4TransportDescriptor.hpp>
 #include <fastdds/rtps/transport/UDPv6TransportDescriptor.hpp>
 #include <fastdds/rtps/transport/NetworkBuffer.hpp>
+#include <fastdds/rtps/writer/WriterDiscoveryInfo.hpp>
 #include <fastdds/statistics/dds/domain/DomainParticipant.hpp>
 #include <fastdds/statistics/dds/publisher/qos/DataWriterQos.hpp>
 #include <fastdds/statistics/topic_names.hpp>
@@ -1160,6 +1163,64 @@ class RemoteDiscoveryDomainParticipantListener : public DomainParticipantListene
 //!--REMOTE_TYPE_INTROSPECTION
 class TypeIntrospectionSubscriber : public DomainParticipantListener
 {
+    //!--DYNTYPE_IDL_SERIALIZATION
+    /* Custom Callback on_data_reader_discovery */
+    void on_data_reader_discovery(
+            DomainParticipant* /* participant */,
+            eprosima::fastdds::rtps::ReaderDiscoveryInfo&& info,
+            bool& /* should_be_ignored */) override
+    {
+        // Get remote type information
+        xtypes::TypeObject remote_type_object;
+        if (RETCODE_OK != DomainParticipantFactory::get_instance()->type_object_registry().get_type_object(
+                    info.info.type_information().type_information.complete().typeid_with_size().type_id(),
+                    remote_type_object))
+        {
+            // Error
+            return;
+        }
+
+        // Build remotely discovered type
+        DynamicType::_ref_type remote_type = DynamicTypeBuilderFactory::get_instance()->create_type_w_type_object(
+            remote_type_object)->build();
+
+        // Serialize DynamicType into its IDL representation
+        std::stringstream idl;
+        idl_serialize(remote_type, idl);
+
+        // Print IDL representation
+        std::cout << "Type discovered:\n" << idl.str() << std::endl;
+    }
+
+    /* Custom Callback on_data_writer_discovery */
+    void on_data_writer_discovery(
+            DomainParticipant* /* participant */,
+            eprosima::fastdds::rtps::WriterDiscoveryInfo&& info,
+            bool& /* should_be_ignored */) override
+    {
+        // Get remote type information
+        xtypes::TypeObject remote_type_object;
+        if (RETCODE_OK != DomainParticipantFactory::get_instance()->type_object_registry().get_type_object(
+                    info.info.type_information().type_information.complete().typeid_with_size().type_id(),
+                    remote_type_object))
+        {
+            // Error
+            return;
+        }
+
+        // Build remotely discovered type
+        DynamicType::_ref_type remote_type = DynamicTypeBuilderFactory::get_instance()->create_type_w_type_object(
+            remote_type_object)->build();
+
+        // Serialize DynamicType into its IDL representation
+        std::stringstream idl;
+        idl_serialize(remote_type, idl);
+
+        // Print IDL representation
+        std::cout << "Type discovered:\n" << idl.str() << std::endl;
+    }
+    //!--
+
     //!--DYNDATA_JSON_SERIALIZATION
     void on_data_available(
             DataReader* reader)

docs/03-exports/aliases-api.include

@@ -991,6 +991,7 @@
 .. |ITypeObjectRegistry-api| replace:: :cpp:class:`ITypeObjectRegistry <eprosima::fastdds::dds::xtypes::ITypeObjectRegistry>`
 .. |ITypeObjectRegistry::get_type_object| replace:: :cpp:func:`ITypeObjectRegistry::get_type_object <eprosima::fastdds::dds::xtypes::ITypeObjectRegistry::get_type_object>`
 .. |TypeObjectUtils-api| replace:: :cpp:class:`TypeObjectUtils <eprosima::fastdds::dds::xtypes::TypeObjectUtils>`
+.. |XTypesUtils-idl_serialize-api| replace:: :cpp:func:`idl_serialize <eprosima::fastdds::dds::idl_serialize>`
 .. |XTypesUtils-json_serialize-api| replace:: :cpp:func:`json_serialize <eprosima::fastdds::dds::json_serialize>`
 .. }}}
 

docs/fastdds/api_reference/dds_pim/xtypes/utils.rst

@@ -5,5 +5,8 @@
 Utils
 -----
 
+.. doxygenfunction:: eprosima::fastdds::dds::idl_serialize
+   :project: FastDDS
+
 .. doxygenfunction:: eprosima::fastdds::dds::json_serialize
    :project: FastDDS

docs/fastdds/xtypes/language_binding.rst

@@ -836,6 +836,8 @@ modifies the involved bits instead of the full primitive value.
 For a detailed explanation about the XML definition of this type, please refer to
 :ref:`XML Bitset Types<xmldynamictypes_bitset>`.
 
+.. _xtypes_annotations:
+
 Annotations
 ^^^^^^^^^^^
 

docs/fastdds/xtypes/type_serializing.rst

@@ -10,6 +10,48 @@ within distributed systems.
 Serialization is a crucial process in data distribution services, as it converts complex data structures into a
 format that can be easily transmitted and reconstructed across different platforms and programming environments.
 
+.. _xtypes_serialization_utilities_idl:
+
+Dynamic Type to IDL
+-------------------
+
+The method |XTypesUtils-idl_serialize-api| serializes a |DynamicType-api| object to its IDL representation.
+
+.. note::
+
+    The conversion to IDL only supports the following :ref:`builtin annotations<builtin_annotations>`:
+    :code:`@bit_bound`, :code:`@extensibility`, :code:`@key`, and :code:`@position`.
+
+.. warning::
+
+    The conversion to IDL of a :ref:`Bitset<xtypes_supportedtypes_bitset>` with inheritance merges derived
+    :ref:`Bitsets<xtypes_supportedtypes_bitset>` with their base :ref:`Bitset<xtypes_supportedtypes_bitset>`.
+
+.. warning::
+
+    The conversion to IDL dismisses values explicitly set to their default value.
+    For example, the default :code:`@bit_bound` value of a :ref:`Bitmask<xtypes_supportedtypes_bitmask>` is 32.
+    If a user were to explicitly set the :code:`@bit_bound` value of a
+    :ref:`Bitmask<xtypes_supportedtypes_bitmask>` to 32 and then serialize the |DynamicType-api| to IDL, the
+    :code:`@bit_bound` would not be included in the IDL.
+
+.. _xtypes_serialization_utilities_idl_example:
+
+Example: Convert a discovered type to IDL format
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following example demonstrates how to use the |XTypesUtils-idl_serialize-api| method in Fast DDS to convert
+discovered types to IDL format.
+Each time the subscriber discovers a new |DataReader-api| or |DataWriter-api|, it uses the
+|DynamicTypeBuilderFactory-api| to build a |DynamicType-api| and serialize it to IDL format.
+Please refer to :ref:`use-case-remote-type-discovery-and-matching` section for more details on how to implement
+remote type discovery.
+
+.. literalinclude:: /../code/DDSCodeTester.cpp
+    :language: c++
+    :start-after: //!--DYNTYPE_IDL_SERIALIZATION
+    :end-before: //!--
+
 DynamicData to JSON
 --------------------
 
@@ -40,7 +82,7 @@ Below is an example of the definition of primitive types in IDL:
     :start-after: //!--IDL_PRIMITIVES
     :end-before: //!--
 
-The previous |DynamicData-api| object corresponding to the type represented above
+A |DynamicData-api| object corresponding to the type represented above
 would be serialized as follows:
 
 .. literalinclude:: /../code/json/Primitives.json
@@ -60,7 +102,7 @@ The following example shows the definition of string types in IDL:
     :start-after: //!--IDL_STRINGS
     :end-before: //!--
 
-The previous |DynamicData-api| object corresponding to the type represented above
+A |DynamicData-api| object corresponding to the type represented above
 would be serialized as follows:
 
 .. literalinclude:: /../code/json/Strings.json
@@ -139,7 +181,7 @@ Below is an example of the definition of sequence types in IDL:
     :start-after: //!--IDL_SEQUENCES
     :end-before: //!--
 
-The previous |DynamicData-api| object corresponding to the type represented above
+A |DynamicData-api| object corresponding to the type represented above
 would be serialized as follows:
 
 .. literalinclude:: /../code/json/Sequences.json
@@ -158,7 +200,7 @@ The following example shows the definition of array types in IDL:
     :start-after: //!--IDL_ARRAYS_JSON
     :end-before: //!--
 
-The previous |DynamicData-api| object corresponding to the type represented above
+A |DynamicData-api| object corresponding to the type represented above
 would be serialized as follows:
 
 .. literalinclude:: /../code/json/Arrays.json
@@ -178,7 +220,7 @@ Below is an example of the definition of map types in IDL:
     :start-after: //!--IDL_MAPS
     :end-before: //!--
 
-The previous |DynamicData-api| object corresponding to the type represented above
+A |DynamicData-api| object corresponding to the type represented above
 would be serialized as follows:
 
 .. literalinclude:: /../code/json/Maps.json
@@ -197,7 +239,7 @@ Here is an example of the definition of structure types in IDL:
     :start-after: //!--IDL_STRUCT
     :end-before: //!--
 
-The previous |DynamicData-api| object corresponding to the type represented above
+A |DynamicData-api| object corresponding to the type represented above
 would be serialized as follows:
 
 .. literalinclude:: /../code/json/Structs.json
@@ -216,7 +258,7 @@ Below is an example of the definition of union types in IDL:
     :start-after: //!--IDL_UNION
     :end-before: //!--
 
-The previous |DynamicData-api| object corresponding to the type represented above
+A |DynamicData-api| object corresponding to the type represented above
 would be serialized as follows:
 
 .. literalinclude:: /../code/json/Unions.json
@@ -235,13 +277,13 @@ Below is an example of the definition of bitset types in IDL:
     :start-after: //!--IDL_BITSET_JSON
     :end-before: //!--
 
-The previous |DynamicData-api| object corresponding to the type represented above
+A |DynamicData-api| object corresponding to the type represented above
 would be serialized as follows:
 
 .. literalinclude:: /../code/json/Bitsets.json
     :language: json
 
-.. _xtypes_serialization_utilities_example:
+.. _xtypes_serialization_utilities_json_example:
 
 Example: Convert received data into JSON format
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^