From ccbaf76f85d62f6712e407ab3b380644c2dd7c83 Mon Sep 17 00:00:00 2001 From: tempate Date: Fri, 21 Jun 2024 11:00:10 +0200 Subject: [PATCH 1/4] Documentation to serialize DynamicTypes to IDL Signed-off-by: tempate --- code/DDSCodeTester.cpp | 26 ++++++++++++++ code/DynamicTypesIDLExamples.idl | 8 +++++ code/XMLTester.xml | 7 ++++ docs/fastdds/xtypes/language_binding.rst | 2 ++ docs/fastdds/xtypes/type_serializing.rst | 45 ++++++++++++++++++++++++ docs/fastdds/xtypes/xtypes.rst | 1 + 6 files changed, 89 insertions(+) create mode 100644 docs/fastdds/xtypes/type_serializing.rst diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp index 8b7384e03..974817317 100644 --- a/code/DDSCodeTester.cpp +++ b/code/DDSCodeTester.cpp @@ -5606,6 +5606,32 @@ void dynamictypes_examples() data->return_loaned_value(loan_data); //!-- } + { + //!--CPP_HELLO_WORLD + // Create struct type + TypeDescriptor::_ref_type struct_type_descriptor {traits::make_shared()}; + struct_type_descriptor->kind(TK_STRUCTURE); + struct_type_descriptor->name("HelloWorld"); + DynamicTypeBuilder::_ref_type struct_builder {DynamicTypeBuilderFactory::get_instance()-> + create_type(struct_type_descriptor)}; + + // The type consists of two members, and index and a message. Add members to the struct. + MemberDescriptor::_ref_type index_member_descriptor {traits::make_shared()}; + index_member_descriptor->name("index"); + index_member_descriptor->type(DynamicTypeBuilderFactory::get_instance()-> + get_primitive_type(TK_UINT32)); + struct_builder->add_member(index_member_descriptor); + + MemberDescriptor::_ref_type message_member_descriptor {traits::make_shared()}; + message_member_descriptor->name("message"); + message_member_descriptor->type(DynamicTypeBuilderFactory::get_instance()-> + create_string_type(static_cast(LENGTH_UNLIMITED))->build()); + struct_builder->add_member(message_member_descriptor); + + // Build the type + DynamicType::_ref_type struct_type {struct_builder->build()}; + //!-- + } } void xml_profiles_examples() diff --git a/code/DynamicTypesIDLExamples.idl b/code/DynamicTypesIDLExamples.idl index 596a8ea14..80ab54269 100644 --- a/code/DynamicTypesIDLExamples.idl +++ b/code/DynamicTypesIDLExamples.idl @@ -202,3 +202,11 @@ struct AnnotatedStruct @MyAnnotation(length = 10) string string_var; }; //!-- + +//!--IDL_HELLO_WORLD +struct HelloWorld +{ + unsigned long index; + string message; +}; +//!-- diff --git a/code/XMLTester.xml b/code/XMLTester.xml index 6a4b26f74..153861cd7 100644 --- a/code/XMLTester.xml +++ b/code/XMLTester.xml @@ -4570,6 +4570,13 @@ <--> +XML_HELLO_WORLD<--> + + + + +<--> + diff --git a/docs/fastdds/xtypes/language_binding.rst b/docs/fastdds/xtypes/language_binding.rst index ca31225c8..8c9898982 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 new file mode 100644 index 000000000..bff0fb1a0 --- /dev/null +++ b/docs/fastdds/xtypes/type_serializing.rst @@ -0,0 +1,45 @@ +.. include:: ../../03-exports/aliases-api.include + +.. _xtypes_type_serializing: + +Dynamic Type Serializing +======================== + +Fast-DDS provides methods to serialize DynamicType objects. + +Dynamic Type to IDL +------------------- + +The method `idl_serialize` converts a DynamicType object into an IDL string. +The following `DynamicType` object would be serialized as follows: + +.. tabs:: + + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :start-after: //!--CPP_HELLO_WORLD + :end-before: //!-- + + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: XML_HELLO_WORLD<--> + :end-before: <--> + + .. tab:: IDL + + .. literalinclude:: /../code/DynamicTypesIDLExamples.idl + :language: omg-idl + :start-after: //!--IDL_HELLO_WORLD + :end-before: //!-- + +.. note:: + + The conversion to IDL does not support :ref:`xtypes_supportedtypes_alias`, :ref:`xtypes_supportedtypes_bitset`, :ref:`xtypes_supportedtypes_bitmask`, or :ref:`xtypes_annotations`. + +.. note:: + + The conversion to IDL does not support inheritance of :ref:`xtypes_supportedtypes_structure`. diff --git a/docs/fastdds/xtypes/xtypes.rst b/docs/fastdds/xtypes/xtypes.rst index b9b48b652..500a3e139 100644 --- a/docs/fastdds/xtypes/xtypes.rst +++ b/docs/fastdds/xtypes/xtypes.rst @@ -23,6 +23,7 @@ This specification defines the following concepts: /fastdds/xtypes/discovery_matching.rst /fastdds/xtypes/language_binding.rst + /fastdds/xtypes/type_serializing.rst .. note:: From e62b1bf062bf4781302bd4f8a207d0034edd2d2d Mon Sep 17 00:00:00 2001 From: tempate Date: Tue, 25 Jun 2024 14:28:25 +0200 Subject: [PATCH 2/4] Support TK_ALIAS, TK_BITMASK, TK_BITSET and a few built-in annotations Signed-off-by: tempate --- docs/fastdds/xtypes/type_serializing.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/fastdds/xtypes/type_serializing.rst b/docs/fastdds/xtypes/type_serializing.rst index bff0fb1a0..2e017fe64 100644 --- a/docs/fastdds/xtypes/type_serializing.rst +++ b/docs/fastdds/xtypes/type_serializing.rst @@ -5,12 +5,12 @@ Dynamic Type Serializing ======================== -Fast-DDS provides methods to serialize DynamicType objects. +Fast-DDS provides methods to serialize `DynamicType` objects. Dynamic Type to IDL ------------------- -The method `idl_serialize` converts a DynamicType object into an IDL string. +The method `idl_serialize` converts a `DynamicType` object into an IDL string. The following `DynamicType` object would be serialized as follows: .. tabs:: @@ -38,8 +38,8 @@ The following `DynamicType` object would be serialized as follows: .. note:: - The conversion to IDL does not support :ref:`xtypes_supportedtypes_alias`, :ref:`xtypes_supportedtypes_bitset`, :ref:`xtypes_supportedtypes_bitmask`, or :ref:`xtypes_annotations`. + The conversion to IDL only supports the annotations: `@bit_bound`, `@extensibility`, `@key`, `@position`. .. note:: - The conversion to IDL does not support inheritance of :ref:`xtypes_supportedtypes_structure`. + The conversion to IDL does not support inheritance of :ref:`xtypes_supportedtypes_structure` or of :ref:`xtypes_supportedtypes_bitset`. From 593552be886d233549e2410c6a797b65708a9732 Mon Sep 17 00:00:00 2001 From: tempate Date: Tue, 25 Jun 2024 14:41:30 +0200 Subject: [PATCH 3/4] Omit explicitly set default values Signed-off-by: tempate --- code/DDSCodeTester.cpp | 94 ++++++++++++++++++++++++ code/DynamicTypesIDLExamples.idl | 28 +++++++ code/XMLTester.xml | 24 ++++++ docs/fastdds/xtypes/type_serializing.rst | 67 ++++++++++++++++- 4 files changed, 212 insertions(+), 1 deletion(-) diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp index 974817317..fb1478bac 100644 --- a/code/DDSCodeTester.cpp +++ b/code/DDSCodeTester.cpp @@ -5632,6 +5632,100 @@ void dynamictypes_examples() DynamicType::_ref_type struct_type {struct_builder->build()}; //!-- } + { + //!--CPP_BITMASK_DEFAULT_ANNOTATIONS + // Define a struct type to contain a bitmask + TypeDescriptor::_ref_type type_descriptor {traits::make_shared()}; + type_descriptor->kind(TK_STRUCTURE); + type_descriptor->name("BitmaskStruct"); + DynamicTypeBuilder::_ref_type struct_builder {DynamicTypeBuilderFactory::get_instance()-> + create_type(type_descriptor)}; + + // Define the bitmask type + DynamicTypeBuilder::_ref_type bitmask_builder {DynamicTypeBuilderFactory::get_instance()->create_bitmask_type(32)}; + + /* Alternative + TypeDescriptor::_ref_type bitmask_type_descriptor {traits::make_shared()}; + bitmask_type_descriptor->kind(TK_BITMASK); + bitmask_type_descriptor->name("MyBitMask"); + bitmask_type_descriptor->element_type(DynamicTypeBuilderFactory::get_instance()->get_primitive_type( + TK_BOOLEAN)); + bitmask_type_descriptor->bound().push_back(32); + DynamicTypeBuilder::_ref_type bitmask_builder {DynamicTypeBuilderFactory::get_instance()->create_type( + bitmask_type_descriptor)}; + */ + + // Add bitfield members to the bitmask type + MemberDescriptor::_ref_type bitfield_member_descriptor {traits::make_shared()}; + bitfield_member_descriptor->type(DynamicTypeBuilderFactory::get_instance()->get_primitive_type(TK_BOOLEAN)); + bitfield_member_descriptor->name("flag0"); + bitfield_member_descriptor->id(0); + bitmask_builder->add_member(bitfield_member_descriptor); + bitfield_member_descriptor = traits::make_shared(); + bitfield_member_descriptor->type(DynamicTypeBuilderFactory::get_instance()->get_primitive_type(TK_BOOLEAN)); + bitfield_member_descriptor->name("flag1"); + bitfield_member_descriptor->id(2); + bitmask_builder->add_member(bitfield_member_descriptor); + bitfield_member_descriptor = traits::make_shared(); + bitfield_member_descriptor->type(DynamicTypeBuilderFactory::get_instance()->get_primitive_type(TK_BOOLEAN)); + bitfield_member_descriptor->name("flag2"); + bitmask_builder->add_member(bitfield_member_descriptor); + // Build the bitmask type + DynamicType::_ref_type bitmask_type = bitmask_builder->build(); + + // Add a bitmask member to the struct + MemberDescriptor::_ref_type member_descriptor {traits::make_shared()}; + member_descriptor->name("my_bitmask"); + member_descriptor->type(bitmask_type); + struct_builder->add_member(member_descriptor); + // Build the struct type + DynamicType::_ref_type struct_type {struct_builder->build()}; + //!-- + } + { + //!--CPP_BITSET_DEFAULT_TYPES + // Define a struct type to contain the bitset + TypeDescriptor::_ref_type struct_type_descriptor {traits::make_shared()}; + struct_type_descriptor->kind(TK_STRUCTURE); + struct_type_descriptor->name("BitsetStruct"); + DynamicTypeBuilder::_ref_type struct_builder {DynamicTypeBuilderFactory::get_instance()->create_type( + struct_type_descriptor)}; + + // Define type for my_bitset + TypeDescriptor::_ref_type bitset_type_descriptor {traits::make_shared()}; + bitset_type_descriptor->kind(TK_BITSET); + bitset_type_descriptor->name("MyBitSet"); + bitset_type_descriptor->bound({3, 1, 12}); + DynamicTypeBuilder::_ref_type bitset_builder {DynamicTypeBuilderFactory::get_instance()->create_type( + bitset_type_descriptor)}; + // Add members to the bitset type + MemberDescriptor::_ref_type bitset_member_descriptor {traits::make_shared()}; + bitset_member_descriptor->name("a"); + bitset_member_descriptor->type(DynamicTypeBuilderFactory::get_instance()->get_primitive_type(TK_UINT8)); + bitset_member_descriptor->id(0); + bitset_builder->add_member(bitset_member_descriptor); + bitset_member_descriptor = traits::make_shared(); + bitset_member_descriptor->name("b"); + bitset_member_descriptor->type(DynamicTypeBuilderFactory::get_instance()->get_primitive_type(TK_BOOLEAN)); + bitset_member_descriptor->id(3); + bitset_builder->add_member(bitset_member_descriptor); + bitset_member_descriptor = traits::make_shared(); + bitset_member_descriptor->name("c"); + bitset_member_descriptor->type(DynamicTypeBuilderFactory::get_instance()->get_primitive_type(TK_INT16)); + bitset_member_descriptor->id(4); + bitset_builder->add_member(bitset_member_descriptor); + // Build the bitset type + DynamicType::_ref_type bitset_type = bitset_builder->build(); + + // Add the bitset member to the struct + MemberDescriptor::_ref_type member_descriptor {traits::make_shared()}; + member_descriptor->name("my_bitset"); + member_descriptor->type(bitset_type); + struct_builder->add_member(member_descriptor); + // Build the struct type + DynamicType::_ref_type struct_type {struct_builder->build()}; + //!-- + } } void xml_profiles_examples() diff --git a/code/DynamicTypesIDLExamples.idl b/code/DynamicTypesIDLExamples.idl index 80ab54269..0eb767d4a 100644 --- a/code/DynamicTypesIDLExamples.idl +++ b/code/DynamicTypesIDLExamples.idl @@ -210,3 +210,31 @@ struct HelloWorld string message; }; //!-- + +//!--IDL_BITMASK_DEFAULT_ANNOTATIONS +bitmask MyBitMask +{ + flag0, + @position(2) flag1, + flag2 +}; + +struct BitmaskStruct +{ + MyBitMask my_bitmask; +}; +//!-- + +//!--IDL_BITSET_DEFAULT_TYPES +bitset MyBitSet +{ + bitfield<3> a; + bitfield<1> b; + bitfield<12, short> c; +}; + +struct BitsetStruct +{ + MyBitSet my_bitset; +}; +//!-- diff --git a/code/XMLTester.xml b/code/XMLTester.xml index 153861cd7..94beb3e85 100644 --- a/code/XMLTester.xml +++ b/code/XMLTester.xml @@ -4577,6 +4577,30 @@ <--> +XML_BITMASK_DEFAULT_ANNOTATIONS<--> + + + + + + + + + +<--> + +XML_BITSET_DEFAULT_TYPES<--> + + + + + + + + + +<--> + diff --git a/docs/fastdds/xtypes/type_serializing.rst b/docs/fastdds/xtypes/type_serializing.rst index 2e017fe64..d7825fdc3 100644 --- a/docs/fastdds/xtypes/type_serializing.rst +++ b/docs/fastdds/xtypes/type_serializing.rst @@ -38,8 +38,73 @@ The following `DynamicType` object would be serialized as follows: .. note:: - The conversion to IDL only supports the annotations: `@bit_bound`, `@extensibility`, `@key`, `@position`. + The conversion to IDL only supports the annotations: `@bit_bound`, `@extensibility`, `@key`, and `@position`. .. note:: The conversion to IDL does not support inheritance of :ref:`xtypes_supportedtypes_structure` or of :ref:`xtypes_supportedtypes_bitset`. + +Default values +++++++++++++++ + +In general, if a user explicitly sets a value to its default value, the serialization to IDL will not set the value explicitly. + +Example: annotations +^^^^^^^^^^^^^^^^^^^^ + +In the following example, `MyBitMask` has two explicit annotations (`@bit_bound(32)` and `@position(0)`) that do not appear in the IDL, since they both are the default values. +The annotation `@position(2)` does appear, since it is not the default. +Furthermore, the annotation `@position(2)` increases the position of `flag2` to `3`, but the `@position(3)` annotation does not appear since by default the position is one more than the previous position. + +.. tabs:: + + .. tab:: IDL + + .. literalinclude:: /../code/DynamicTypesIDLExamples.idl + :language: omg-idl + :start-after: //!--IDL_BITMASK_DEFAULT_ANNOTATIONS + :end-before: //!-- + + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: XML_BITMASK_DEFAULT_ANNOTATIONS<--> + :end-before: <--> + + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :start-after: //!--CPP_BITMASK_DEFAULT_ANNOTATIONS + :end-before: //!-- + +Example: bitsets +^^^^^^^^^^^^^^^^ + +In the following example, the three bitfields of `MyBitSet` explicitly specify their type. +Two of the types (`unsigned char` and `boolean`) are the default and, therefore, do not appear in the IDL. +The type `short` does appear since it is not the default type for a 12-bit long variable. + +.. tabs:: + + .. tab:: IDL + + .. literalinclude:: /../code/DynamicTypesIDLExamples.idl + :language: omg-idl + :start-after: //!--IDL_BITSET_DEFAULT_TYPES + :end-before: //!-- + + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: XML_BITSET_DEFAULT_TYPES<--> + :end-before: <--> + + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :start-after: //!--CPP_BITSET_DEFAULT_TYPES + :end-before: //!-- From 4f159a4cd22069005886dc5d2856833e2b56174c Mon Sep 17 00:00:00 2001 From: tempate Date: Tue, 25 Jun 2024 16:00:05 +0200 Subject: [PATCH 4/4] Support inheritance in TK_STRUCT & TK_BITSET Signed-off-by: tempate --- docs/fastdds/xtypes/type_serializing.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/fastdds/xtypes/type_serializing.rst b/docs/fastdds/xtypes/type_serializing.rst index d7825fdc3..8e63a7723 100644 --- a/docs/fastdds/xtypes/type_serializing.rst +++ b/docs/fastdds/xtypes/type_serializing.rst @@ -15,11 +15,11 @@ The following `DynamicType` object would be serialized as follows: .. tabs:: - .. tab:: C++ + .. tab:: IDL - .. literalinclude:: /../code/DDSCodeTester.cpp - :language: c++ - :start-after: //!--CPP_HELLO_WORLD + .. literalinclude:: /../code/DynamicTypesIDLExamples.idl + :language: omg-idl + :start-after: //!--IDL_HELLO_WORLD :end-before: //!-- .. tab:: XML @@ -29,11 +29,11 @@ The following `DynamicType` object would be serialized as follows: :start-after: XML_HELLO_WORLD<--> :end-before: <--> - .. tab:: IDL + .. tab:: C++ - .. literalinclude:: /../code/DynamicTypesIDLExamples.idl - :language: omg-idl - :start-after: //!--IDL_HELLO_WORLD + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :start-after: //!--CPP_HELLO_WORLD :end-before: //!-- .. note:: @@ -42,7 +42,7 @@ The following `DynamicType` object would be serialized as follows: .. note:: - The conversion to IDL does not support inheritance of :ref:`xtypes_supportedtypes_structure` or of :ref:`xtypes_supportedtypes_bitset`. + The conversion to IDL supports inheritance of :ref:`xtypes_supportedtypes_struct` fully, and of :ref:`xtypes_supportedtypes_bitset` at the cost of collapsing the base and derived bitsets into a single bitset. Default values ++++++++++++++