From e2378701fb35bc98c03385f7963775ddd1e0bf1b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Poderoso?= <120394830+JesusPoderoso@users.noreply.github.com> Date: Fri, 29 Sep 2023 11:45:41 +0200 Subject: [PATCH] Improve locators documentation (#558) * Refs #19570: Improve locators documentation Signed-off-by: JesusPoderoso * Refs #19570: Apply rev suggestions Signed-off-by: JesusPoderoso * Refs #19570: Include wan specification Signed-off-by: JesusPoderoso * Refs #19570: Apply rev suggestions Signed-off-by: JesusPoderoso * Refs #19570: Fix spelling Signed-off-by: EduPonz --------- Signed-off-by: JesusPoderoso Signed-off-by: EduPonz Co-authored-by: EduPonz --- .../api_reference/spelling_wordlist.txt | 1 + docs/fastdds/transport/transport_api.rst | 31 +++++++++++++++++++ docs/spelling_wordlist.txt | 1 + 3 files changed, 33 insertions(+) diff --git a/docs/fastdds/api_reference/spelling_wordlist.txt b/docs/fastdds/api_reference/spelling_wordlist.txt index 57d33f115..4821e7391 100644 --- a/docs/fastdds/api_reference/spelling_wordlist.txt +++ b/docs/fastdds/api_reference/spelling_wordlist.txt @@ -109,6 +109,7 @@ PartitionQosPolicy PDPListener periodMillisecs Pid +PortBasedTransportDescriptor pos preallocate PresentationQosPolicy diff --git a/docs/fastdds/transport/transport_api.rst b/docs/fastdds/transport/transport_api.rst index c1cdc5bb1..cb8e81521 100644 --- a/docs/fastdds/transport/transport_api.rst +++ b/docs/fastdds/transport/transport_api.rst @@ -182,11 +182,42 @@ In TCP, the port of the locator is divided into a physical and a logical port. * The *physical port* is the port used by the network device, the real port that the operating system understands. It is stored in the two least significant bytes of the member |Locator_t::port-api|. * The *logical port* is the RTPS port. + It is used by the RTPS protocol to distinguish different entities. It is stored in the two most significant bytes of the member |Locator_t::port-api|. +In TCP, this distinction allows for several DDS applications using different RTPS ports (*logical ports*) to share the +same *physical port*, thus only requiring for a single port to be opened for all communications. In UDP there is only the *physical port*, which is also the RTPS port, and is stored in the two least significant bytes of the member |Locator_t::port-api|. +The locator address, represented in 16 bytes, is managed differently depending on whether the protocol used is IPv4 or +IPv6. + +* The IPv6 address uses the 16 available bytes to represent a unique and global address. +* The IPv4 address splits those 16 bytes in the following three sections, ordered from least to greatest significance: + + - 4 bytes LAN IP: Local subnet identification (UDP and TCP). + - 4 bytes WAN IP: Public IP (TCP only). + - 8 bytes unused. + +.. code-block:: idl + + Locator IPv4 address + +--------+-----------------------------+-----------------------------+ + | Unused | WAN address (62.128.41.210) | LAN address (192.168.0.113) | + +--------+-----------------------------+-----------------------------+ + 8 bytes (TCP only) 4 bytes 4 bytes + + + Locator IPv6 address + +--------------------------------------------------------------------+ + | Address (2001:0000:130F:0000:0000:09C0:876A:130B) | + +--------------------------------------------------------------------+ + 16 bytes + +Check how to manipulate the WAN address in the :ref:`TCP IPv4 transport descriptor api ` +section. + .. _transport_transportApi_ipLocator: Configuring IP locators with IPLocator diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index 6e7a9785b..a09ca82c5 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -231,6 +231,7 @@ submessage submessages submodule submodules +subnet superset takeNextData TCP