diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp index 8b7384e03..fb1478bac 100644 --- a/code/DDSCodeTester.cpp +++ b/code/DDSCodeTester.cpp @@ -5606,6 +5606,126 @@ 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()}; + //!-- + } + { + //!--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 596a8ea14..0eb767d4a 100644 --- a/code/DynamicTypesIDLExamples.idl +++ b/code/DynamicTypesIDLExamples.idl @@ -202,3 +202,39 @@ struct AnnotatedStruct @MyAnnotation(length = 10) string string_var; }; //!-- + +//!--IDL_HELLO_WORLD +struct HelloWorld +{ + unsigned long index; + 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 6a4b26f74..94beb3e85 100644 --- a/code/XMLTester.xml +++ b/code/XMLTester.xml @@ -4570,6 +4570,37 @@ <--> +XML_HELLO_WORLD<--> + + + + +<--> + +XML_BITMASK_DEFAULT_ANNOTATIONS<--> + + + + + + + + + +<--> + +XML_BITSET_DEFAULT_TYPES<--> + + + + + + + + + +<--> + 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..8e63a7723 --- /dev/null +++ b/docs/fastdds/xtypes/type_serializing.rst @@ -0,0 +1,110 @@ +.. 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:: IDL + + .. literalinclude:: /../code/DynamicTypesIDLExamples.idl + :language: omg-idl + :start-after: //!--IDL_HELLO_WORLD + :end-before: //!-- + + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: XML_HELLO_WORLD<--> + :end-before: <--> + + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :start-after: //!--CPP_HELLO_WORLD + :end-before: //!-- + +.. note:: + + The conversion to IDL only supports the annotations: `@bit_bound`, `@extensibility`, `@key`, and `@position`. + +.. note:: + + 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 +++++++++++++++ + +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: //!-- 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::