From 327dfa03c8453b39896055d10c1c8c691eb5b48b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ricardo=20Gonz=C3=A1lez?= Date: Wed, 27 Sep 2023 11:45:16 +0200 Subject: [PATCH] Documentation about Fast-CDR v2.0.0 and new annotations (#550) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Refs #18678. Fix compilation Signed-off-by: Ricardo González Moreno * Refs #18678. Document optional and extensibility Signed-off-by: Ricardo González Moreno * Refs #18687. Update option extrastg Signed-off-by: Ricardo González Moreno * Refs #18687. Add suggested note Signed-off-by: Ricardo González Moreno * Refs #18687. Improve hightlighing Signed-off-by: Ricardo González Moreno * Refs #18687. Add link to custom template example Signed-off-by: Ricardo González Moreno * Refs #18687. Fix spelling Signed-off-by: Ricardo González Moreno * Refs #18687. Apply suggestions Signed-off-by: Ricardo González Moreno * Refs #18687. Apply suggestions Signed-off-by: Ricardo González Moreno * Refs #18687. Apply suggestion Signed-off-by: Ricardo González Moreno * Refs #18687. Fixes Signed-off-by: Ricardo González Moreno * Refs #18687. Apply suggestion Signed-off-by: Ricardo González Moreno --------- Signed-off-by: Ricardo González Moreno --- code/CMakeLists.txt | 2 +- code/DDSCodeTester.cpp | 7 +- .../Examples/C++/DDSHelloWorld/CMakeLists.txt | 12 +- .../C++/DDSHelloWorld/src/HelloWorld.cxx | 113 +++++--------- .../C++/DDSHelloWorld/src/HelloWorld.h | 146 ++++++++---------- .../DDSHelloWorld/src/HelloWorldCdrAux.hpp | 45 ++++++ .../DDSHelloWorld/src/HelloWorldCdrAux.ipp | 126 +++++++++++++++ .../src/HelloWorldPubSubTypes.cxx | 138 +++++++++++------ .../DDSHelloWorld/src/HelloWorldPubSubTypes.h | 104 ++++++++++--- code/FastDDSGenCodeTester.cpp | 104 +++++++++---- docs/03-exports/aliases-api.include | 1 + .../core/policy/datarepresentationid.rst | 2 + .../CDRSerialization/CDRSerialization.rst | 7 + .../api_reference/rtps/common/common.rst | 1 + docs/fastdds/dds_layer/topic/instances.rst | 2 +- docs/fastdds/dynamic_types/annotations.rst | 8 +- .../simple_app/includes/dataType.rst | 6 +- .../simple_app/includes/workspace.rst | 2 + .../simple_python_app/includes/dataType.rst | 6 +- .../simple_python_app/includes/workspace.rst | 2 + .../core/policy/datarepresentationid.rst | 2 + .../use_cases/request_reply/request_reply.rst | 2 +- .../rosbag_capture/rosbag_capture.rst | 3 +- .../fastdds/use_cases/zero_copy/zero_copy.rst | 11 +- docs/fastddsgen/dataTypes/dataTypes.rst | 114 +++++++++++--- .../pubsub_app/includes/idl_file.rst | 3 +- .../pubsub_app/includes/workspace.rst | 2 + docs/fastddsgen/usage/usage.rst | 59 ++++--- docs/installation/sources/sources_windows.rst | 4 +- docs/spelling_wordlist.txt | 1 + 30 files changed, 706 insertions(+), 329 deletions(-) create mode 100644 code/Examples/C++/DDSHelloWorld/src/HelloWorldCdrAux.hpp create mode 100644 code/Examples/C++/DDSHelloWorld/src/HelloWorldCdrAux.ipp create mode 100644 docs/fastdds/api_reference/rtps/common/CDRSerialization/CDRSerialization.rst diff --git a/code/CMakeLists.txt b/code/CMakeLists.txt index a424e12a9..0fad51bbe 100644 --- a/code/CMakeLists.txt +++ b/code/CMakeLists.txt @@ -61,7 +61,7 @@ target_link_libraries(doctest fastrtps) # DDSCodeTester utilizes Fast DDS API add_executable(dds-doctest DDSCodeTester.cpp FastDDSGenCodeTester.cpp) target_include_directories(dds-doctest PRIVATE ${FAST_INCLUDE_DIR}) -target_link_libraries(dds-doctest fastrtps) +target_link_libraries(dds-doctest fastrtps fastcdr) #################################################################################################### # Add tests diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp index 8b80107bc..576821167 100644 --- a/code/DDSCodeTester.cpp +++ b/code/DDSCodeTester.cpp @@ -259,6 +259,7 @@ class CustomDomainParticipantListener : public DomainParticipantListener class CustomPayloadPool : public eprosima::fastrtps::rtps::IPayloadPool { public: + CustomPayloadPool() = default; ~CustomPayloadPool() = default; bool get_payload( @@ -267,6 +268,7 @@ class CustomPayloadPool : public eprosima::fastrtps::rtps::IPayloadPool { return true; } + bool get_payload( eprosima::fastrtps::rtps::SerializedPayload_t& data, eprosima::fastrtps::rtps::IPayloadPool*& data_owner, @@ -274,11 +276,13 @@ class CustomPayloadPool : public eprosima::fastrtps::rtps::IPayloadPool { return true; } + bool release_payload( eprosima::fastrtps::rtps::CacheChange_t& cache_change) { return true; } + }; //!-- @@ -1946,8 +1950,7 @@ void dds_custom_filters_examples() * } */ eprosima::fastcdr::FastBuffer fastbuffer(reinterpret_cast(payload.data), payload.length); - eprosima::fastcdr::Cdr deser(fastbuffer, eprosima::fastcdr::Cdr::DEFAULT_ENDIAN, - eprosima::fastcdr::Cdr::DDS_CDR); + eprosima::fastcdr::Cdr deser(fastbuffer); // Deserialize encapsulation. deser.read_encapsulation(); int index = 0; diff --git a/code/Examples/C++/DDSHelloWorld/CMakeLists.txt b/code/Examples/C++/DDSHelloWorld/CMakeLists.txt index e614fa2cc..5d0523502 100644 --- a/code/Examples/C++/DDSHelloWorld/CMakeLists.txt +++ b/code/Examples/C++/DDSHelloWorld/CMakeLists.txt @@ -12,21 +12,21 @@ # See the License for the specific language governing permissions and # limitations under the License. -cmake_minimum_required(VERSION 3.12.4) +cmake_minimum_required(VERSION 3.22) + + + -if(NOT CMAKE_VERSION VERSION_LESS 3.0) - cmake_policy(SET CMP0048 NEW) -endif() project(DDSHelloWorld) # Find requirements if(NOT fastcdr_FOUND) - find_package(fastcdr REQUIRED) + find_package(fastcdr 2 REQUIRED) endif() if(NOT fastrtps_FOUND) - find_package(fastrtps REQUIRED) + find_package(fastrtps 2.12 REQUIRED) endif() # Set C++11 diff --git a/code/Examples/C++/DDSHelloWorld/src/HelloWorld.cxx b/code/Examples/C++/DDSHelloWorld/src/HelloWorld.cxx index 243075d24..bcda56fb4 100644 --- a/code/Examples/C++/DDSHelloWorld/src/HelloWorld.cxx +++ b/code/Examples/C++/DDSHelloWorld/src/HelloWorld.cxx @@ -14,52 +14,53 @@ /*! * @file HelloWorld.cpp - * This source file contains the definition of the described types in the IDL file. + * This source file contains the implementation of the described types in the IDL file. * - * This file was generated by the tool gen. + * This file was generated by the tool fastddsgen. */ #ifdef _WIN32 // Remove linker warning LNK4221 on Visual Studio -namespace { char dummy; } -#endif +namespace { +char dummy; +} // namespace +#endif // _WIN32 #include "HelloWorld.h" #include + #include using namespace eprosima::fastcdr::exception; #include + HelloWorld::HelloWorld() { - // m_index com.eprosima.idl.parser.typecode.PrimitiveTypeCode@e720b71 - m_index = 0; - // m_message com.eprosima.idl.parser.typecode.StringTypeCode@74ad1f1f - m_message =""; } HelloWorld::~HelloWorld() { - - } -HelloWorld::HelloWorld(const HelloWorld &x) +HelloWorld::HelloWorld( + const HelloWorld& x) { m_index = x.m_index; m_message = x.m_message; } -HelloWorld::HelloWorld(HelloWorld &&x) +HelloWorld::HelloWorld( + HelloWorld&& x) noexcept { m_index = x.m_index; m_message = std::move(x.m_message); } -HelloWorld& HelloWorld::operator=(const HelloWorld &x) +HelloWorld& HelloWorld::operator =( + const HelloWorld& x) { m_index = x.m_index; @@ -68,7 +69,8 @@ HelloWorld& HelloWorld::operator=(const HelloWorld &x) return *this; } -HelloWorld& HelloWorld::operator=(HelloWorld &&x) +HelloWorld& HelloWorld::operator =( + HelloWorld&& x) noexcept { m_index = x.m_index; @@ -77,56 +79,27 @@ HelloWorld& HelloWorld::operator=(HelloWorld &&x) return *this; } -size_t HelloWorld::getMaxCdrSerializedSize(size_t current_alignment) +bool HelloWorld::operator ==( + const HelloWorld& x) const { - size_t initial_alignment = current_alignment; - - - current_alignment += 4 + eprosima::fastcdr::Cdr::alignment(current_alignment, 4); - - - current_alignment += 4 + eprosima::fastcdr::Cdr::alignment(current_alignment, 4) + 255 + 1; - - - return current_alignment - initial_alignment; + return (m_index == x.m_index && + m_message == x.m_message); } -size_t HelloWorld::getCdrSerializedSize(const HelloWorld& data, size_t current_alignment) +bool HelloWorld::operator !=( + const HelloWorld& x) const { - (void)data; - size_t initial_alignment = current_alignment; - - - current_alignment += 4 + eprosima::fastcdr::Cdr::alignment(current_alignment, 4); - - - current_alignment += 4 + eprosima::fastcdr::Cdr::alignment(current_alignment, 4) + data.message().size() + 1; - - - return current_alignment - initial_alignment; -} - -void HelloWorld::serialize(eprosima::fastcdr::Cdr &scdr) const -{ - - scdr << m_index; - scdr << m_message; -} - -void HelloWorld::deserialize(eprosima::fastcdr::Cdr &dcdr) -{ - - dcdr >> m_index; - dcdr >> m_message; + return !(*this == x); } /*! * @brief This function sets a value in member index * @param _index New value for member index */ -void HelloWorld::index(uint32_t _index) +void HelloWorld::index( + uint32_t _index) { -m_index = _index; + m_index = _index; } /*! @@ -147,22 +120,25 @@ uint32_t& HelloWorld::index() return m_index; } + /*! * @brief This function copies the value in member message * @param _message New value to be copied in member message */ -void HelloWorld::message(const std::string &_message) +void HelloWorld::message( + const std::string& _message) { -m_message = _message; + m_message = _message; } /*! * @brief This function moves the value in member message * @param _message New value to be moved in member message */ -void HelloWorld::message(std::string &&_message) +void HelloWorld::message( + std::string&& _message) { -m_message = std::move(_message); + m_message = std::move(_message); } /*! @@ -183,25 +159,6 @@ std::string& HelloWorld::message() return m_message; } -size_t HelloWorld::getKeyMaxCdrSerializedSize(size_t current_alignment) -{ - size_t current_align = current_alignment; - - - - - - return current_align; -} - -bool HelloWorld::isKeyDefined() -{ - return false; -} -void HelloWorld::serializeKey(eprosima::fastcdr::Cdr &scdr) const -{ - (void) scdr; - - -} +// Include auxiliary functions like for serializing/deserializing. +#include "HelloWorldCdrAux.ipp" diff --git a/code/Examples/C++/DDSHelloWorld/src/HelloWorld.h b/code/Examples/C++/DDSHelloWorld/src/HelloWorld.h index 5b94c7c9d..0c6d09801 100644 --- a/code/Examples/C++/DDSHelloWorld/src/HelloWorld.h +++ b/code/Examples/C++/DDSHelloWorld/src/HelloWorld.h @@ -16,57 +16,60 @@ * @file HelloWorld.h * This header file contains the declaration of the described types in the IDL file. * - * This file was generated by the tool gen. + * This file was generated by the tool fastddsgen. */ -#ifndef _HELLOWORLD_H_ -#define _HELLOWORLD_H_ +#ifndef _FAST_DDS_GENERATED_HELLOWORLD_H_ +#define _FAST_DDS_GENERATED_HELLOWORLD_H_ -// TODO Poner en el contexto. - -#include #include +#include +#include +#include #include #include -#include -#include + +#include +#include + + #if defined(_WIN32) #if defined(EPROSIMA_USER_DLL_EXPORT) #define eProsima_user_DllExport __declspec( dllexport ) #else #define eProsima_user_DllExport -#endif +#endif // EPROSIMA_USER_DLL_EXPORT #else #define eProsima_user_DllExport -#endif +#endif // _WIN32 #if defined(_WIN32) #if defined(EPROSIMA_USER_DLL_EXPORT) -#if defined(HelloWorld_SOURCE) -#define HelloWorld_DllAPI __declspec( dllexport ) +#if defined(HELLOWORLD_SOURCE) +#define HELLOWORLD_DllAPI __declspec( dllexport ) #else -#define HelloWorld_DllAPI __declspec( dllimport ) -#endif // HelloWorld_SOURCE +#define HELLOWORLD_DllAPI __declspec( dllimport ) +#endif // HELLOWORLD_SOURCE #else -#define HelloWorld_DllAPI -#endif +#define HELLOWORLD_DllAPI +#endif // EPROSIMA_USER_DLL_EXPORT #else -#define HelloWorld_DllAPI +#define HELLOWORLD_DllAPI #endif // _WIN32 -namespace eprosima -{ - namespace fastcdr - { - class Cdr; - } -} +namespace eprosima { +namespace fastcdr { +class Cdr; +class CdrSizeCalculator; +} // namespace fastcdr +} // namespace eprosima + /*! * @brief This class represents the structure HelloWorld defined by the user in the IDL file. - * @ingroup HELLOWORLD + * @ingroup HelloWorld */ class HelloWorld { @@ -86,31 +89,50 @@ class HelloWorld * @brief Copy constructor. * @param x Reference to the object HelloWorld that will be copied. */ - eProsima_user_DllExport HelloWorld(const HelloWorld &x); + eProsima_user_DllExport HelloWorld( + const HelloWorld& x); /*! * @brief Move constructor. * @param x Reference to the object HelloWorld that will be copied. */ - eProsima_user_DllExport HelloWorld(HelloWorld &&x); + eProsima_user_DllExport HelloWorld( + HelloWorld&& x) noexcept; /*! * @brief Copy assignment. * @param x Reference to the object HelloWorld that will be copied. */ - eProsima_user_DllExport HelloWorld& operator=(const HelloWorld &x); + eProsima_user_DllExport HelloWorld& operator =( + const HelloWorld& x); /*! * @brief Move assignment. * @param x Reference to the object HelloWorld that will be copied. */ - eProsima_user_DllExport HelloWorld& operator=(HelloWorld &&x); + eProsima_user_DllExport HelloWorld& operator =( + HelloWorld&& x) noexcept; + + /*! + * @brief Comparison operator. + * @param x HelloWorld object to compare. + */ + eProsima_user_DllExport bool operator ==( + const HelloWorld& x) const; + + /*! + * @brief Comparison operator. + * @param x HelloWorld object to compare. + */ + eProsima_user_DllExport bool operator !=( + const HelloWorld& x) const; /*! * @brief This function sets a value in member index * @param _index New value for member index */ - eProsima_user_DllExport void index(uint32_t _index); + eProsima_user_DllExport void index( + uint32_t _index); /*! * @brief This function returns the value of member index @@ -124,17 +146,20 @@ class HelloWorld */ eProsima_user_DllExport uint32_t& index(); + /*! * @brief This function copies the value in member message * @param _message New value to be copied in member message */ - eProsima_user_DllExport void message(const std::string &_message); + eProsima_user_DllExport void message( + const std::string& _message); /*! * @brief This function moves the value in member message * @param _message New value to be moved in member message */ - eProsima_user_DllExport void message(std::string &&_message); + eProsima_user_DllExport void message( + std::string&& _message); /*! * @brief This function returns a constant reference to member message @@ -148,59 +173,12 @@ class HelloWorld */ eProsima_user_DllExport std::string& message(); - /*! - * @brief This function returns the maximum serialized size of an object - * depending on the buffer alignment. - * @param current_alignment Buffer alignment. - * @return Maximum serialized size. - */ - eProsima_user_DllExport static size_t getMaxCdrSerializedSize(size_t current_alignment = 0); - - /*! - * @brief This function returns the serialized size of a data depending on the buffer alignment. - * @param data Data which is calculated its serialized size. - * @param current_alignment Buffer alignment. - * @return Serialized size. - */ - eProsima_user_DllExport static size_t getCdrSerializedSize(const HelloWorld& data, size_t current_alignment = 0); - - - /*! - * @brief This function serializes an object using CDR serialization. - * @param cdr CDR serialization object. - */ - eProsima_user_DllExport void serialize(eprosima::fastcdr::Cdr &cdr) const; - - /*! - * @brief This function deserializes an object using CDR serialization. - * @param cdr CDR serialization object. - */ - eProsima_user_DllExport void deserialize(eprosima::fastcdr::Cdr &cdr); - - - - /*! - * @brief This function returns the maximum serialized size of the Key of an object - * depending on the buffer alignment. - * @param current_alignment Buffer alignment. - * @return Maximum serialized size. - */ - eProsima_user_DllExport static size_t getKeyMaxCdrSerializedSize(size_t current_alignment = 0); - - /*! - * @brief This function tells you if the Key has been defined for this type - */ - eProsima_user_DllExport static bool isKeyDefined(); - - /*! - * @brief This function serializes the key members of an object using CDR serialization. - * @param cdr CDR serialization object. - */ - eProsima_user_DllExport void serializeKey(eprosima::fastcdr::Cdr &cdr) const; - private: - uint32_t m_index; + + uint32_t m_index{0}; std::string m_message; + }; -#endif // _HELLOWORLD_H_ \ No newline at end of file +#endif // _FAST_DDS_GENERATED_HELLOWORLD_H_ + diff --git a/code/Examples/C++/DDSHelloWorld/src/HelloWorldCdrAux.hpp b/code/Examples/C++/DDSHelloWorld/src/HelloWorldCdrAux.hpp new file mode 100644 index 000000000..37b13815b --- /dev/null +++ b/code/Examples/C++/DDSHelloWorld/src/HelloWorldCdrAux.hpp @@ -0,0 +1,45 @@ +// Copyright 2016 Proyectos y Sistemas de Mantenimiento SL (eProsima). +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +/*! + * @file HelloWorldCdrAux.hpp + * This source file contains some definitions of CDR related functions. + * + * This file was generated by the tool fastddsgen. + */ + +#ifndef _FAST_DDS_GENERATED_HELLOWORLDCDRAUX_HPP_ +#define _FAST_DDS_GENERATED_HELLOWORLDCDRAUX_HPP_ + +#include "HelloWorld.h" + +constexpr uint32_t HelloWorld_max_cdr_typesize {268UL}; +constexpr uint32_t HelloWorld_max_key_cdr_typesize {0UL}; + + +namespace eprosima { +namespace fastcdr { + +class Cdr; +class CdrSizeCalculator; + +eProsima_user_DllExport void serialize_key( + eprosima::fastcdr::Cdr& scdr, + const HelloWorld& data); + + +} // namespace fastcdr +} // namespace eprosima + +#endif // _FAST_DDS_GENERATED_HELLOWORLDCDRAUX_HPP_ \ No newline at end of file diff --git a/code/Examples/C++/DDSHelloWorld/src/HelloWorldCdrAux.ipp b/code/Examples/C++/DDSHelloWorld/src/HelloWorldCdrAux.ipp new file mode 100644 index 000000000..b9461ff5b --- /dev/null +++ b/code/Examples/C++/DDSHelloWorld/src/HelloWorldCdrAux.ipp @@ -0,0 +1,126 @@ +// Copyright 2016 Proyectos y Sistemas de Mantenimiento SL (eProsima). +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +/*! + * @file HelloWorldCdrAux.ipp + * This source file contains some declarations of CDR related functions. + * + * This file was generated by the tool fastddsgen. + */ + +#ifndef _FAST_DDS_GENERATED_HELLOWORLDCDRAUX_IPP_ +#define _FAST_DDS_GENERATED_HELLOWORLDCDRAUX_IPP_ + +#include "HelloWorldCdrAux.hpp" + +#include +#include + + +#include +using namespace eprosima::fastcdr::exception; + +namespace eprosima { +namespace fastcdr { + +template<> +eProsima_user_DllExport size_t calculate_serialized_size( + eprosima::fastcdr::CdrSizeCalculator& calculator, + const HelloWorld& data, + size_t& current_alignment) +{ + static_cast(data); + + eprosima::fastcdr::EncodingAlgorithmFlag previous_encoding = calculator.get_encoding(); + size_t calculated_size {calculator.begin_calculate_type_serialized_size( + eprosima::fastcdr::CdrVersion::XCDRv2 == calculator.get_cdr_version() ? + eprosima::fastcdr::EncodingAlgorithmFlag::DELIMIT_CDR2 : + eprosima::fastcdr::EncodingAlgorithmFlag::PLAIN_CDR, + current_alignment)}; + + + calculated_size += calculator.calculate_member_serialized_size(eprosima::fastcdr::MemberId(0), + data.index(), current_alignment); + + calculated_size += calculator.calculate_member_serialized_size(eprosima::fastcdr::MemberId(1), + data.message(), current_alignment); + + + calculated_size += calculator.end_calculate_type_serialized_size(previous_encoding, current_alignment); + + return calculated_size; +} + +template<> +eProsima_user_DllExport void serialize( + eprosima::fastcdr::Cdr& scdr, + const HelloWorld& data) +{ + eprosima::fastcdr::Cdr::state current_state(scdr); + scdr.begin_serialize_type(current_state, + eprosima::fastcdr::CdrVersion::XCDRv2 == scdr.get_cdr_version() ? + eprosima::fastcdr::EncodingAlgorithmFlag::DELIMIT_CDR2 : + eprosima::fastcdr::EncodingAlgorithmFlag::PLAIN_CDR); + + scdr + << eprosima::fastcdr::MemberId(0) << data.index() + << eprosima::fastcdr::MemberId(1) << data.message() +; + + scdr.end_serialize_type(current_state); +} + +template<> +eProsima_user_DllExport void deserialize( + eprosima::fastcdr::Cdr& cdr, + HelloWorld& data) +{ + cdr.deserialize_type(eprosima::fastcdr::CdrVersion::XCDRv2 == cdr.get_cdr_version() ? + eprosima::fastcdr::EncodingAlgorithmFlag::DELIMIT_CDR2 : + eprosima::fastcdr::EncodingAlgorithmFlag::PLAIN_CDR, + [&data](eprosima::fastcdr::Cdr& dcdr, const eprosima::fastcdr::MemberId& mid) -> bool + { + bool ret_value = true; + switch (mid.id) + { + case 0: + dcdr >> data.index(); + break; + + case 1: + dcdr >> data.message(); + break; + + default: + ret_value = false; + break; + } + return ret_value; + }); +} + +void serialize_key( + eprosima::fastcdr::Cdr& scdr, + const HelloWorld& data) +{ + static_cast(scdr); + static_cast(data); +} + + + +} // namespace fastcdr +} // namespace eprosima + +#endif // _FAST_DDS_GENERATED_HELLOWORLDCDRAUX_IPP_ \ No newline at end of file diff --git a/code/Examples/C++/DDSHelloWorld/src/HelloWorldPubSubTypes.cxx b/code/Examples/C++/DDSHelloWorld/src/HelloWorldPubSubTypes.cxx index 89e89cc85..f4a5ef511 100644 --- a/code/Examples/C++/DDSHelloWorld/src/HelloWorldPubSubTypes.cxx +++ b/code/Examples/C++/DDSHelloWorld/src/HelloWorldPubSubTypes.cxx @@ -16,72 +16,100 @@ * @file HelloWorldPubSubTypes.cpp * This header file contains the implementation of the serialization functions. * - * This file was generated by the tool fastcdrgen. + * This file was generated by the tool fastddsgen. */ #include #include +#include #include "HelloWorldPubSubTypes.h" +#include "HelloWorldCdrAux.hpp" -using namespace eprosima::fastrtps; -using namespace eprosima::fastrtps::rtps; +using SerializedPayload_t = eprosima::fastrtps::rtps::SerializedPayload_t; +using InstanceHandle_t = eprosima::fastrtps::rtps::InstanceHandle_t; +using DataRepresentationId_t = eprosima::fastdds::dds::DataRepresentationId_t; HelloWorldPubSubType::HelloWorldPubSubType() { setName("HelloWorld"); - m_typeSize = static_cast(HelloWorld::getMaxCdrSerializedSize()) + 4 /*encapsulation*/; - m_isGetKeyDefined = HelloWorld::isKeyDefined(); - size_t keyLength = HelloWorld::getKeyMaxCdrSerializedSize()>16 ? HelloWorld::getKeyMaxCdrSerializedSize() : 16; + uint32_t type_size = HelloWorld_max_cdr_typesize; + type_size += static_cast(eprosima::fastcdr::Cdr::alignment(type_size, 4)); /* possible submessage alignment */ + m_typeSize = type_size + 4; /*encapsulation*/ + m_isGetKeyDefined = false; + uint32_t keyLength = HelloWorld_max_key_cdr_typesize > 16 ? HelloWorld_max_key_cdr_typesize : 16; m_keyBuffer = reinterpret_cast(malloc(keyLength)); memset(m_keyBuffer, 0, keyLength); } HelloWorldPubSubType::~HelloWorldPubSubType() { - if(m_keyBuffer!=nullptr) + if (m_keyBuffer != nullptr) + { free(m_keyBuffer); + } } -bool HelloWorldPubSubType::serialize(void *data, SerializedPayload_t *payload) +bool HelloWorldPubSubType::serialize( + void* data, + SerializedPayload_t* payload, + DataRepresentationId_t data_representation) { - HelloWorld *p_type = static_cast(data); - eprosima::fastcdr::FastBuffer fastbuffer(reinterpret_cast(payload->data), payload->max_size); // Object that manages the raw buffer. + HelloWorld* p_type = static_cast(data); + + // Object that manages the raw buffer. + eprosima::fastcdr::FastBuffer fastbuffer(reinterpret_cast(payload->data), payload->max_size); + // Object that serializes the data. eprosima::fastcdr::Cdr ser(fastbuffer, eprosima::fastcdr::Cdr::DEFAULT_ENDIAN, - eprosima::fastcdr::Cdr::DDS_CDR); // Object that serializes the data. + data_representation == DataRepresentationId_t::XCDR_DATA_REPRESENTATION ? + eprosima::fastcdr::CdrVersion::XCDRv1 : eprosima::fastcdr::CdrVersion::XCDRv2); payload->encapsulation = ser.endianness() == eprosima::fastcdr::Cdr::BIG_ENDIANNESS ? CDR_BE : CDR_LE; - // Serialize encapsulation - ser.serialize_encapsulation(); + ser.set_encoding_flag( + data_representation == DataRepresentationId_t::XCDR_DATA_REPRESENTATION ? + eprosima::fastcdr::EncodingAlgorithmFlag::PLAIN_CDR : + eprosima::fastcdr::EncodingAlgorithmFlag::DELIMIT_CDR2); try { - p_type->serialize(ser); // Serialize the object: + // Serialize encapsulation + ser.serialize_encapsulation(); + // Serialize the object. + ser << *p_type; } - catch(eprosima::fastcdr::exception::NotEnoughMemoryException& /*exception*/) + catch (eprosima::fastcdr::exception::Exception& /*exception*/) { return false; } - payload->length = static_cast(ser.getSerializedDataLength()); //Get the serialized length + // Get the serialized length + payload->length = static_cast(ser.get_serialized_data_length()); return true; } -bool HelloWorldPubSubType::deserialize(SerializedPayload_t* payload, void* data) +bool HelloWorldPubSubType::deserialize( + SerializedPayload_t* payload, + void* data) { - HelloWorld* p_type = static_cast(data); //Convert DATA to pointer of your type - eprosima::fastcdr::FastBuffer fastbuffer(reinterpret_cast(payload->data), payload->length); // Object that manages the raw buffer. - eprosima::fastcdr::Cdr deser(fastbuffer, eprosima::fastcdr::Cdr::DEFAULT_ENDIAN, - eprosima::fastcdr::Cdr::DDS_CDR); // Object that deserializes the data. - // Deserialize encapsulation. - deser.read_encapsulation(); - payload->encapsulation = deser.endianness() == eprosima::fastcdr::Cdr::BIG_ENDIANNESS ? CDR_BE : CDR_LE; - try { - p_type->deserialize(deser); //Deserialize the object: + // Convert DATA to pointer of your type + HelloWorld* p_type = static_cast(data); + + // Object that manages the raw buffer. + eprosima::fastcdr::FastBuffer fastbuffer(reinterpret_cast(payload->data), payload->length); + + // Object that deserializes the data. + eprosima::fastcdr::Cdr deser(fastbuffer, eprosima::fastcdr::Cdr::DEFAULT_ENDIAN); + + // Deserialize encapsulation. + deser.read_encapsulation(); + payload->encapsulation = deser.endianness() == eprosima::fastcdr::Cdr::BIG_ENDIANNESS ? CDR_BE : CDR_LE; + + // Deserialize the object. + deser >> *p_type; } - catch(eprosima::fastcdr::exception::NotEnoughMemoryException& /*exception*/) + catch (eprosima::fastcdr::exception::Exception& /*exception*/) { return false; } @@ -89,12 +117,20 @@ bool HelloWorldPubSubType::deserialize(SerializedPayload_t* payload, void* data) return true; } -std::function HelloWorldPubSubType::getSerializedSizeProvider(void* data) +std::function HelloWorldPubSubType::getSerializedSizeProvider( + void* data, + DataRepresentationId_t data_representation) { - return [data]() -> uint32_t - { - return static_cast(type::getCdrSerializedSize(*static_cast(data))) + 4 /*encapsulation*/; - }; + return [data, data_representation]() -> uint32_t + { + eprosima::fastcdr::CdrSizeCalculator calculator( + data_representation == DataRepresentationId_t::XCDR_DATA_REPRESENTATION ? + eprosima::fastcdr::CdrVersion::XCDRv1 :eprosima::fastcdr::CdrVersion::XCDRv2); + size_t current_alignment {0}; + return static_cast(calculator.calculate_serialized_size( + *static_cast(data), current_alignment)) + + 4u /*encapsulation*/; + }; } void* HelloWorldPubSubType::createData() @@ -102,29 +138,45 @@ void* HelloWorldPubSubType::createData() return reinterpret_cast(new HelloWorld()); } -void HelloWorldPubSubType::deleteData(void* data) +void HelloWorldPubSubType::deleteData( + void* data) { delete(reinterpret_cast(data)); } -bool HelloWorldPubSubType::getKey(void *data, InstanceHandle_t* handle, bool force_md5) +bool HelloWorldPubSubType::getKey( + void* data, + InstanceHandle_t* handle, + bool force_md5) { - if(!m_isGetKeyDefined) + if (!m_isGetKeyDefined) + { return false; + } + HelloWorld* p_type = static_cast(data); - eprosima::fastcdr::FastBuffer fastbuffer(reinterpret_cast(m_keyBuffer),HelloWorld::getKeyMaxCdrSerializedSize()); // Object that manages the raw buffer. - eprosima::fastcdr::Cdr ser(fastbuffer, eprosima::fastcdr::Cdr::BIG_ENDIANNESS); // Object that serializes the data. - p_type->serializeKey(ser); - if(force_md5 || HelloWorld::getKeyMaxCdrSerializedSize()>16) { + + // Object that manages the raw buffer. + eprosima::fastcdr::FastBuffer fastbuffer(reinterpret_cast(m_keyBuffer), + HelloWorld_max_key_cdr_typesize); + + // Object that serializes the data. + eprosima::fastcdr::Cdr ser(fastbuffer, eprosima::fastcdr::Cdr::BIG_ENDIANNESS); + eprosima::fastcdr::serialize_key(ser, *p_type); + if (force_md5 || HelloWorld_max_key_cdr_typesize > 16) + { m_md5.init(); - m_md5.update(m_keyBuffer, static_cast(ser.getSerializedDataLength())); + m_md5.update(m_keyBuffer, static_cast(ser.get_serialized_data_length())); m_md5.finalize(); - for(uint8_t i = 0;i<16;++i) { + for (uint8_t i = 0; i < 16; ++i) + { handle->value[i] = m_md5.digest[i]; } } - else { - for(uint8_t i = 0;i<16;++i) { + else + { + for (uint8_t i = 0; i < 16; ++i) + { handle->value[i] = m_keyBuffer[i]; } } diff --git a/code/Examples/C++/DDSHelloWorld/src/HelloWorldPubSubTypes.h b/code/Examples/C++/DDSHelloWorld/src/HelloWorldPubSubTypes.h index 8d8125203..5b325dd1c 100644 --- a/code/Examples/C++/DDSHelloWorld/src/HelloWorldPubSubTypes.h +++ b/code/Examples/C++/DDSHelloWorld/src/HelloWorldPubSubTypes.h @@ -16,42 +16,108 @@ * @file HelloWorldPubSubTypes.h * This header file contains the declaration of the serialization functions. * - * This file was generated by the tool fastcdrgen. + * This file was generated by the tool fastddsgen. */ -#ifndef _HELLOWORLD_PUBSUBTYPES_H_ -#define _HELLOWORLD_PUBSUBTYPES_H_ +#ifndef _FAST_DDS_GENERATED_HELLOWORLD_PUBSUBTYPES_H_ +#define _FAST_DDS_GENERATED_HELLOWORLD_PUBSUBTYPES_H_ -#include -#include +#include +#include +#include +#include +#include #include "HelloWorld.h" -#if !defined(GEN_API_VER) || (GEN_API_VER != 1) -#error Generated HelloWorld is not compatible with current installed Fast-RTPS. Please, regenerate it with fastddsgen. -#endif + +#if !defined(GEN_API_VER) || (GEN_API_VER != 2) +#error \ + Generated HelloWorld is not compatible with current installed Fast DDS. Please, regenerate it with fastddsgen. +#endif // GEN_API_VER + /*! * @brief This class represents the TopicDataType of the type HelloWorld defined by the user in the IDL file. - * @ingroup HELLOWORLD + * @ingroup HelloWorld */ -class HelloWorldPubSubType : public eprosima::fastrtps::TopicDataType { +class HelloWorldPubSubType : public eprosima::fastdds::dds::TopicDataType +{ public: + typedef HelloWorld type; eProsima_user_DllExport HelloWorldPubSubType(); - eProsima_user_DllExport virtual ~HelloWorldPubSubType(); - eProsima_user_DllExport virtual bool serialize(void *data, eprosima::fastrtps::rtps::SerializedPayload_t *payload) override; - eProsima_user_DllExport virtual bool deserialize(eprosima::fastrtps::rtps::SerializedPayload_t *payload, void *data) override; - eProsima_user_DllExport virtual std::function getSerializedSizeProvider(void* data) override; - eProsima_user_DllExport virtual bool getKey(void *data, eprosima::fastrtps::rtps::InstanceHandle_t *ihandle, - bool force_md5 = false) override; - eProsima_user_DllExport virtual void* createData() override; - eProsima_user_DllExport virtual void deleteData(void * data) override; + eProsima_user_DllExport ~HelloWorldPubSubType() override; + + eProsima_user_DllExport bool serialize( + void* data, + eprosima::fastrtps::rtps::SerializedPayload_t* payload) override + { + return serialize(data, payload, eprosima::fastdds::dds::DEFAULT_DATA_REPRESENTATION); + } + + eProsima_user_DllExport bool serialize( + void* data, + eprosima::fastrtps::rtps::SerializedPayload_t* payload, + eprosima::fastdds::dds::DataRepresentationId_t data_representation) override; + + eProsima_user_DllExport bool deserialize( + eprosima::fastrtps::rtps::SerializedPayload_t* payload, + void* data) override; + + eProsima_user_DllExport std::function getSerializedSizeProvider( + void* data) override + { + return getSerializedSizeProvider(data, eprosima::fastdds::dds::DEFAULT_DATA_REPRESENTATION); + } + + eProsima_user_DllExport std::function getSerializedSizeProvider( + void* data, + eprosima::fastdds::dds::DataRepresentationId_t data_representation) override; + + eProsima_user_DllExport bool getKey( + void* data, + eprosima::fastrtps::rtps::InstanceHandle_t* ihandle, + bool force_md5 = false) override; + + eProsima_user_DllExport void* createData() override; + + eProsima_user_DllExport void deleteData( + void* data) override; + +#ifdef TOPIC_DATA_TYPE_API_HAS_IS_BOUNDED + eProsima_user_DllExport inline bool is_bounded() const override + { + return false; + } + +#endif // TOPIC_DATA_TYPE_API_HAS_IS_BOUNDED + +#ifdef TOPIC_DATA_TYPE_API_HAS_IS_PLAIN + eProsima_user_DllExport inline bool is_plain() const override + { + return false; + } + +#endif // TOPIC_DATA_TYPE_API_HAS_IS_PLAIN + +#ifdef TOPIC_DATA_TYPE_API_HAS_CONSTRUCT_SAMPLE + eProsima_user_DllExport inline bool construct_sample( + void* memory) const override + { + static_cast(memory); + return false; + } + +#endif // TOPIC_DATA_TYPE_API_HAS_CONSTRUCT_SAMPLE + MD5 m_md5; unsigned char* m_keyBuffer; + }; -#endif // _HELLOWORLD_PUBSUBTYPES_H_ \ No newline at end of file +#endif // _FAST_DDS_GENERATED_HELLOWORLD_PUBSUBTYPES_H_ + diff --git a/code/FastDDSGenCodeTester.cpp b/code/FastDDSGenCodeTester.cpp index ae3275223..2135cb955 100644 --- a/code/FastDDSGenCodeTester.cpp +++ b/code/FastDDSGenCodeTester.cpp @@ -2,32 +2,44 @@ #include #include +#include + using octet = unsigned char; // STRUCTURES_DATA_TYPE class Structure { public: + Structure(); ~Structure(); - Structure(const Structure &x); - Structure(Structure &&x); - Structure& operator=(const Structure &x); - Structure& operator=(Structure &&x); - - void octet_value(uint8_t _octet_value); + Structure( + const Structure& x); + Structure( + Structure&& x); + Structure& operator =( + const Structure& x); + Structure& operator =( + Structure&& x); + + void octet_value( + uint8_t _octet_value); uint8_t octet_value() const; uint8_t& octet_value(); - void long_value(int64_t _long_value); + void long_value( + int64_t _long_value); int64_t long_value() const; int64_t& long_value(); - void string_value(const std::string - &_string_value); - void string_value(std::string &&_string_value); + void string_value( + const std::string + & _string_value); + void string_value( + std::string&& _string_value); const std::string& string_value() const; std::string& string_value(); private: + uint8_t m_octet_value; int64_t m_long_value; std::string m_string_value; @@ -46,35 +58,64 @@ class ChildStruct : public ParentStruct }; //! +// STRUCTURE_WITH_OPTIONAL +class StructWithOptionalMember +{ + eprosima::fastcdr::optional octet_opt; +}; +//! + +void accessing_optional_value() +{ + eprosima::fastcdr::optional octet_opt; + + // ACCESSING_OPTIONAL_VALUE + if (octet_opt.has_value()) + { + octet oc = octet_opt.value(); + } + //! +} // UNION_DATA_TYPE class Union { public: + Union(); ~Union(); - Union(const Union &x); - Union(Union &&x); - Union& operator=(const Union &x); - Union& operator=(Union &&x); - - void d(int32_t __d); + Union( + const Union& x); + Union( + Union&& x); + Union& operator =( + const Union& x); + Union& operator =( + Union&& x); + + void d( + int32_t __d); int32_t _d() const; int32_t& _d(); - void octet_value(uint8_t _octet_value); + void octet_value( + uint8_t _octet_value); uint8_t octet_value() const; uint8_t& octet_value(); - void long_value(int64_t _long_value); + void long_value( + int64_t _long_value); int64_t long_value() const; int64_t& long_value(); - void string_value(const std::string - &_string_value); - void string_value(std:: string &&_string_value); + void string_value( + const std::string + & _string_value); + void string_value( + std:: string&& _string_value); const std::string& string_value() const; std::string& string_value(); private: + int32_t m__d; uint8_t m_octet_value; int64_t m_long_value; @@ -86,16 +127,21 @@ class Union class MyBitset { public: - void a(char _a); + + void a( + char _a); char a() const; - void b(uint16_t _b); + void b( + uint16_t _b); uint16_t b() const; - void c(int32_t _c); + void c( + int32_t _c); int32_t c() const; private: + std::bitset<25> m_bitset; }; //! @@ -133,8 +179,8 @@ enum MyBitMask : uint8_t //! /* -// INCLUDE_MORE_IDL_FILES -#include "OtherFile.idl" -#include -//! -/**/ + // INCLUDE_MORE_IDL_FILES + #include "OtherFile.idl" + #include + //! + /**/ diff --git a/docs/03-exports/aliases-api.include b/docs/03-exports/aliases-api.include index 160be6534..c8217d80c 100644 --- a/docs/03-exports/aliases-api.include +++ b/docs/03-exports/aliases-api.include @@ -277,6 +277,7 @@ .. |TypeObject-api| replace:: :cpp:class:`TypeObject ` .. |TypeObjectFactory-api| replace:: :cpp:class:`TypeObjectFactory ` .. |TypeSupport-api| replace:: :cpp:class:`TypeSupport` +.. |TypeSupport::is_plain-api| replace:: :cpp:func:`TypeSupport::is_plain() ` .. |TypeSupport::register_type-api| replace:: :cpp:func:`register_type() ` .. |SampleIdentity-api| replace:: :cpp:class:`SampleIdentity` .. |SampleInfo-api| replace:: :cpp:class:`SampleInfo` diff --git a/docs/fastdds/api_reference/dds_pim/core/policy/datarepresentationid.rst b/docs/fastdds/api_reference/dds_pim/core/policy/datarepresentationid.rst index 0866c5fec..a221485ae 100644 --- a/docs/fastdds/api_reference/dds_pim/core/policy/datarepresentationid.rst +++ b/docs/fastdds/api_reference/dds_pim/core/policy/datarepresentationid.rst @@ -8,3 +8,5 @@ DataRepresentationId .. doxygenenum:: eprosima::fastdds::dds::DataRepresentationId :project: FastDDS +.. doxygenvariable:: DEFAULT_DATA_REPRESENTATION + :project: FastDDS diff --git a/docs/fastdds/api_reference/rtps/common/CDRSerialization/CDRSerialization.rst b/docs/fastdds/api_reference/rtps/common/CDRSerialization/CDRSerialization.rst new file mode 100644 index 000000000..e3d1013e0 --- /dev/null +++ b/docs/fastdds/api_reference/rtps/common/CDRSerialization/CDRSerialization.rst @@ -0,0 +1,7 @@ +.. rst-class:: api-ref + +CDRSerialization +---------------- + +.. doxygenvariable:: eprosima::fastdds::rtps::DEFAULT_XCDR_VERSION + :project: FastDDS diff --git a/docs/fastdds/api_reference/rtps/common/common.rst b/docs/fastdds/api_reference/rtps/common/common.rst index e3990c63c..e1ab1e8b4 100644 --- a/docs/fastdds/api_reference/rtps/common/common.rst +++ b/docs/fastdds/api_reference/rtps/common/common.rst @@ -8,6 +8,7 @@ Common /fastdds/api_reference/rtps/common/BinaryProperty/binaryproperty_toc /fastdds/api_reference/rtps/common/CacheChange/cachechange_toc /fastdds/api_reference/rtps/common/CDRMessage_t/cdrmessage_toc + /fastdds/api_reference/rtps/common/CDRSerialization/CDRSerialization /fastdds/api_reference/rtps/common/EntityId_t/entityid_toc /fastdds/api_reference/rtps/common/FragmentNumber/fragmentnumber_toc /fastdds/api_reference/rtps/common/Guid/guid_toc diff --git a/docs/fastdds/dds_layer/topic/instances.rst b/docs/fastdds/dds_layer/topic/instances.rst index 5b42afbb7..fa423a0b2 100644 --- a/docs/fastdds/dds_layer/topic/instances.rst +++ b/docs/fastdds/dds_layer/topic/instances.rst @@ -85,7 +85,7 @@ instance key. The sample data being relayed would be the location of each flight being tracked at any given time. The following IDL defines the data described model: -.. code-block:: idl +.. code-block:: omg-idl struct FlightPosition { diff --git a/docs/fastdds/dynamic_types/annotations.rst b/docs/fastdds/dynamic_types/annotations.rst index 5a59fd136..bbd4f7660 100644 --- a/docs/fastdds/dynamic_types/annotations.rst +++ b/docs/fastdds/dynamic_types/annotations.rst @@ -18,7 +18,7 @@ Both functions take the name, the key and the value of the annotation. For example, if we define an annotation like: -.. code-block:: idl +.. code-block:: omg-idl @annotation MyAnnotation { @@ -28,12 +28,13 @@ For example, if we define an annotation like: And then we apply it through IDL to a struct: -.. code-block:: idl +.. code-block:: omg-idl @MyAnnotation(5, "length") struct MyStruct { - ... + // ... + } The equivalent code using |DynamicTypes| will be: @@ -60,4 +61,3 @@ The following annotations modifies the behavior of DynamicTypes: - | ``@default``: Sets a default value for the member. - | ``@non_serialized``: Excludes a member from being serialized. - diff --git a/docs/fastdds/getting_started/simple_app/includes/dataType.rst b/docs/fastdds/getting_started/simple_app/includes/dataType.rst index 55f40debd..eb054adbb 100644 --- a/docs/fastdds/getting_started/simple_app/includes/dataType.rst +++ b/docs/fastdds/getting_started/simple_app/includes/dataType.rst @@ -22,7 +22,7 @@ In the workspace directory, execute the following commands: This creates the HelloWorld.idl file in the `src` directory. Open the file in a text editor and copy and paste the following snippet of code. -.. code-block:: idl +.. code-block:: omg-idl struct HelloWorld { @@ -43,8 +43,10 @@ This must have generated the following files: * HelloWorld.cxx: HelloWorld type definition. * HelloWorld.h: Header file for HelloWorld.cxx. - * HelloWorldPubSubTypes.cxx: Serialization and Deserialization code for the HelloWorld type. + * HelloWorldPubSubTypes.cxx: Interface used by Fast DDS to support HelloWorld type. * HelloWorldPubSubTypes.h: Header file for HelloWorldPubSubTypes.cxx. + * HelloWorldCdrAux.ipp: Serialization and Deserialization code for the HelloWorld type. + * HelloWorldCdrAux.hpp: Header file for HelloWorldCdrAux.ipp. CMakeLists.txt """""""""""""" diff --git a/docs/fastdds/getting_started/simple_app/includes/workspace.rst b/docs/fastdds/getting_started/simple_app/includes/workspace.rst index f2cdd2903..2cfd0e60b 100644 --- a/docs/fastdds/getting_started/simple_app/includes/workspace.rst +++ b/docs/fastdds/getting_started/simple_app/includes/workspace.rst @@ -21,6 +21,8 @@ Subscriber application respectively. ├── HelloWorld.cxx ├── HelloWorld.h ├── HelloWorld.idl + ├── HelloWorldCdrAux.hpp + ├── HelloWorldCdrAux.ipp ├── HelloWorldPublisher.cpp ├── HelloWorldPubSubTypes.cxx ├── HelloWorldPubSubTypes.h diff --git a/docs/fastdds/getting_started/simple_python_app/includes/dataType.rst b/docs/fastdds/getting_started/simple_python_app/includes/dataType.rst index a21d2e6d2..37d9c36ce 100644 --- a/docs/fastdds/getting_started/simple_python_app/includes/dataType.rst +++ b/docs/fastdds/getting_started/simple_python_app/includes/dataType.rst @@ -22,7 +22,7 @@ In the workspace directory, execute the following commands: This creates the HelloWorld.idl file. Open the file in a text editor and copy and paste the following snippet of code. -.. code-block:: idl +.. code-block:: omg-idl struct HelloWorld { @@ -45,9 +45,11 @@ This must have generated the following files: * HelloWorld.cxx: HelloWorld C++ type definition. * HelloWorld.h: C++ header file for HelloWorld.cxx. * HelloWorld.i: `SWIG`_ interface file for HelloWorld C++ type definition. - * HelloWorldPubSubTypes.cxx: C+`Serialization and Deserialization code for the HelloWorld type. + * HelloWorldPubSubTypes.cxx: C++ interface used by Fast DDS to support HelloWorld type. * HelloWorldPubSubTypes.h: C++ header file for HelloWorldPubSubTypes.cxx. * HelloWorldPubSubTypes.i: `SWIG`_ interface file for C++ Serialization and Deserialization code. + * HelloWorldCdrAux.ipp: C++ serialization and deserialization code for the HelloWorld type. + * HelloWorldCdrAux.hpp: C++ header file for HelloWorldCdrAux.ipp. * CMakeLists.txt: CMake file to generate C++ source code and Python module from the `SWIG`_ interface files, compile and generate C++ libraries. * HelloWorld.py: Python module to be imported by your Python example. diff --git a/docs/fastdds/getting_started/simple_python_app/includes/workspace.rst b/docs/fastdds/getting_started/simple_python_app/includes/workspace.rst index d2d979e3a..916941211 100644 --- a/docs/fastdds/getting_started/simple_python_app/includes/workspace.rst +++ b/docs/fastdds/getting_started/simple_python_app/includes/workspace.rst @@ -16,6 +16,8 @@ Subscriber application respectively. ├── HelloWorld.i ├── HelloWorld.idl ├── HelloWorld.py + ├── HelloWorldCdrAux.hpp + ├── HelloWorldCdrAux.ipp ├── HelloWorldPubSubTypes.cxx ├── HelloWorldPubSubTypes.h ├── HelloWorldPubSubTypes.i diff --git a/docs/fastdds/python_api_reference/dds_pim/core/policy/datarepresentationid.rst b/docs/fastdds/python_api_reference/dds_pim/core/policy/datarepresentationid.rst index 2e3bddac4..9bbf6d0fa 100644 --- a/docs/fastdds/python_api_reference/dds_pim/core/policy/datarepresentationid.rst +++ b/docs/fastdds/python_api_reference/dds_pim/core/policy/datarepresentationid.rst @@ -10,3 +10,5 @@ DataRepresentationId .. autoclass:: fastdds.XML_DATA_REPRESENTATION .. autoclass:: fastdds.XCDR2_DATA_REPRESENTATION + +.. autoclass:: fastdds.DEFAULT_DATA_REPRESENTATION diff --git a/docs/fastdds/use_cases/request_reply/request_reply.rst b/docs/fastdds/use_cases/request_reply/request_reply.rst index e54c8df31..748b3729c 100644 --- a/docs/fastdds/use_cases/request_reply/request_reply.rst +++ b/docs/fastdds/use_cases/request_reply/request_reply.rst @@ -64,7 +64,7 @@ For *Request-Reply* communication perform the following steps: 1. Define two structures in an IDL file. One structure will be used as Request Topic's data type and the other one as Reply Topic's data type. - .. code-block:: idl + .. code-block:: omg-idl enum OperationType { diff --git a/docs/fastdds/use_cases/rosbag_capture/rosbag_capture.rst b/docs/fastdds/use_cases/rosbag_capture/rosbag_capture.rst index b264e4cae..adce32741 100644 --- a/docs/fastdds/use_cases/rosbag_capture/rosbag_capture.rst +++ b/docs/fastdds/use_cases/rosbag_capture/rosbag_capture.rst @@ -40,7 +40,7 @@ Assuming that the type module name selected is ``fastdds_record_typesupport`` th file could be defined. This IDL file will be the one used in the following steps. -.. code-block:: idl +.. code-block:: omg-idl module fastdds_record_typesupport { @@ -244,4 +244,3 @@ will receive them: export RMW_IMPLEMENTATION=rmw_fastrtps_cpp source /fastdds_record_typesupport/install/setup.bash ros2 bag play - diff --git a/docs/fastdds/use_cases/zero_copy/zero_copy.rst b/docs/fastdds/use_cases/zero_copy/zero_copy.rst index 3d6736cec..994b70a91 100644 --- a/docs/fastdds/use_cases/zero_copy/zero_copy.rst +++ b/docs/fastdds/use_cases/zero_copy/zero_copy.rst @@ -51,7 +51,7 @@ To enable Zero-Copy perform the following steps: 1. Define a plain and bounded type in an IDL file and generate the corresponding source code for further processing with the |Fast DDS-Gen| tool. - .. code-block:: idl + .. code-block:: omg-idl struct LoanableHelloWorld { @@ -148,6 +148,15 @@ Although Zero-Copy can be used for one or several *Fast DDS* application process it has some constraints: * Only plain types are supported. + + A plain type is a type whose CDR representation matches its in-memory representation. + This requirement avoids the copy between the CDR buffer and the user buffer because the data representation is the + same. + Consequently, only :ref:`primitive types` (except ``string``), arrays of these primitive + types, and structures with FINAL :ref:`extensibility` and members of these primitive types, + are considered to be plain (Fast DDS also provides an API to check if a defined type is plain: + |TypeSupport::is_plain-api|). + * Constraints for :ref:`datasharing delivery` also apply. .. note:: diff --git a/docs/fastddsgen/dataTypes/dataTypes.rst b/docs/fastddsgen/dataTypes/dataTypes.rst index cb0edbc0d..7d9b351a3 100644 --- a/docs/fastddsgen/dataTypes/dataTypes.rst +++ b/docs/fastddsgen/dataTypes/dataTypes.rst @@ -146,7 +146,7 @@ Furthermore, :func:`set` and :func:`get` member functions are created to access The following IDL structure: -.. code-block:: idl +.. code-block:: omg-idl struct Structure { @@ -164,7 +164,7 @@ Would be converted to: Structures can inherit from other structures, extending their member set. -.. code-block:: idl +.. code-block:: omg-idl struct ParentStruct { @@ -183,6 +183,80 @@ In this case, the resulting C++ code will be: :start-after: // STRUCTURE_INHERITANCE :end-before: //! +.. _optional_members: + +Optional members +"""""""""""""""" + +A member of a structure can be optional. +This is achieved by writing the ``@optional`` annotation before the member. + +.. code-block:: omg-idl + + struct StructWithOptionalMember + { + @optional octet octet_opt; + }; + +An optional member is converted into a template class ``eprosima::fastcdr::optional``, where ``T`` is the member's +type. + +.. literalinclude:: /../code/FastDDSGenCodeTester.cpp + :language: c++ + :start-after: // STRUCTURE_WITH_OPTIONAL + :end-before: //! + +Before reading the value of the optional member, it should be checked the optional contains a value using +``has_value()`` function. +Accessing a *null* optional throws a ``eprosima::fastcdr::exception::BadOptionalAccessException`` exception. + +.. literalinclude:: /../code/FastDDSGenCodeTester.cpp + :language: c++ + :start-after: // ACCESSING_OPTIONAL_VALUE + :dedent: 4 + :end-before: //! + +.. _extensibility: + +Extensibility +""""""""""""" + +In order to support evolving types without breaking interoperability, the concept of type extensibility is supported by +*Fast DDS-Gen*. +There are three extensibility kinds: *final*, *appendable* and *mutable*. + +* *FINAL* extensibility indicates that the type is strictly defined. It is not possible to add members while maintaining + type assignability. +* *APPENDABLE* extensibility indicates that two types, where one contains all of the members of the other plus + additional members appended to the end, may remain assignable. +* *MUTABLE* extensibility indicates that two types may differ from one another in the additional, removal, and/or + transposition of members while remaining assignable. + +.. code-block:: omg-idl + + @extensibility(FINAL) + struct FinalStruct + { + octet octet_opt; + }; + + @extensibility(APPENDABLE) + struct AppendableStruct + { + octet octet_opt; + }; + + @extensibility(MUTABLE) + struct MutableStruct + { + octet octet_opt; + }; + +.. note:: + + XCDRv1 encoding algorithm is not able to manage correctly the deserialization of an appendable structure when it is + used as a member of another one. + Unions ^^^^^^ @@ -192,7 +266,7 @@ An IDL union type is mapped as a C++ class with member functions to access the u The following IDL union: -.. code-block:: idl +.. code-block:: omg-idl union Union switch(long) { @@ -220,7 +294,7 @@ Each member is defined as *bitfield* and eases the access to a part of the bitse For example: -.. code-block:: idl +.. code-block:: omg-idl bitset MyBitset { @@ -251,7 +325,7 @@ uses ``int32_t`` instead of automatically use ``uint16_t``. Bitsets can inherit from other bitsets, extending their member set. -.. code-block:: idl +.. code-block:: omg-idl bitset ParentBitset { @@ -281,7 +355,7 @@ An IDL enumeration type is mapped directly to the corresponding C++11 enumeratio The following IDL enumeration: -.. code-block:: idl +.. code-block:: omg-idl enum Enumeration { @@ -305,7 +379,7 @@ It allows defining bit masks based on their position. The following IDL bitmask: -.. code-block:: idl +.. code-block:: omg-idl @bit_bound(8) bitmask MyBitMask @@ -334,15 +408,15 @@ Data types with a key ^^^^^^^^^^^^^^^^^^^^^ In order to use keyed topics, the user should define some key members inside the structure. -This is achieved by writing the ``@Key`` annotation before the members of the structure that are used as keys. +This is achieved by writing the ``@key`` annotation before the members of the structure that are used as keys. For example in the following IDL file the *id* and *type* field would be the keys: -.. code-block:: idl +.. code-block:: omg-idl struct MyType { - @Key long id; - @Key string type; + @key long id; + @key string type; long positionX; long positionY; }; @@ -375,7 +449,7 @@ The application allows the user to define and use their own annotations as defin `OMG IDL 4.2 specification `_. User annotations will be passed to TypeObject generated code if the ``-typeobject`` argument was used. -.. code-block:: idl +.. code-block:: omg-idl @annotation MyAnnotation { @@ -392,16 +466,16 @@ Additionally, the following standard annotations are builtin (recognized and pas +-------------------------+--------------------------------------------------------------------------------------------+ | @autoid | [Unimplemented] Automatically allocate identifiers to the elements. | +-------------------------+--------------------------------------------------------------------------------------------+ -| @optional | [Unimplemented] Setting an element as optional. | +| @optional | Setting an element as optional. More info in `Optional Members`_. | +-------------------------+--------------------------------------------------------------------------------------------+ -| @extensibility | [Unimplemented] Applied to any element which is constructed. Allow specifying how the |br| | -| | element is allowed to evolve. | +| @extensibility | Applied to any element which is constructed. Allow specifying how the |br| | +| | element is allowed to evolve. More info in Extensibility_. | +-------------------------+--------------------------------------------------------------------------------------------+ -| @final | [Unimplemented] Shortcut for `@extensibility(FINAL)` | +| @final | Shortcut for `@extensibility(FINAL)` | +-------------------------+--------------------------------------------------------------------------------------------+ -| @appendable | [Unimplemented] Shortcut for `@extensibility(APPENDABLE)` | +| @appendable | Shortcut for `@extensibility(APPENDABLE)` | +-------------------------+--------------------------------------------------------------------------------------------+ -| @mutable | [Unimplemented] Shortcut for `@extensibility(MUTABLE)` | +| @mutable | Shortcut for `@extensibility(MUTABLE)` | +-------------------------+--------------------------------------------------------------------------------------------+ | @position | Setting a position to an element or group of elements. Used by bitmasks_. | +-------------------------+--------------------------------------------------------------------------------------------+ @@ -454,7 +528,7 @@ Forward declaration *Fast DDS-Gen* supports forward declarations. This allows declaring inter-dependant structures, unions, etc. -.. code-block:: idl +.. code-block:: omg-idl struct ForwardStruct; @@ -507,7 +581,7 @@ There are two ways to write IDL comments: Please refer to the `IDL 4.2 specification `_ (*Section 7.2 Lexical Conventions*) for more information on IDL conventions. -.. code-block:: idl +.. code-block:: omg-idl /* MyStruct definition */ struct MyStruc diff --git a/docs/fastddsgen/pubsub_app/includes/idl_file.rst b/docs/fastddsgen/pubsub_app/includes/idl_file.rst index 6ed492396..b74a21c7a 100644 --- a/docs/fastddsgen/pubsub_app/includes/idl_file.rst +++ b/docs/fastddsgen/pubsub_app/includes/idl_file.rst @@ -8,7 +8,7 @@ presented in :ref:`dds_layer_definition_data_types`. In the preferred text editor, create the *HelloWorld.idl* file with the following content and save it in the *FastDDSGenHelloWorld* directory. -.. code-block:: idl +.. code-block:: omg-idl // HelloWorld.idl struct HelloWorld @@ -24,4 +24,3 @@ For this, use the *Fast DDS-Gen* code generation tool, which can do two differen The second option is the one used to create this publish/subscribe application, while the first option is applied in this other tutorial: :ref:`writing_pubsub_app`. - diff --git a/docs/fastddsgen/pubsub_app/includes/workspace.rst b/docs/fastddsgen/pubsub_app/includes/workspace.rst index 931cb3e2d..e74810232 100644 --- a/docs/fastddsgen/pubsub_app/includes/workspace.rst +++ b/docs/fastddsgen/pubsub_app/includes/workspace.rst @@ -21,6 +21,8 @@ The file ``build/HelloWorld`` is the generated *Fast DDS* application. ├── HelloWorld.cxx ├── HelloWorld.h ├── HelloWorld.idl + ├── HelloWorldCdrAux.hpp + ├── HelloWorldCdrAux.ipp ├── HelloWorldPublisher.cxx ├── HelloWorldPublisher.h ├── HelloWorldPubSubMain.cxx diff --git a/docs/fastddsgen/usage/usage.rst b/docs/fastddsgen/usage/usage.rst index e457283b6..9ac4a132a 100644 --- a/docs/fastddsgen/usage/usage.rst +++ b/docs/fastddsgen/usage/usage.rst @@ -53,50 +53,49 @@ Where the option choices are: * - Option - Description - * - -help - - Shows the help information - * - -version - - Shows the current version of eProsima *Fast DDS-Gen*. + * - -cs + - Enables Case Sensitivity * - -d - Sets the output directory where the generated files are created. - * - -I - - Add directory to preprocessor include paths. - * - -t - - Sets a specific directory as a temporary directory. + * - -default_extensibility |br| + -de + - Sets the default extensibility for types without the @extensibility annotation. |br| + Values: |br| + - final |br| + - appendable (default) |br| + - mutable * - -example - Generates an example and a solution to compile the generated source code for a specific |br| platform. The help command shows the supported platforms. - * - -replace - - Replaces the generated source code files even if they exist. + * - -extrastg