Ref 22890. Feature IDL parsing documentation

Signed-off-by: Eugenio Collado <[email protected]>

Author: EugenioCollado

code/DDSCodeTester.cpp

@@ -2032,6 +2032,45 @@ void dds_topic_examples()
         }
         //!--
     }
+
+    {
+        //DDS_DYNAMIC_TYPES_IDL_PARSING
+        // Create a DomainParticipant in the desired domain
+        DomainParticipant* participant =
+                DomainParticipantFactory::get_instance()->create_participant(0, PARTICIPANT_QOS_DEFAULT);
+        if (nullptr == participant)
+        {
+            // Error
+            return;
+        }
+
+        // Optional: Set the preprocessor to be executed before parsing the IDL
+        DynamicTypeBuilderFactory::get_instance()->set_preprocessor("<optional_path_to_your_preprocessor_executable>");
+
+        // Load the IDL file
+        std::string idl_file = "<path_to_idl>.idl";
+        std::string type_name = "YourType";
+        std::vector<std::string> include_paths;
+        include_paths.push_back("<path_to_included_idl>.idl");
+
+        // Retrieve the instance of the desired type
+        DynamicTypeBuilder::_ref_type dyn_type_builder = 
+                DynamicTypeBuilderFactory::get_instance()->create_type_w_uri(idl_file, type_name, include_paths);
+
+        // Register dynamic type
+        TypeSupport dyn_type_support(new DynamicPubSubType(dyn_type_builder->build()));
+        dyn_type_support.register_type(participant, nullptr);
+
+        // Create a Topic with the registered type.
+        Topic* topic =
+                participant->create_topic("topic_name", dyn_type_support.get_type_name(), TOPIC_QOS_DEFAULT);
+        if (nullptr == topic)
+        {
+            // Error
+            return;
+        }
+        //!--
+    }
 }
 
 void dds_content_filtered_topic_examples()

docs/03-exports/aliases-api.include

@@ -1002,9 +1002,12 @@
 .. |DynamicTypeBuilderFactory::create_sequence_type| replace:: :cpp:func:`DynamicTypeBuilderFactory::create_sequence_type <eprosima::fastdds::dds::DynamicTypeBuilderFactory::create_sequence_type>`
 .. |DynamicTypeBuilderFactory::create_string_type| replace:: :cpp:func:`DynamicTypeBuilderFactory::create_string_type <eprosima::fastdds::dds::DynamicTypeBuilderFactory::create_string_type>`
 .. |DynamicTypeBuilderFactory::create_type_w_type_object| replace:: :cpp:func:`DynamicTypeBuilderFactory::create_type_w_type_object <eprosima::fastdds::dds::DynamicTypeBuilderFactory::create_type_w_type_object>`
+.. |DynamicTypeBuilderFactory::create_type_w_uri| replace:: :cpp:func:`DynamicTypeBuilderFactory::create_type_w_uri <eprosima::fastdds::dds::DynamicTypeBuilderFactory::create_type_w_uri>`
 .. |DynamicTypeBuilderFactory::create_type| replace:: :cpp:func:`DynamicTypeBuilderFactory::create_type <eprosima::fastdds::dds::DynamicTypeBuilderFactory::create_type>`
 .. |DynamicTypeBuilderFactory::create_wstring_type| replace:: :cpp:func:`DynamicTypeBuilderFactory::create_wstring_type <eprosima::fastdds::dds::DynamicTypeBuilderFactory::create_wstring_type>`
 .. |DynamicTypeBuilderFactory::get_primitive_type| replace:: :cpp:func:`DynamicTypeBuilderFactory::get_primitive_type <eprosima::fastdds::dds::DynamicTypeBuilderFactory::get_primitive_type>`
+.. |DynamicTypeBuilderFactory::set_preprocessor| replace:: :cpp:func:`DynamicTypeBuilderFactory::set_preprocessor <eprosima::fastdds::dds::DynamicTypeBuilderFactory::set_preprocessor>`
+
 .. |DynamicTypeMember-api| replace:: :cpp:class:`DynamicTypeMember <eprosima::fastdds::dds::DynamicTypeMember>`
 .. |MemberDescriptor-api| replace:: :cpp:class:`MemberDescriptor <eprosima::fastdds::dds::MemberDescriptor>`
 .. |TypeDescriptor-api| replace:: :cpp:class:`TypeDescriptor <eprosima::fastdds::dds::TypeDescriptor>`

docs/fastdds/xtypes/idl_parsing.rst

@@ -0,0 +1,62 @@
+.. include:: ../../../03-exports/aliases.include
+.. include:: ../../../03-exports/aliases-api.include
+.. include:: ../../03-exports/roles.include
+
+.. _dynamic-types-idl-parsing:
+
+Dynamic Types IDL Parsing
+=========================
+
+*Fast DDS* supports the implementation of |DynamicTypes| for parsing IDL files at runtime to generate dynamic data types.
+The |DynamicTypeBuilderFactory::create_type_w_uri| API allows users to provide a URI pointing to an IDL file.
+Fast DDS will process the file and return the corresponding DynamicTypeBuilder, which can then be used to
+create a DynamicType.
+
+This feature enables applications to dynamically load type definitions from IDL files instead of relying
+solely on pre-generated types or XML profiles. This enhances flexibility, as new data types can be introduced
+without modifying and recompiling the application.
+
+Type definition
+^^^^^^^^^^^^^^^
+Below, the types supported by *eProsima Fast DDS* IDL parsing are presented.
+For further information about the supported |DynamicTypes|, please, refer to :ref:`xtypes_supportedtypes`.
+
+* :ref:`xtypes_supportedtypes_primitive`
+* :ref:`xtypes_supportedtypes_string`
+* :ref:`xtypes_supportedtypes_structure`
+* :ref:`xtypes_supportedtypes_alias`
+* :ref:`xtypes_supportedtypes_array`
+* :ref:`xtypes_supportedtypes_union`
+* :ref:`xtypes_supportedtypes_enumeration`
+* :ref:`xtypes_annotations` (you can see the full table in :ref:`xtypes_builtin_annotations`)
+
+- TODO (Eugenio): arithmetic expressions, union/struct forward declarations, switch-case.
+
+The following types are currently not supported by the IDL parsing feature:
+
+* :ref:`xtypes_supportedtypes_bitmask`
+* :ref:`xtypes_supportedtypes_sequence`
+* :ref:`xtypes_supportedtypes_map`
+* :ref:`xtypes_supportedtypes_bitset`
+
+
+- TODO (Eugenio): module,inheritance, member id
+
+Example
+^^^^^^^
+
+*Fast DDS* application can use dynamic types generated in runtime just by loading the corresponding IDL files into the
+|DynamicTypeBuilderFactory-api| using |DynamicTypeBuilderFactory::create_type_w_uri|.
+After getting the DynamicType, objects of |DynamicPubSubType-api| class might be instantiated and used to write/read
+data.
+
+.. note::
+
+    The preprocessor can be manually selected using |DynamicTypeBuilderFactory::set_preprocessor|
+
+The following snippet shows the previously explained steps:
+
+.. literalinclude:: /../code/DDSCodeTester.cpp
+     :language: c++
+     :start-after: //DDS_DYNAMIC_TYPES_IDL_PARSING
+     :end-before: //!--

docs/fastdds/xtypes/language_binding.rst

@@ -10,7 +10,8 @@ Dynamic Language Binding
 The Dynamic Language Binding API allows to define data types at runtime instead of having the types predefined as it is
 required by the Plain Language Binding.
 This API includes both the type definition and, the getters and setters required to use the defined types.
-Type definition can also be done using a XML configuration file as explained in :ref:`xmldynamictypes` section.
+Type definition can also be done using a XML configuration file as explained in :ref:`xmldynamictypes` section or by
+parsing an IDL file at runtime, as explained in :ref:`dynamic-types-idl-parsing` section.
 
 This section presents first the Dynamic Language Binding API, and then the supported types and specific examples
 defining and using those types.
@@ -896,6 +897,7 @@ The annotation parameter value must be converted to its string representation.
             :start-after: //!--CPP_CUSTOM_ANNOTATION
             :end-before: //!--
 
+.. _xtypes_builtin_annotations:
 
 Builtin annotations
 """""""""""""""""""
@@ -914,71 +916,88 @@ Please, refer to :ref:`builtin annotations <builtin_annotations>` for the comple
       - Dynamic Language Binding API
       - Dynamic Language Binding support
       - XML Dynamic Type profiles support
+      - IDL Parsing Dynamic Type support
     * - :code:`@appendable`
       - |TypeDescriptor-api| :code:`extensibility_kind` property.
       - ✅
       - ❌
+      - ❌
     * - :code:`@bit_bound`
       - |TypeDescriptor-api| :code:`bound` property for :ref:`xtypes_supportedtypes_bitset`. |br|
         |MemberDescriptor-api| :code:`type` property for :ref:`xtypes_supportedtypes_enumeration`.
       - ✅
       - ✅❌ (`Enumeration types`_ not configurable).
+      - TODO (Eugenio)
     * - :code:`@default`
       - |MemberDescriptor-api| :code:`default_value` property.
       - ✅
       - ❌
+      - TODO (Eugenio)
     * - :code:`default_literal`
       - |MemberDescriptor-api| :code:`is_default_label` property.
       - ✅
       - ❌
+      - TODO (Eugenio)
     * - :code:`@extensibility`
       - |TypeDescriptor-api| :code:`extensibility_kind` property.
       - ✅
       - ❌
+      - TODO (Eugenio)
     * - :code:`@external`
       - |MemberDescriptor-api| :code:`is_shared` property.
       - ❌
       - ❌
+      - ❌
     * - :code:`@final`
       - |TypeDescriptor-api| :code:`extensibility_kind` property.
       - ✅
       - ❌
+      - ❌
     * - :code:`@id`
       - |MemberDescriptor-api| :code:`id` property.
       - ✅
       - ❌
+      - TODO (Eugenio)
     * - :code:`@key` / :code:`@Key`
       - |MemberDescriptor-api| :code:`is_key` property.
       - ✅
       - ❌
+      - ❌
     * - :code:`@mutable`
       - |TypeDescriptor-api| :code:`extensibility_kind` property.
       - ✅
       - ❌
+      - ❌
     * - :code:`@nested`
       - |TypeDescriptor-api| :code:`is_nested` property.
       - ❌
       - ❌
+      - TODO (Eugenio)
     * - :code:`@optional`
       - |MemberDescriptor-api| :code:`is_optional` property.
       - ❌
       - ❌
+      - ❌
     * - :code:`@position`
       - |MemberDescriptor-api| :code:`id` property.
       - ✅
       - ✅
+      - TODO (Eugenio)
     * - :code:`@try_construct`
       - |MemberDescriptor-api| :code:`try_construct_kind` property.
       - ❌
       - ❌
+      - TODO (Eugenio)
     * - :code:`@value`
       - |MemberDescriptor-api| :code:`default_value` property.
       - ✅
       - ✅
+      - TODO (Eugenio)
     * - :code:`@verbatim`
       - |VerbatimTextDescriptor-api|
       - ❌
       - ❌
+      - TODO (Eugenio)
 
 .. _xtypes_complextypes:
 

docs/fastdds/xtypes/xtypes.rst

@@ -24,6 +24,7 @@ This specification defines the following concepts:
    /fastdds/xtypes/discovery_matching.rst
    /fastdds/xtypes/language_binding.rst
    /fastdds/xtypes/type_serializing.rst
+   /fastdds/xtypes/idl_parsing.rst
 
 .. note::