From 144d5224418e1dbe51de2262e6e6aec73d2d520a Mon Sep 17 00:00:00 2001 From: tempate Date: Thu, 11 Jul 2024 09:38:58 +0200 Subject: [PATCH 1/5] Documentation to serialize DynamicTypes to IDL Signed-off-by: tempate --- code/DDSCodeTester.cpp | 61 ++++++++++++++++++++++++ docs/03-exports/aliases-api.include | 1 + docs/fastdds/xtypes/language_binding.rst | 2 + docs/fastdds/xtypes/type_serializing.rst | 37 +++++++++++++- 4 files changed, 100 insertions(+), 1 deletion(-) diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp index 793dbfa3e..b528e5107 100644 --- a/code/DDSCodeTester.cpp +++ b/code/DDSCodeTester.cpp @@ -1,3 +1,4 @@ +#include #include #include #include @@ -41,6 +42,7 @@ #include #include #include +#include #include #include #include @@ -53,6 +55,7 @@ #include #include #include +#include #include #include #include @@ -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 received:\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 received:\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 index fba26cf55..369d5a635 100644 --- a/docs/03-exports/aliases-api.include +++ b/docs/03-exports/aliases-api.include @@ -991,6 +991,7 @@ .. |ITypeObjectRegistry-api| replace:: :cpp:class:`ITypeObjectRegistry ` .. |ITypeObjectRegistry::get_type_object| replace:: :cpp:func:`ITypeObjectRegistry::get_type_object ` .. |TypeObjectUtils-api| replace:: :cpp:class:`TypeObjectUtils ` +.. |XTypesUtils-idl_serialize-api| replace:: :cpp:func:`idl_serialize ` .. |XTypesUtils-json_serialize-api| replace:: :cpp:func:`json_serialize ` .. }}} diff --git a/docs/fastdds/xtypes/language_binding.rst b/docs/fastdds/xtypes/language_binding.rst index 009019320..847da3d18 100644 --- 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`. +.. _xtypes_annotations: + Annotations ^^^^^^^^^^^ diff --git a/docs/fastdds/xtypes/type_serializing.rst b/docs/fastdds/xtypes/type_serializing.rst index d224a4e1b..e0db7f9df 100644 --- a/docs/fastdds/xtypes/type_serializing.rst +++ b/docs/fastdds/xtypes/type_serializing.rst @@ -10,6 +10,41 @@ 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 into its IDL representation. + +.. note:: + + The conversion to IDL only supports the :ref:`builtin annotation`: `@bit_bound`, `@extensibility`, `@key`, and `@position`. + +.. warning:: + + The conversion to IDL of a :ref:`xtypes_supportedtypes_bitset` with inheritance merges derived bitsets with their base bitset. + +.. warning:: + + The conversion to IDL dismisses values explicitly set to their default values. + For example, the default :ref:`@bit_bound` value of a :ref:`xtypes_supportedtypes_bitmask` is 32. + If a user were to explicitly set the :ref:`@bit_bound` value of a :ref:`xtypes_supportedtypes_bitmask` to 32 and then serialize the |DynamicType-api| to IDL, the :ref:`@bit_bound` would not be included in the IDL. + +.. _xtypes_serialization_utilities_idl_example: + +Example: Convert a discovered type to IDL format +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following code demonstrates how to use the |XTypesUtils-idl_serialize-api| function in Fast DDS to convert discovered types to their IDL representation. +Each time the subscriber discovers a new reader or writer, it would use 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 -------------------- @@ -241,7 +276,7 @@ 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 498c01ce3a29901a75688d506456075ed50222c8 Mon Sep 17 00:00:00 2001 From: tempate Date: Thu, 11 Jul 2024 10:14:42 +0200 Subject: [PATCH 2/5] Review (Irene) - Apply suggestions Signed-off-by: tempate --- code/DDSCodeTester.cpp | 4 ++-- docs/fastdds/xtypes/type_serializing.rst | 16 ++++++++-------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp index b528e5107..b3bf168c6 100644 --- a/code/DDSCodeTester.cpp +++ b/code/DDSCodeTester.cpp @@ -1189,7 +1189,7 @@ class TypeIntrospectionSubscriber : public DomainParticipantListener idl_serialize(remote_type, idl); // Print IDL representation - std::cout << "Type received:\n" << idl.str() << std::endl; + std::cout << "Type discovered:\n" << idl.str() << std::endl; } /* Custom Callback on_data_writer_discovery */ @@ -1217,7 +1217,7 @@ class TypeIntrospectionSubscriber : public DomainParticipantListener idl_serialize(remote_type, idl); // Print IDL representation - std::cout << "Type received:\n" << idl.str() << std::endl; + std::cout << "Type discovered:\n" << idl.str() << std::endl; } //!-- diff --git a/docs/fastdds/xtypes/type_serializing.rst b/docs/fastdds/xtypes/type_serializing.rst index e0db7f9df..a7a2124d3 100644 --- a/docs/fastdds/xtypes/type_serializing.rst +++ b/docs/fastdds/xtypes/type_serializing.rst @@ -15,29 +15,29 @@ format that can be easily transmitted and reconstructed across different platfor Dynamic Type to IDL ------------------- -The method |XTypesUtils-idl_serialize-api| serializes a |DynamicType-api| object into its IDL representation. +The method |XTypesUtils-idl_serialize-api| serializes a |DynamicType-api| object to its IDL representation. .. note:: - The conversion to IDL only supports the :ref:`builtin annotation`: `@bit_bound`, `@extensibility`, `@key`, and `@position`. + The conversion to IDL only supports the :ref:`builtin annotation`: :code:`@bit_bound`, :code:`@extensibility`, :code:`@key`, and :code:`@position`. .. warning:: - The conversion to IDL of a :ref:`xtypes_supportedtypes_bitset` with inheritance merges derived bitsets with their base bitset. + The conversion to IDL of a :ref:`Bitset` with inheritance merges derived :ref:`Bitsets` with their base :ref:`Bitset`. .. warning:: - The conversion to IDL dismisses values explicitly set to their default values. - For example, the default :ref:`@bit_bound` value of a :ref:`xtypes_supportedtypes_bitmask` is 32. - If a user were to explicitly set the :ref:`@bit_bound` value of a :ref:`xtypes_supportedtypes_bitmask` to 32 and then serialize the |DynamicType-api| to IDL, the :ref:`@bit_bound` would not be included in the IDL. + The conversion to IDL dismisses values explicitly set to their default value. + For example, the default :code:`@bit_bound` value of a :ref:`Bitmask` is 32. + If a user were to explicitly set the :code:`@bit_bound` value of a :ref:`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 code demonstrates how to use the |XTypesUtils-idl_serialize-api| function in Fast DDS to convert discovered types to their IDL representation. -Each time the subscriber discovers a new reader or writer, it would use the |DynamicTypeBuilderFactory-api| to build a |DynamicType-api| and serialize it 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 reader or writer, 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 From 764c294a41a224e2fa3f60577c6e38a4c545e481 Mon Sep 17 00:00:00 2001 From: tempate Date: Thu, 11 Jul 2024 10:15:04 +0200 Subject: [PATCH 3/5] =?UTF-8?q?Review=20(Ra=C3=BAl)=20-=20Apply=20suggesti?= =?UTF-8?q?ons?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: tempate --- docs/fastdds/api_reference/dds_pim/xtypes/utils.rst | 3 +++ docs/fastdds/xtypes/type_serializing.rst | 4 ++-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/fastdds/api_reference/dds_pim/xtypes/utils.rst b/docs/fastdds/api_reference/dds_pim/xtypes/utils.rst index 9d3271bff..d0a613a2d 100644 --- 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/type_serializing.rst b/docs/fastdds/xtypes/type_serializing.rst index a7a2124d3..86cb64027 100644 --- a/docs/fastdds/xtypes/type_serializing.rst +++ b/docs/fastdds/xtypes/type_serializing.rst @@ -19,7 +19,7 @@ The method |XTypesUtils-idl_serialize-api| serializes a |DynamicType-api| object .. note:: - The conversion to IDL only supports the :ref:`builtin annotation`: :code:`@bit_bound`, :code:`@extensibility`, :code:`@key`, and :code:`@position`. + The conversion to IDL only supports the following :ref:`builtin annotations`: :code:`@bit_bound`, :code:`@extensibility`, :code:`@key`, and :code:`@position`. .. warning:: @@ -37,7 +37,7 @@ 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 reader or writer, it uses the |DynamicTypeBuilderFactory-api| to build a |DynamicType-api| and serialize it 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 From db2dc6ca370e0ea3e2baaa75ab8b9e89089e8562 Mon Sep 17 00:00:00 2001 From: tempate Date: Thu, 11 Jul 2024 10:17:07 +0200 Subject: [PATCH 4/5] Review (Juan) - Apply suggestions Signed-off-by: tempate --- docs/fastdds/xtypes/type_serializing.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/fastdds/xtypes/type_serializing.rst b/docs/fastdds/xtypes/type_serializing.rst index 86cb64027..3c53ae5d6 100644 --- a/docs/fastdds/xtypes/type_serializing.rst +++ b/docs/fastdds/xtypes/type_serializing.rst @@ -75,7 +75,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 @@ -95,7 +95,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 @@ -174,7 +174,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 @@ -193,7 +193,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 @@ -213,7 +213,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 @@ -232,7 +232,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 @@ -251,7 +251,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 @@ -270,7 +270,7 @@ 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 From f03bfc52803954294f65c5444ef58541b9cd1e18 Mon Sep 17 00:00:00 2001 From: tempate Date: Thu, 11 Jul 2024 10:36:29 +0200 Subject: [PATCH 5/5] Fix - Max line length Signed-off-by: tempate --- docs/fastdds/xtypes/type_serializing.rst | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/docs/fastdds/xtypes/type_serializing.rst b/docs/fastdds/xtypes/type_serializing.rst index 3c53ae5d6..08b954f58 100644 --- a/docs/fastdds/xtypes/type_serializing.rst +++ b/docs/fastdds/xtypes/type_serializing.rst @@ -19,26 +19,33 @@ The method |XTypesUtils-idl_serialize-api| serializes a |DynamicType-api| object .. note:: - The conversion to IDL only supports the following :ref:`builtin annotations`: :code:`@bit_bound`, :code:`@extensibility`, :code:`@key`, and :code:`@position`. + The conversion to IDL only supports the following :ref:`builtin annotations`: + :code:`@bit_bound`, :code:`@extensibility`, :code:`@key`, and :code:`@position`. .. warning:: - The conversion to IDL of a :ref:`Bitset` with inheritance merges derived :ref:`Bitsets` with their base :ref:`Bitset`. + The conversion to IDL of a :ref:`Bitset` with inheritance merges derived + :ref:`Bitsets` with their base :ref:`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` is 32. - If a user were to explicitly set the :code:`@bit_bound` value of a :ref:`Bitmask` to 32 and then serialize the |DynamicType-api| to IDL, the :code:`@bit_bound` would not be included in the IDL. + If a user were to explicitly set the :code:`@bit_bound` value of a + :ref:`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. +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++