rti::core::RtpsWellKnownPorts Class Reference

<<extension>> Configures the mapping of the RTPS well-known ports More...

#include <rti/core/policy/CorePolicy.hpp>

Public Member Functions
	RtpsWellKnownPorts ()
	Creates an instance that contains the default RTPS well-known ports.
	RtpsWellKnownPorts (int32_t the_port_base, int32_t the_domain_id_gain, int32_t the_participant_id_gain, int32_t the_builtin_multicast_port_offset, int32_t the_builtin_unicast_port_offset, int32_t the_user_multicast_port_offset, int32_t the_user_unicast_port_offset)
	Creates an instance with the specified ports.
int32_t	port_base () const
	Getter (see setter with the same name)
RtpsWellKnownPorts &	port_base (int32_t the_port_base)
	The base port offset.
int32_t	domain_id_gain () const
	Getter (see setter with the same name)
RtpsWellKnownPorts &	domain_id_gain (int32_t the_domain_id_gain)
	Tunable domain gain parameter.
int32_t	participant_id_gain () const
	Getter (see setter with the same name)
RtpsWellKnownPorts &	participant_id_gain (int32_t the_participant_id_gain)
	Tunable participant gain parameter.
int32_t	builtin_multicast_port_offset () const
	Getter (see setter with the same name)
RtpsWellKnownPorts &	builtin_multicast_port_offset (int32_t the_builtin_multicast_port_offset)
	Additional offset for metatraffic multicast port.
int32_t	builtin_unicast_port_offset () const
	Getter (see setter with the same name)
RtpsWellKnownPorts &	builtin_unicast_port_offset (int32_t the_builtin_unicast_port_offset)
	Additional offset for metatraffic unicast port.
int32_t	user_multicast_port_offset () const
	Getter (see setter with the same name)
RtpsWellKnownPorts &	user_multicast_port_offset (int32_t the_user_multicast_port_offset)
	Additional offset for usertraffic multicast port.
int32_t	user_unicast_port_offset () const
	Getter (see setter with the same name)
RtpsWellKnownPorts &	user_unicast_port_offset (int32_t the_user_unicast_port_offset)
	Additional offset for usertraffic unicast port.

Static Public Member Functions
static RtpsWellKnownPorts	Interoperable ()
	Returns an instance containing the port mapping compliant with the OMG DDS Interoperability wire protocol.
static RtpsWellKnownPorts	BackwardsCompatible ()
	Returns an instance containing the port mapping compatible with previous versions of RTI Connext.

Detailed Description

<<extension>> Configures the mapping of the RTPS well-known ports

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 rti::core::RtpsWellKnownPorts. 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 rti::core::RtpsWellKnownPorts, the port numbers depend on:

- domain_id, as specified in dds::domain::DomainParticipant()

- participant_id, as specified using rti::core::policy::WireProtocol::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 rti::core::policy::Discovery::multicast_receive_addresses on a dds::domain::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 rti::core::policy::TransportMulticast, rti::core::policy::TransportUnicast, or by the rti::core::policy::TransportUnicast 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 rti::core::policy::TransportMulticast.

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 rti::core::RtpsWellKnownPorts::Interoperable()).

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:

rti::core::policy::WireProtocol

Constructor & Destructor Documentation

rti::core::RtpsWellKnownPorts::RtpsWellKnownPorts ( )

inline

Creates an instance that contains the default RTPS well-known ports.

rti::core::RtpsWellKnownPorts::RtpsWellKnownPorts ( int32_t  the_port_base, int32_t  the_domain_id_gain, int32_t  the_participant_id_gain, int32_t  the_builtin_multicast_port_offset, int32_t  the_builtin_unicast_port_offset, int32_t  the_user_multicast_port_offset, int32_t  the_user_unicast_port_offset  )

inline

Creates an instance with the specified ports.

See individual setters.

Member Function Documentation

int32_t rti::core::RtpsWellKnownPorts::port_base ( ) const

inline

Getter (see setter with the same name)

RtpsWellKnownPorts& rti::core::RtpsWellKnownPorts::port_base ( int32_t  the_port_base )

inline

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.

int32_t rti::core::RtpsWellKnownPorts::domain_id_gain ( ) const

inline

Getter (see setter with the same name)

RtpsWellKnownPorts& rti::core::RtpsWellKnownPorts::domain_id_gain ( int32_t  the_domain_id_gain )

inline

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::domain::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::domain::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.

int32_t rti::core::RtpsWellKnownPorts::participant_id_gain ( ) const

inline

Getter (see setter with the same name)

RtpsWellKnownPorts& rti::core::RtpsWellKnownPorts::participant_id_gain ( int32_t  the_participant_id_gain )

inline

Tunable participant gain parameter.

Multiplier of the participant_id. See rti::core::RtpsWellKnownPorts::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.

int32_t rti::core::RtpsWellKnownPorts::builtin_multicast_port_offset ( ) const

inline

Getter (see setter with the same name)

RtpsWellKnownPorts& rti::core::RtpsWellKnownPorts::builtin_multicast_port_offset ( int32_t  the_builtin_multicast_port_offset )

inline

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.

int32_t rti::core::RtpsWellKnownPorts::builtin_unicast_port_offset ( ) const

inline

Getter (see setter with the same name)

RtpsWellKnownPorts& rti::core::RtpsWellKnownPorts::builtin_unicast_port_offset ( int32_t  the_builtin_unicast_port_offset )

inline

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.

int32_t rti::core::RtpsWellKnownPorts::user_multicast_port_offset ( ) const

inline

Getter (see setter with the same name)

RtpsWellKnownPorts& rti::core::RtpsWellKnownPorts::user_multicast_port_offset ( int32_t  the_user_multicast_port_offset )

inline

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.

int32_t rti::core::RtpsWellKnownPorts::user_unicast_port_offset ( ) const

inline

Getter (see setter with the same name)

RtpsWellKnownPorts& rti::core::RtpsWellKnownPorts::user_unicast_port_offset ( int32_t  the_user_unicast_port_offset )

inline

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.