Improve locators documentation (#558)

* Refs #19570: Improve locators documentation Signed-off-by: JesusPoderoso <[email protected]> * Refs #19570: Apply rev suggestions Signed-off-by: JesusPoderoso <[email protected]> * Refs #19570: Include wan specification Signed-off-by: JesusPoderoso <[email protected]> * Refs #19570: Apply rev suggestions Signed-off-by: JesusPoderoso <[email protected]> * Refs #19570: Fix spelling Signed-off-by: EduPonz <[email protected]> --------- Signed-off-by: JesusPoderoso <[email protected]> Signed-off-by: EduPonz <[email protected]> Co-authored-by: EduPonz <[email protected]>
eProsima · Sep 29, 2023 · e237870 · e237870
1 parent 632eff7
commit e237870
Show file tree

Hide file tree

Showing 3 changed files with 33 additions and 0 deletions.
diff --git 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
@@ -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 <api_tcpv4_transport_descriptor>`
+section.
+
 .. _transport_transportApi_ipLocator:
 
 Configuring IP locators with IPLocator

diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
@@ -231,6 +231,7 @@ submessage
 submessages
 submodule
 submodules
+subnet
 superset
 takeNextData
 TCP