DDS_RtpsWellKnownPorts_t Struct Reference

RTPS well-known port mapping configuration. More...

Data Fields
DDS_Long	port_base
	The base port offset.
DDS_Long	domain_id_gain
	Tunable domain gain parameter.
DDS_Long	participant_id_gain
	Tunable participant gain parameter.
DDS_Long	builtin_multicast_port_offset
	Additional offset for metatraffic multicast port.
DDS_Long	builtin_unicast_port_offset
	Additional offset for metatraffic unicast port.
DDS_Long	user_multicast_port_offset
	Additional offset for usertraffic multicast port.
DDS_Long	user_unicast_port_offset
	Additional offset for usertraffic unicast port.

Detailed Description

RTPS well-known port mapping configuration.

RTI Connext uses the RTPS wire protocol. The discovery protocols defined by RTPS rely on well-known ports to initiate discovery. These well-known ports define the multicast and unicast ports on which a Participant will listen for discovery metatraffic from other Participants. The discovery metatraffic contains all the information required to establish the presence of remote DDS entities in the network.

The well-known ports are defined by RTPS in terms of port mapping expressions with several tunable parameters, which allow you to customize what network ports are used by RTI Connext. These parameters are exposed in DDS_RtpsWellKnownPorts_t. In order for all Participants in a system to correctly discover each other, it is important that they all use the same port mapping expressions.

The actual port mapping expressions, as defined by the RTPS specification, can be found below. In addition to the parameters listed in DDS_RtpsWellKnownPorts_t, the port numbers depend on:

- domain_id, as specified in DDS_DomainParticipantFactory_create_participant

- participant_id, as specified using DDS_WireProtocolQosPolicy::participant_id

The domain_id parameter ensures no port conflicts exist between Participants belonging to different domains. This also means that discovery metatraffic in one domain is not visible to Participants in a different domain. The participant_id parameter ensures that unique unicast port numbers are assigned to Participants belonging to the same domain on a given host.

The metatraffic_unicast_port is used to exchange discovery metatraffic using unicast.

metatraffic_unicast_port = port_base + (domain_id_gain * domain_id) + (participant_id_gain * participant_id) + builtin_unicast_port_offset 

The metatraffic_multicast_port is used to exchange discovery metatraffic using multicast. The corresponding multicast group addresses are specified via DDS_DiscoveryQosPolicy::multicast_receive_addresses on a DDS_DomainParticipant entity.

metatraffic_multicast_port = port_base + (domain_id_gain * domain_id) + builtin_multicast_port_offset 

RTPS also defines the default multicast and unicast ports on which DataReaders and DataWriters receive usertraffic. These default ports can be overridden using the DDS_DataReaderQos::multicast, DDS_DataReaderQos::unicast, or by the DDS_DataWriterQos::unicast QoS policies.

The usertraffic_unicast_port is used to exchange user data using unicast.

usertraffic_unicast_port = port_base + (domain_id_gain * domain_id) + (participant_id_gain * participant_id) + user_unicast_port_offset 

The usertraffic_multicast_port is used to exchange user data using multicast. The corresponding multicast group addresses can be configured using DDS_TransportMulticastQosPolicy.

usertraffic_multicast_port = port_base + (domain_id_gain * domain_id) + user_multicast_port_offset 

By default, the port mapping parameters are configured to compliant with OMG's DDS Interoperability Wire Protocol (see also DDS_INTEROPERABLE_RTPS_WELL_KNOWN_PORTS).

The OMG's DDS Interoperability Wire Protocol compliant port mapping parameters are not backwards compatible with previous versions of the RTI Connext middleware.

When modifying the port mapping parameters, care must be taken to avoid port aliasing. This would result in undefined discovery behavior. The chosen parameter values will also determine the maximum possible number of domains in the system and the maximum number of participants per domain. Additionally, any resulting mapped port number must be within the range imposed by the underlying transport. For example, for UDPv4, this range typically equals [1024 - 65535].

QoS:

DDS_WireProtocolQosPolicy

Field Documentation

DDS_Long DDS_RtpsWellKnownPorts_t::port_base

The base port offset.

All mapped well-known ports are offset by this value.

[default] 7400

[range] [>= 1], but resulting ports must be within the range imposed by the underlying transport.

DDS_Long DDS_RtpsWellKnownPorts_t::domain_id_gain

Tunable domain gain parameter.

Multiplier of the domain_id. Together with participant_id_gain, it determines the highest domain_id and participant_id allowed on this network.

In general, there are two ways to setup domain_id_gain and participant_id_gain parameters.

If domain_id_gain > participant_id_gain, it results in a port mapping layout where all DDS_DomainParticipant instances within a single domain occupy a consecutive range of domain_id_gain ports. Precisely, all ports occupied by the domain fall within:

(port_base + (domain_id_gain * domain_id)) 

and:

(port_base + (domain_id_gain * (domain_id + 1)) - 1) 

Under such a case, the highest domain_id is limited only by the underlying transport's maximum port. The highest participant_id, however, must satisfy:

max_participant_id < (domain_id_gain / participant_id_gain) 

On the contrary, if domain_id_gain <= participant_id_gain, it results in a port mapping layout where a given domain's DDS_DomainParticipant instances occupy ports spanned across the entire valid port range allowed by the underlying transport. For instance, it results in the following potential mapping:

Mapped Port	Domain Id	Participant ID
higher port number	Domain Id = 1	Participant ID = 2
	Domain Id = 0	Participant ID = 2
	Domain Id = 1	Participant ID = 1
	Domain Id = 0	Participant ID = 1
	Domain Id = 1	Participant ID = 0
lower port number	Domain Id = 0	Participant ID = 0

Under this case, the highest participant_id is limited only by the underlying transport's maximum port. The highest domain_id, however, must satisfy:

max_domain_id < (participant_id_gain / domain_id_gain) 

Additionally, domain_id_gain also determines the range of the port-specific offsets.

domain_id_gain > abs(builtin_multicast_port_offset - user_multicast_port_offset) 

domain_id_gain > abs(builtin_unicast_port_offset - user_unicast_port_offset) 

Violating this may result in port aliasing and undefined discovery behavior.

[default] 250

[range] [> 0], but resulting ports must be within the range imposed by the underlying transport.

DDS_Long DDS_RtpsWellKnownPorts_t::participant_id_gain

Tunable participant gain parameter.

Multiplier of the participant_id. See DDS_RtpsWellKnownPorts_t::domain_id_gain for its implications on the highest domain_id and participant_id allowed on this network.

Additionally, participant_id_gain also determines the range of builtin_unicast_port_offset and user_unicast_port_offset.

participant_id_gain > abs(builtin_unicast_port_offset - user_unicast_port_offset) 

[default] 2

[range] [> 0], but resulting ports must be within the range imposed by the underlying transport.

DDS_Long DDS_RtpsWellKnownPorts_t::builtin_multicast_port_offset

Additional offset for metatraffic multicast port.

It must be unique from other port-specific offsets.

[default] 0

[range] [>= 0], but resulting ports must be within the range imposed by the underlying transport.

DDS_Long DDS_RtpsWellKnownPorts_t::builtin_unicast_port_offset

Additional offset for metatraffic unicast port.

It must be unique from other port-specific offsets.

[default] 10

[range] [>= 0], but resulting ports must be within the range imposed by the underlying transport.

DDS_Long DDS_RtpsWellKnownPorts_t::user_multicast_port_offset

Additional offset for usertraffic multicast port.

It must be unique from other port-specific offsets.

[default] 1

[range] [>= 0], but resulting ports must be within the range imposed by the underlying transport.

DDS_Long DDS_RtpsWellKnownPorts_t::user_unicast_port_offset

Additional offset for usertraffic unicast port.

It must be unique from other port-specific offsets.

[default] 11

[range] [>= 0], but resulting ports must be within the range imposed by the underlying transport.