Documentation to serialize DynamicTypes to IDL (#865)

* Documentation to serialize DynamicTypes to IDL Signed-off-by: tempate <[email protected]> * Review (Irene) - Apply suggestions Signed-off-by: tempate <[email protected]> * Review (Raúl) - Apply suggestions Signed-off-by: tempate <[email protected]> * Review (Juan) - Apply suggestions Signed-off-by: tempate <[email protected]> * Fix - Max line length Signed-off-by: tempate <[email protected]> --------- Signed-off-by: tempate <[email protected]>
eProsima · Jul 12, 2024 · 128a8d1 · 128a8d1
1 parent 2885461
commit 128a8d1
Show file tree

Hide file tree

Showing 5 changed files with 118 additions and 9 deletions.
diff --git a/code/DDSCodeTester.cpp b/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)

diff --git a/docs/03-exports/aliases-api.include b/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>`
 .. }}}
 

diff --git a/docs/fastdds/api_reference/dds_pim/xtypes/utils.rst b/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
diff --git a/docs/fastdds/xtypes/language_binding.rst b/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
 ^^^^^^^^^^^
 

diff --git a/docs/fastdds/xtypes/type_serializing.rst b/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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^