.. _DDS_WireProtocolQosPolicy: ../../../api_c/html/structDDS__WireProtocolQosPolicy.html
.. _rtps_well_known_ports: ../../../api_c/html/structDDS__WireProtocolQosPolicy.html

Transport Addresses
-------------------

In order for DDS entities to communicate, the DDS entities must know 
each other's location. DDS entities may be colocated in the same 
DDS *DomainParticipant*, may be located in different DDS *DomainParticipants* 
within the same node, or may be located on different nodes connected by 
a network. 

In DDS, a location is called a *locator*. A locator uniquely describes 
how to reach one or more DDS entitites in a network. A DDS locator 
consists of the following parts:

- The locator *kind* identifies the type of locators, e.g. UDPv4.
- The locator *port* identifies the location of DDS entities at an address.
  The port number of a locator is not directly configurable; rather, 
  it is configured indirectly by the DDS_WireProtocolQosPolicy_ 
  (rtps_well_known_ports_) of the *DomainParticipant's* QoS, where a 
  well-known, interoperable RTPS port number is assigned.
- The locator *address* indentifies the network address. Transports are
  concerned with exchanging messages using the network address.


Reserving Addresses and Ports
.............................
 
Address reservation is the process to determine which locators should be 
used in the discovery announcement. Which transports and addresses to be used 
are determined as described in :doc:`../discovery`.

When a *DomainParticipant* is created, it calculates a port number and tries to 
reserve this port on all addresses available in *all* the transports based 
on the registration properties. If the port cannot be reserved on all 
transports, then it releases the port on *all* transports and tries again. If 
no free port can be found, the process fails and the *DomainParticipant* cannot 
be created.

.. warning::

  If an address is specified without the transport name as a prefix, 
  e.g. "192.168.1.1" instead of "_udp://192.168.1.1", and multiple transports 
  understand the address, only the *last* transport found will try to reserve 
  the address. Which transport is the *last* is non-determinstic. This 
  capability is present to be backwards compatible with earlier versions of 
  |me|, but **should not be used**; this feature may be deprecated in  
  future versions. Always specify addresses using the transport name as the 
  prefix.


Address Limitations
...................

The number of locators which can be announced is limited to *only* 
the first *four* of each type, across *all* transports available for 
each policy. If more than four are available of any type, these are *ignored*.
This is by design, although it may be changed in future versions. The order in 
which the locators are read is also not known, thus the exact four locators 
which will be used are not deterministic.

To ensure that *all* the desired addresses and *only* the desired address
are used in a transport, follow these rules:

- Make sure that no more than four unicast addresses and four multicast
  addresses can be returned across *all* transports for discovery traffic.
     
- Make sure that no more than four unicast addresses and four multicast
  addresses can be returned across *all* transports for user traffic.

- Make sure that no more than four unicast addresses and four multicast
  addresses can be returned across *all* transports for user-traffic,
  for *DataReader* and *DataWriter* specific locators, and that they do
  *not* duplicate any of the *DomainParticipant*’s locators.

  
Address Notation
................

In |me|, all addresses are specified as ASCII strings. The full 
address format is:

.. code-block:: none

  < > denotes optional   
  [ ] denotes range or discreet values, unless enclosed in ''
      which means a literal.
        
  ADDRESS = <PREFIX://><ADDRESS> |
            @<PREFIX://><ADDRESS> | 
            INDEX@<PREFIX>://<ADDRESS>
        
  INDEX = INTEGER | '[' INTEGER ']' | '[' INTEGER-INTEGER ']' | '[' -INTEGER ']'
        
  PREFIX = [a-zA-Z_][0-9a-zA-Z_]+
        
  INTEGER = DEC_INTEGER | HEX_INTEGER
        
  DEC_INTEGER = [0-9]+ 

  HEX_INTEGER = [0x|0X][0-9a-fA-F]+ 
        
  ADDRESS = 0 or more 8bit characters

Note that while the ``PREFIX`` is marked optional, it should always be used.