Skip to content

Commit 128a8d1

Browse files
tempatetempate
authored
Documentation to serialize DynamicTypes to IDL (#865)
* Documentation to serialize DynamicTypes to IDL Signed-off-by: tempate <danieldiaz@eprosima.com> * Review (Irene) - Apply suggestions Signed-off-by: tempate <danieldiaz@eprosima.com> * Review (Raúl) - Apply suggestions Signed-off-by: tempate <danieldiaz@eprosima.com> * Review (Juan) - Apply suggestions Signed-off-by: tempate <danieldiaz@eprosima.com> * Fix - Max line length Signed-off-by: tempate <danieldiaz@eprosima.com> --------- Signed-off-by: tempate <danieldiaz@eprosima.com>
1 parent 2885461 commit 128a8d1

5 files changed

Lines changed: 118 additions & 9 deletions

File tree

‎code/DDSCodeTester.cpp‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
#include <iostream>
12
#include <memory>
23
#include <sstream>
34
#include <thread>
@@ -41,6 +42,7 @@
4142
#include <fastdds/rtps/attributes/ThreadSettings.hpp>
4243
#include <fastdds/rtps/common/WriteParams.hpp>
4344
#include <fastdds/rtps/history/IPayloadPool.hpp>
45+
#include <fastdds/rtps/reader/ReaderDiscoveryInfo.hpp>
4446
#include <fastdds/rtps/transport/ChainingTransport.hpp>
4547
#include <fastdds/rtps/transport/ChainingTransportDescriptor.hpp>
4648
#include <fastdds/rtps/transport/network/AllowedNetworkInterface.hpp>
@@ -53,6 +55,7 @@
5355
#include <fastdds/rtps/transport/UDPv4TransportDescriptor.hpp>
5456
#include <fastdds/rtps/transport/UDPv6TransportDescriptor.hpp>
5557
#include <fastdds/rtps/transport/NetworkBuffer.hpp>
58+
#include <fastdds/rtps/writer/WriterDiscoveryInfo.hpp>
5659
#include <fastdds/statistics/dds/domain/DomainParticipant.hpp>
5760
#include <fastdds/statistics/dds/publisher/qos/DataWriterQos.hpp>
5861
#include <fastdds/statistics/topic_names.hpp>
@@ -1160,6 +1163,64 @@ class RemoteDiscoveryDomainParticipantListener : public DomainParticipantListene
11601163
//!--REMOTE_TYPE_INTROSPECTION
11611164
class TypeIntrospectionSubscriber : public DomainParticipantListener
11621165
{
1166+
//!--DYNTYPE_IDL_SERIALIZATION
1167+
/* Custom Callback on_data_reader_discovery */
1168+
void on_data_reader_discovery(
1169+
DomainParticipant* /* participant */,
1170+
eprosima::fastdds::rtps::ReaderDiscoveryInfo&& info,
1171+
bool& /* should_be_ignored */) override
1172+
{
1173+
// Get remote type information
1174+
xtypes::TypeObject remote_type_object;
1175+
if (RETCODE_OK != DomainParticipantFactory::get_instance()->type_object_registry().get_type_object(
1176+
info.info.type_information().type_information.complete().typeid_with_size().type_id(),
1177+
remote_type_object))
1178+
{
1179+
// Error
1180+
return;
1181+
}
1182+
1183+
// Build remotely discovered type
1184+
DynamicType::_ref_type remote_type = DynamicTypeBuilderFactory::get_instance()->create_type_w_type_object(
1185+
remote_type_object)->build();
1186+
1187+
// Serialize DynamicType into its IDL representation
1188+
std::stringstream idl;
1189+
idl_serialize(remote_type, idl);
1190+
1191+
// Print IDL representation
1192+
std::cout << "Type discovered:\n" << idl.str() << std::endl;
1193+
}
1194+
1195+
/* Custom Callback on_data_writer_discovery */
1196+
void on_data_writer_discovery(
1197+
DomainParticipant* /* participant */,
1198+
eprosima::fastdds::rtps::WriterDiscoveryInfo&& info,
1199+
bool& /* should_be_ignored */) override
1200+
{
1201+
// Get remote type information
1202+
xtypes::TypeObject remote_type_object;
1203+
if (RETCODE_OK != DomainParticipantFactory::get_instance()->type_object_registry().get_type_object(
1204+
info.info.type_information().type_information.complete().typeid_with_size().type_id(),
1205+
remote_type_object))
1206+
{
1207+
// Error
1208+
return;
1209+
}
1210+
1211+
// Build remotely discovered type
1212+
DynamicType::_ref_type remote_type = DynamicTypeBuilderFactory::get_instance()->create_type_w_type_object(
1213+
remote_type_object)->build();
1214+
1215+
// Serialize DynamicType into its IDL representation
1216+
std::stringstream idl;
1217+
idl_serialize(remote_type, idl);
1218+
1219+
// Print IDL representation
1220+
std::cout << "Type discovered:\n" << idl.str() << std::endl;
1221+
}
1222+
//!--
1223+
11631224
//!--DYNDATA_JSON_SERIALIZATION
11641225
void on_data_available(
11651226
DataReader* reader)

‎docs/03-exports/aliases-api.include‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -991,6 +991,7 @@
991991
.. |ITypeObjectRegistry-api| replace:: :cpp:class:`ITypeObjectRegistry <eprosima::fastdds::dds::xtypes::ITypeObjectRegistry>`
992992
.. |ITypeObjectRegistry::get_type_object| replace:: :cpp:func:`ITypeObjectRegistry::get_type_object <eprosima::fastdds::dds::xtypes::ITypeObjectRegistry::get_type_object>`
993993
.. |TypeObjectUtils-api| replace:: :cpp:class:`TypeObjectUtils <eprosima::fastdds::dds::xtypes::TypeObjectUtils>`
994+
.. |XTypesUtils-idl_serialize-api| replace:: :cpp:func:`idl_serialize <eprosima::fastdds::dds::idl_serialize>`
994995
.. |XTypesUtils-json_serialize-api| replace:: :cpp:func:`json_serialize <eprosima::fastdds::dds::json_serialize>`
995996
.. }}}
996997

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,8 @@
55
Utils
66
-----
77

8+
.. doxygenfunction:: eprosima::fastdds::dds::idl_serialize
9+
:project: FastDDS
10+
811
.. doxygenfunction:: eprosima::fastdds::dds::json_serialize
912
:project: FastDDS

‎docs/fastdds/xtypes/language_binding.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -836,6 +836,8 @@ modifies the involved bits instead of the full primitive value.
836836
For a detailed explanation about the XML definition of this type, please refer to
837837
:ref:`XML Bitset Types<xmldynamictypes_bitset>`.
838838

839+
.. _xtypes_annotations:
840+
839841
Annotations
840842
^^^^^^^^^^^
841843

‎docs/fastdds/xtypes/type_serializing.rst‎

Lines changed: 51 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,48 @@ within distributed systems.
1010
Serialization is a crucial process in data distribution services, as it converts complex data structures into a
1111
format that can be easily transmitted and reconstructed across different platforms and programming environments.
1212

13+
.. _xtypes_serialization_utilities_idl:
14+
15+
Dynamic Type to IDL
16+
-------------------
17+
18+
The method |XTypesUtils-idl_serialize-api| serializes a |DynamicType-api| object to its IDL representation.
19+
20+
.. note::
21+
22+
The conversion to IDL only supports the following :ref:`builtin annotations<builtin_annotations>`:
23+
:code:`@bit_bound`, :code:`@extensibility`, :code:`@key`, and :code:`@position`.
24+
25+
.. warning::
26+
27+
The conversion to IDL of a :ref:`Bitset<xtypes_supportedtypes_bitset>` with inheritance merges derived
28+
:ref:`Bitsets<xtypes_supportedtypes_bitset>` with their base :ref:`Bitset<xtypes_supportedtypes_bitset>`.
29+
30+
.. warning::
31+
32+
The conversion to IDL dismisses values explicitly set to their default value.
33+
For example, the default :code:`@bit_bound` value of a :ref:`Bitmask<xtypes_supportedtypes_bitmask>` is 32.
34+
If a user were to explicitly set the :code:`@bit_bound` value of a
35+
:ref:`Bitmask<xtypes_supportedtypes_bitmask>` to 32 and then serialize the |DynamicType-api| to IDL, the
36+
:code:`@bit_bound` would not be included in the IDL.
37+
38+
.. _xtypes_serialization_utilities_idl_example:
39+
40+
Example: Convert a discovered type to IDL format
41+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
42+
43+
The following example demonstrates how to use the |XTypesUtils-idl_serialize-api| method in Fast DDS to convert
44+
discovered types to IDL format.
45+
Each time the subscriber discovers a new |DataReader-api| or |DataWriter-api|, it uses the
46+
|DynamicTypeBuilderFactory-api| to build a |DynamicType-api| and serialize it to IDL format.
47+
Please refer to :ref:`use-case-remote-type-discovery-and-matching` section for more details on how to implement
48+
remote type discovery.
49+
50+
.. literalinclude:: /../code/DDSCodeTester.cpp
51+
:language: c++
52+
:start-after: //!--DYNTYPE_IDL_SERIALIZATION
53+
:end-before: //!--
54+
1355
DynamicData to JSON
1456
--------------------
1557

@@ -40,7 +82,7 @@ Below is an example of the definition of primitive types in IDL:
4082
:start-after: //!--IDL_PRIMITIVES
4183
:end-before: //!--
4284

43-
The previous |DynamicData-api| object corresponding to the type represented above
85+
A |DynamicData-api| object corresponding to the type represented above
4486
would be serialized as follows:
4587

4688
.. literalinclude:: /../code/json/Primitives.json
@@ -60,7 +102,7 @@ The following example shows the definition of string types in IDL:
60102
:start-after: //!--IDL_STRINGS
61103
:end-before: //!--
62104

63-
The previous |DynamicData-api| object corresponding to the type represented above
105+
A |DynamicData-api| object corresponding to the type represented above
64106
would be serialized as follows:
65107

66108
.. literalinclude:: /../code/json/Strings.json
@@ -139,7 +181,7 @@ Below is an example of the definition of sequence types in IDL:
139181
:start-after: //!--IDL_SEQUENCES
140182
:end-before: //!--
141183

142-
The previous |DynamicData-api| object corresponding to the type represented above
184+
A |DynamicData-api| object corresponding to the type represented above
143185
would be serialized as follows:
144186

145187
.. literalinclude:: /../code/json/Sequences.json
@@ -158,7 +200,7 @@ The following example shows the definition of array types in IDL:
158200
:start-after: //!--IDL_ARRAYS_JSON
159201
:end-before: //!--
160202

161-
The previous |DynamicData-api| object corresponding to the type represented above
203+
A |DynamicData-api| object corresponding to the type represented above
162204
would be serialized as follows:
163205

164206
.. literalinclude:: /../code/json/Arrays.json
@@ -178,7 +220,7 @@ Below is an example of the definition of map types in IDL:
178220
:start-after: //!--IDL_MAPS
179221
:end-before: //!--
180222

181-
The previous |DynamicData-api| object corresponding to the type represented above
223+
A |DynamicData-api| object corresponding to the type represented above
182224
would be serialized as follows:
183225

184226
.. literalinclude:: /../code/json/Maps.json
@@ -197,7 +239,7 @@ Here is an example of the definition of structure types in IDL:
197239
:start-after: //!--IDL_STRUCT
198240
:end-before: //!--
199241

200-
The previous |DynamicData-api| object corresponding to the type represented above
242+
A |DynamicData-api| object corresponding to the type represented above
201243
would be serialized as follows:
202244

203245
.. literalinclude:: /../code/json/Structs.json
@@ -216,7 +258,7 @@ Below is an example of the definition of union types in IDL:
216258
:start-after: //!--IDL_UNION
217259
:end-before: //!--
218260

219-
The previous |DynamicData-api| object corresponding to the type represented above
261+
A |DynamicData-api| object corresponding to the type represented above
220262
would be serialized as follows:
221263

222264
.. literalinclude:: /../code/json/Unions.json
@@ -235,13 +277,13 @@ Below is an example of the definition of bitset types in IDL:
235277
:start-after: //!--IDL_BITSET_JSON
236278
:end-before: //!--
237279

238-
The previous |DynamicData-api| object corresponding to the type represented above
280+
A |DynamicData-api| object corresponding to the type represented above
239281
would be serialized as follows:
240282

241283
.. literalinclude:: /../code/json/Bitsets.json
242284
:language: json
243285

244-
.. _xtypes_serialization_utilities_example:
286+
.. _xtypes_serialization_utilities_json_example:
245287

246288
Example: Convert received data into JSON format
247289
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

0 commit comments

Comments
 (0)