6.7. Listening Locators

Listening Locators are used to receive incoming traffic on the DomainParticipant. These Locators can be classified according to the communication type and to the nature of the data.

According to the communication type we have:

  • Multicast locators: Listen to multicast communications.

  • Unicast locators: Listen to unicast communications.

According to the nature of the data we have:

  • Metatraffic locators: Used to receive metatraffic information, usually used by built-in endpoints to perform discovery.

  • User locators: Used by the endpoints created by the user to receive user Topic data changes.

Applications can provide their own Listening Locators, or use the Default Listening Locators provided by eProsima Fast DDS.

6.7.1. Adding Listening Locators

Users can add custom Listening Locators to the DomainParticipant using the DomainParticipantQos. Depending on the field where the Locator is added, it will be treated as a multicast, unicast, user or metatraffic Locator.

Note

Both UDP and TCP unicast Locators support to have a null address. In that case, Fast DDS automatically gets and uses local network addresses.

Note

Both UDP and TCP Locators support to have a zero port. In that case, Fast DDS automatically calculates and uses well-known ports for that type of traffic. See Well Known Ports for details about the well-known ports.

Warning

TCP does not support multicast scenarios, so the network architecture must be carefully planned.

6.7.1.1. Metatraffic Multicast Locators

Users can set their own metatraffic multicast locators using the field wire_protocol().builtin.metatrafficMulticastLocatorList.

C++

DomainParticipantQos qos;

// This locator will open a socket to listen network messages
// on UDPv4 port 22222 over multicast address 239.255.0.1
eprosima::fastrtps::rtps::Locator_t locator;
IPLocator::setIPv4(locator, 239, 255, 0, 1);
locator.port = 22222;

// Add the locator to the DomainParticipantQos
qos.wire_protocol().builtin.metatrafficMulticastLocatorList.push_back(locator);

XML

<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
    <participant profile_name="CustomMetatrafficMulticastParticipant">
        <rtps>
            <builtin>
                <metatrafficMulticastLocatorList>
                    <!-- LOCATOR_LIST -->
                    <locator>
                        <udpv4>
                            <address>239.255.0.1</address>
                            <port>22222</port>
                        </udpv4>
                    </locator>
                </metatrafficMulticastLocatorList>
            </builtin>
        </rtps>
    </participant>
</profiles>

6.7.1.2. Metatraffic Unicast Locators

Users can set their own metatraffic unicast locators using the field wire_protocol().builtin.metatrafficUnicastLocatorList.

C++

DomainParticipantQos qos;

// This locator will open a socket to listen network messages
// on UDPv4 port 22223 over address 192.168.0.1
eprosima::fastrtps::rtps::Locator_t locator;
IPLocator::setIPv4(locator, 192, 168, 0, 1);
locator.port = 22223;

// Add the locator to the DomainParticipantQos
qos.wire_protocol().builtin.metatrafficUnicastLocatorList.push_back(locator);

XML

<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
    <participant profile_name="CustomMetatrafficUnicastParticipant">
        <rtps>
            <builtin>
                <metatrafficUnicastLocatorList>
                    <!-- LOCATOR_LIST -->
                    <locator>
                        <udpv4>
                            <address>192.168.0.1</address>
                            <port>22223</port>
                        </udpv4>
                    </locator>
                </metatrafficUnicastLocatorList>
            </builtin>
        </rtps>
    </participant>
</profiles>

6.7.1.3. User-traffic Multicast Locators

Users can set their own user-traffic multicast locators using the field wire_protocol().default_multicast_locator_list.

C++

DomainParticipantQos qos;

// This locator will open a socket to listen network messages
// on UDPv4 port 22224 over multicast address 239.255.0.1
eprosima::fastrtps::rtps::Locator_t locator;
IPLocator::setIPv4(locator, 239, 255, 0, 1);
locator.port = 22224;

// Add the locator to the DomainParticipantQos
qos.wire_protocol().default_multicast_locator_list.push_back(locator);

XML

<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
    <participant profile_name="CustomUsertrafficMulticastParticipant">
        <rtps>
            <defaultMulticastLocatorList>
                <!-- LOCATOR_LIST -->
                <locator>
                    <udpv4>
                        <address>239.255.0.1</address>
                        <port>22224</port>
                    </udpv4>
                </locator>
            </defaultMulticastLocatorList>
        </rtps>
    </participant>
</profiles>

6.7.1.4. User-traffic Unicast Locators

Users can set their own user-traffic unicast locators using the field wire_protocol().default_unicast_locator_list.

C++

DomainParticipantQos qos;

// This locator will open a socket to listen network messages
// on UDPv4 port 22225 over address 192.168.0.1
eprosima::fastrtps::rtps::Locator_t locator;
IPLocator::setIPv4(locator, 192, 168, 0, 1);
locator.port = 22225;

// Add the locator to the DomainParticipantQos
qos.wire_protocol().default_unicast_locator_list.push_back(locator);

XML

<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
    <participant profile_name="CustomUsertrafficUnicastParticipant">
        <rtps>
            <defaultUnicastLocatorList>
                <!-- LOCATOR_LIST -->
                <locator>
                    <udpv4>
                        <address>192.168.0.1</address>
                        <port>22225</port>
                    </udpv4>
                </locator>
            </defaultUnicastLocatorList>
        </rtps>
    </participant>
</profiles>

6.7.2. Default Listening Locators

If the application does not define any Listening Locators, eProsima Fast DDS automatically enables a set of listening UDPv4 locators by default. This allows out-of-the-box communication in most cases, without the need of further configuring the Transport Layer.

  • If the application does not define any metatraffic Locator (neither unicast nor multicast), Fast DDS enables one multicast Locator that will be used during Discovery, and one unicast Locator that will be used for peer-to-peer communication with already discovered DomainParticipants.

  • If the application does not define any user-traffic Locator (neither unicast nor multicast), Fast DDS enables one unicast Locator that will be used for peer-to-peer communication of Topic data.

For example, it is possible to prevent multicast traffic adding a single user-traffic unicast Locator as described in Disabling all Multicast Traffic.

Default Listening Locators always use Well Known Ports.

6.7.3. Well Known Ports

The DDSI-RTPS V2.2 standard (Section 9.6.1.1) defines a set of rules to calculate well-known ports for default Locators, so that DomainParticipants can communicate with these default Locators. Well-known ports are also selected automatically by Fast DDS when a Locator is configured with port number 0.

Well-known ports are calculated using the following predefined rules:

Rules to calculate ports on default listening locators

Traffic type

Well-known port expression

Metatraffic multicast

PB + DG * domainId + offsetd0

Metatraffic unicast

PB + DG * domainId + offsetd1 + PG * participantId

User multicast

PB + DG * domainId + offsetd2

User unicast

PB + DG * domainId + offsetd3 + PG * participantId

The values used in these rules are explained on the following table. The default values can be modified using the corresponding field on the DomainParticipantQos.

Values used in the rules to calculate well-known ports

Symbol

Meaning

Default value

QoS field

DG

DomainID gain

250

wire_protocol().port.domainIDGain

PG

ParticipantId gain

2

wire_protocol().port.participantIDGain

PB

Port Base number

7400

wire_protocol().port.portBase

offsetd0

Additional offset

0

wire_protocol().port.offsetd0

offsetd1

Additional offset

10

wire_protocol().port.offsetd1

offsetd2

Additional offset

1

wire_protocol().port.offsetd2

offsetd3

Additional offset

11

wire_protocol().port.offsetd3