RTI Connext Modern C++ API  Version 7.0.0
rti::core::policy::WireProtocol Class Reference

<<extension>> Configures the write protocol of a dds::domain::DomainParticipant More...

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

Public Member Functions

 WireProtocol ()
 Creates the default policy. More...
 
WireProtocolparticipant_id (int32_t the_participant_id)
 A value used to distinguish among different participants belonging to the same domain on the same host. More...
 
int32_t participant_id () const
 Getter (see the setter with the same name) More...
 
WireProtocolrtps_host_id (uint32_t the_rtps_host_id)
 The RTPS Host ID of the domain participant. More...
 
uint32_t rtps_host_id () const
 Getter (see the setter with the same name) More...
 
WireProtocolrtps_app_id (uint32_t the_rtps_app_id)
 The RTPS App ID of the domain participant. More...
 
uint32_t rtps_app_id () const
 Getter (see the setter with the same name) More...
 
WireProtocolrtps_instance_id (uint32_t the_rtps_instance_id)
 The RTPS Instance ID of the dds::domain::DomainParticipant. More...
 
uint32_t rtps_instance_id () const
 Getter (see the setter with the same name) More...
 
WireProtocolrtps_well_known_ports (const rti::core::RtpsWellKnownPorts &the_rtps_well_known_ports)
 Configures the RTPS well-known port mappings. More...
 
rti::core::RtpsWellKnownPorts rtps_well_known_ports () const
 Getter (see the setter with the same name) More...
 
WireProtocolrtps_reserved_port_mask (const RtpsReservedPortKindMask &the_rtps_reserved_port_mask)
 Specifies which well-known ports to reserve when enabling the participant. More...
 
RtpsReservedPortKindMask rtps_reserved_port_mask () const
 Getter (see the setter with the same name) More...
 
WireProtocolrtps_auto_id_kind (rti::core::policy::WireProtocolAutoKind the_kind)
 Kind of auto mechanism used to calculate the GUID prefix. More...
 
rti::core::policy::WireProtocolAutoKind rtps_auto_id_kind () const
 Getter (see the setter with the same name) More...
 
WireProtocolcompute_crc (bool crc_needed)
 Adds RTPS CRC submessage to every message when this field is set to true. More...
 
bool compute_crc () const
 Getter (see the setter with the same name) More...
 
WireProtocolcheck_crc (bool crc_checked)
 Checks if the received RTPS message is valid by comparing the computed CRC with the received RTPS CRC submessage when this field is set to true. More...
 
bool check_crc () const
 Getter (see the setter with the same name) More...
 

Static Public Attributes

static OMG_DDS_API_CLASS_VARIABLE const uint32_t RTPS_AUTO_ID
 Indicates that RTI Connext should choose an appropriate host, app, instance or object ID automatically. More...
 

Detailed Description

<<extension>> Configures the write protocol of a dds::domain::DomainParticipant

Entity:
dds::domain::DomainParticipant
Properties:
RxO = N/A
Changeable = NO

Usage

This QoS policy configures some participant-wide properties of the DDS Real-Time Publish Subscribe (RTPS) on-the-wire protocol. (rti::core::policy::DataWriterProtocol and rti::core::policy::DataReaderProtocol configure RTPS and reliability properties on a per dds::pub::DataWriter or dds::sub::DataReader basis.)

NOTE: The default QoS policies returned by RTI Connext contain the correctly initialized wire protocol attributes. The defaults are not normally expected to be modified, but are available to the advanced user customizing the implementation behavior.

The default values should not be modified without an understanding of the underlying Real-Time Publish Subscribe (RTPS) wire protocol.

In order for the discovery process to work correctly, each dds::domain::DomainParticipant must have a unique identifier. This QoS policy specifies how that identifier should be generated.

RTPS defines a 96-bit prefix to this identifier; each dds::domain::DomainParticipant must have a unique value for this prefix relative to all other participants in its domain.

If an application dies unexpectedly and is restarted, the IDs used by the new instance of DomainParticipants should be different than the ones used by the previous instances. A change in these values allows other DomainParticipants to know that they are communicating with a new instance of an application, and not the previous instance.

For legacy reasons, RTI Connext divides the 96-bit prefix into three integers:

  • The first integer is called host ID. The original purpose of this integer was to contain the identity of the machine on which the DomainParticipant is executing.
  • The second integer is called an application ID. The original purpose of this integer was to contain a value that identifies the process or task in which the DomainParticipant is contained.
  • The third integer is called instance ID. The original purpose was to contain a value that uniquely identifies a DomainParticipant within a task or process.

The rti::core::policy::WireProtocol::rtps_auto_id_kind field can be used to configure the algorithm that RTI Connext uses to populate the 96-bit prefix. Then you can optionally overwrite specific parts of the 96-bit prefix by explicitly configuring the rti::core::policy::WireProtocol::rtps_host_id (first integer), rti::core::policy::WireProtocol::rtps_app_id (second integer), and rti::core::policy::WireProtocol::rtps_instance_id (third integer).

The rti::core::policy::WireProtocol::rtps_auto_id_kind field supports three different prefix generation algorithms:

  1. In the default and most common scenario, rti::core::policy::WireProtocol::rtps_auto_id_kind is set to rti::core::policy::WireProtocolAutoKind_def::RTPS_AUTO_ID_FROM_UUID. As the name suggests, this mechanism uses a unique, randomly generated UUID to fill the rtps_host_id, rtps_app_id, or rtps_instance_id fields. The first two bytes of the rtps_host_id are replaced with the RTI vendor ID (0x0101).
  2. (Legacy) When rtps_auto_id_kind is set to rti::core::policy::WireProtocolAutoKind_def::RTPS_AUTO_ID_FROM_IP, the 96-bit prefix is generated as follows:
    • rtps_host_id: The 32-bit value of the IPv4 of the first up and running interface of the host machine is assigned. If the host does not have an IPv4 address, the host-id will be automatically set to 0x7F000001.
    • rtps_app_id: The process (or task) ID is assigned.
    • rtps_instance_id: A counter is assigned that is incremented per new participant within a process.
    DDS_RTPS_AUTO_ID_FROM_IP is not a good algorithm to guarantee prefix uniqueness, because the process ID can be recycled by the OSs.
  3. (Legacy) When rtps_auto_id_kind is set to rti::core::policy::WireProtocolAutoKind_def::RTPS_AUTO_ID_FROM_MAC, the 96-bit prefix is generated as follows:

    • rtps_host_id: The first 32 bits of the MAC address of the first up and running interface of the host machine are assigned.
    • rtps_app_id: The last 32 bits of the MAC address of the first up and running interface of the host machine are assigned.
    • rtps_instance_id: This field is split into two different parts. The process (or task) ID is assigned to the first 24 bits. A counter is assigned to the last 8 bits. This counter is incremented per new participant.

    DDS_RTPS_AUTO_ID_FROM_IP is not a good algorithm to guarantee prefix uniqueness, because the process ID can be recycled by the OSs.

Some examples are provided to clarify the behavior of this QoSPolicy in case you want to change the default behavior with rti::core::policy::WireProtocolAutoKind_def::RTPS_AUTO_ID_FROM_MAC.

First, get the participant QoS from the DomainParticipantFactory:

Second, change the rti::core::policy::WireProtocol using one of the options shown below.

Third, create the dds::domain::DomainParticipant as usual, using the modified QoS structure instead of the default one.

Option 1: Use rti::core::policy::WireProtocolAutoKind_def::RTPS_AUTO_ID_FROM_MAC to explicitly set just the application/task identifier portion of the rtps_instance_id field.

using namespace rti::core::policy;
participant_qos << WireProtocol()
.rtps_auto_id_kind(WireProtocolAutoKind::RTPS_AUTO_ID_FROM_MAC)
.rtps_instance_id(
/* App ID */ (12 << 8) | /* Instance ID */ WireProtocol::RTPS_AUTO_ID);

Option 2: Handle only the per participant counter and let RTI Connext handle the application/task identifier:

using namespace rti::core::policy;
participant_qos << WireProtocol()
.rtps_auto_id_kind(WireProtocolAutoKind::RTPS_AUTO_ID_FROM_MAC)
.rtps_instance_id(
/* App ID */ WireProtocol::RTPS_AUTO_ID | /* Instance ID */ 12);

Option 3: Handle the entire rtps_instance_id field yourself:

using namespace rti::core::policy;
participant_qos << WireProtocol()
.rtps_auto_id_kind(WireProtocolAutoKind::RTPS_AUTO_ID_FROM_MAC)
.rtps_instance_id(
/* App ID */ (12 << 8) | /* Instance ID */ 9);

NOTE: If you are using rti::core::policy::WireProtocolAutoKind_def::RTPS_AUTO_ID_FROM_MAC as rtps_auto_id_kind and you decide to manually handle the rtps_instance_id field, you must ensure that both parts are non-zero (otherwise RTI Connext will take responsibility for them). RTI recommends that you always specify the two parts separately in order to avoid errors.

Option 4: Let RTI Connext handle the entire rtps_instance_id field:

using namespace rti::core::policy;
participant_qos << WireProtocol().rtps_auto_id_kind(
WireProtocolAutoKind::RTPS_AUTO_ID_FROM_MAC);

NOTE: If you are using rti::core::policy::WireProtocolAutoKind_def::RTPS_AUTO_ID_FROM_MAC as rtps_auto_id_kind and you decide to manually handle the rtps_instance_id field, you must ensure that both parts are non-zero (otherwise RTI Connext will take responsibility for them). RTI recommends that you always specify the two parts separately in order to clearly show the difference.

Constructor & Destructor Documentation

◆ WireProtocol()

rti::core::policy::WireProtocol::WireProtocol ( )
inline

Creates the default policy.

Member Function Documentation

◆ participant_id() [1/2]

WireProtocol& rti::core::policy::WireProtocol::participant_id ( int32_t  the_participant_id)

A value used to distinguish among different participants belonging to the same domain on the same host.

Determines the unicast port on which meta-traffic is received. Also defines the default unicast port for receiving user-traffic for DataReaders and DataWriters (can be overridden by the rti::core::policy::TransportUnicast or rti::core::policy::TransportUnicast).

For more information on port mapping, please refer to rti::core::RtpsWellKnownPorts.

Each dds::domain::DomainParticipant in the same domain and running on the same host, must have a unique participant_id. The participants may be in the same address space or in distinct address spaces.

A negative number (-1) means that RTI Connext will automatically resolve the participant ID as follows.

  • RTI Connext will pick the smallest participant ID based on the unicast ports available on the transports enabled for discovery.
  • RTI Connext will attempt to resolve an automatic port index either when a DomainPartcipant is enabled, or when a DataReader or DataWriter is created. Therefore, all the transports enabled for discovery must have been registered by this time. Otherwise, the discovery transports registered after resolving the automatic port index may produce port conflicts when the DomainPartcipant is enabled.

[default] -1 [automatic], i.e. RTI Connext will automatically pick the participant_id, as described above.

[range] [>= 0], or -1, and does not violate guidelines stated in rti::core::RtpsWellKnownPorts.

See also
dds::core::Entity::enable()

◆ participant_id() [2/2]

int32_t rti::core::policy::WireProtocol::participant_id ( ) const

Getter (see the setter with the same name)

◆ rtps_host_id() [1/2]

WireProtocol& rti::core::policy::WireProtocol::rtps_host_id ( uint32_t  the_rtps_host_id)

The RTPS Host ID of the domain participant.

A specific host ID that is unique in the domain.

[default] rti::core::policy::WireProtocol::RTPS_AUTO_ID. The default value is interpreted as follows:
If rti::core::policy::WireProtocol::rtps_auto_id_kind is equal to rti::core::policy::WireProtocolAutoKind_def::RTPS_AUTO_ID_FROM_IP, the value will be interpreted as the IPv4 address of the first up and running interface of the host machine.
If rti::core::policy::WireProtocol::rtps_auto_id_kind is equal to rti::core::policy::WireProtocolAutoKind_def::RTPS_AUTO_ID_FROM_MAC, the value will be interpreted as the first 32 bits of the MAC address assigned to the first up and running interface of the host machine.
If rti::core::policy::WireProtocol::rtps_auto_id_kind is equal to rti::core::policy::WireProtocolAutoKind_def::RTPS_AUTO_ID_FROM_UUID, the value will be the first 32 bits of the GUID prefix assigned by the UUID algorithm.

[range] [0,0xffffffff]

◆ rtps_host_id() [2/2]

uint32_t rti::core::policy::WireProtocol::rtps_host_id ( ) const

Getter (see the setter with the same name)

◆ rtps_app_id() [1/2]

WireProtocol& rti::core::policy::WireProtocol::rtps_app_id ( uint32_t  the_rtps_app_id)

The RTPS App ID of the domain participant.

A participant specific ID that, together with the rtps_instance_id, is unique within the scope of the rtps_host_id.

If a participant dies and is restarted, it is recommended that it be given an app ID that is distinct from the previous one so that other participants in the domain can distinguish between them.

[default] rti::core::policy::WireProtocol::RTPS_AUTO_ID. The default value is interpreted as follows:
If rti::core::policy::WireProtocol::rtps_auto_id_kind is equal to rti::core::policy::WireProtocolAutoKind_def::RTPS_AUTO_ID_FROM_IP the value will be the process (or task) ID.
If rti::core::policy::WireProtocol::rtps_auto_id_kind is equal to rti::core::policy::WireProtocolAutoKind_def::RTPS_AUTO_ID_FROM_MAC the value will be the last 32 bits of the MAC address assigned to the first up and running interface of the host machine.
If rti::core::policy::WireProtocol::rtps_auto_id_kind is equal to rti::core::policy::WireProtocolAutoKind_def::RTPS_AUTO_ID_FROM_UUID, the value will be the middle 32 bits of the GUID prefix assigned by the UUID algorithm.

[range] [0,0xffffffff]

◆ rtps_app_id() [2/2]

uint32_t rti::core::policy::WireProtocol::rtps_app_id ( ) const

Getter (see the setter with the same name)

◆ rtps_instance_id() [1/2]

WireProtocol& rti::core::policy::WireProtocol::rtps_instance_id ( uint32_t  the_rtps_instance_id)

The RTPS Instance ID of the dds::domain::DomainParticipant.

This is an instance-specific ID of a participant that, together with the rtps_app_id, is unique within the scope of the rtps_host_id.

If a participant dies and is restarted, it is recommended that it be given an instance ID that is distinct from the previous one so that other participants in the domain can distinguish between them.

[default] rti::core::policy::WireProtocol::RTPS_AUTO_ID. The default value is interpreted as follows:
If rti::core::policy::WireProtocol::rtps_auto_id_kind is equal to rti::core::policy::WireProtocolAutoKind_def::RTPS_AUTO_ID_FROM_IP, a counter is assigned that is incremented per new participant. For VxWorks-653, the first 8 bits are assigned to the partition id for the application.
If rti::core::policy::WireProtocol::rtps_auto_id_kind is equal to rti::core::policy::WireProtocolAutoKind_def::RTPS_AUTO_ID_FROM_MAC, the first 24 bits are assigned to the application/task identifier and the last 8 bits are assigned to a counter that is incremented per new paricipant.
If rti::core::policy::WireProtocol::rtps_auto_id_kind is equal to rti::core::policy::WireProtocolAutoKind_def::RTPS_AUTO_ID_FROM_UUID, the value will be the last 32 bits of the GUID prefix assigned by the UUID algorithm.

[range] [0,0xffffffff] NOTE: If you use rti::core::policy::WireProtocolAutoKind_def::RTPS_AUTO_ID_FROM_MAC as rtps_auto_id_kind and you decide to manually handle the rtps_instance_id field, you must ensure that both the two parts are non-zero, otherwise the middleware will take responsibility for them. We recommend that you always specify the two parts separately in order to avoid errors. (examples)

◆ rtps_instance_id() [2/2]

uint32_t rti::core::policy::WireProtocol::rtps_instance_id ( ) const

Getter (see the setter with the same name)

◆ rtps_well_known_ports() [1/2]

WireProtocol& rti::core::policy::WireProtocol::rtps_well_known_ports ( const rti::core::RtpsWellKnownPorts the_rtps_well_known_ports)

Configures the RTPS well-known port mappings.

Determines the well-known multicast and unicast port mappings for discovery (meta) traffic and user traffic.

[default] rti::core::RtpsWellKnownPorts::Interoperable()

◆ rtps_well_known_ports() [2/2]

rti::core::RtpsWellKnownPorts rti::core::policy::WireProtocol::rtps_well_known_ports ( ) const

Getter (see the setter with the same name)

◆ rtps_reserved_port_mask() [1/2]

WireProtocol& rti::core::policy::WireProtocol::rtps_reserved_port_mask ( const RtpsReservedPortKindMask the_rtps_reserved_port_mask)

Specifies which well-known ports to reserve when enabling the participant.

Specifies which of the well-known multicast and unicast ports will be reserved when the DomainParticipant is enabled. Failure to allocate a port that is computed based on the rti::core::RtpsWellKnownPorts will be detected at this time, and the enable operation will fail.

[default] RTPS_RESERVED_PORT_MASK_DEFAULT

◆ rtps_reserved_port_mask() [2/2]

RtpsReservedPortKindMask rti::core::policy::WireProtocol::rtps_reserved_port_mask ( ) const

Getter (see the setter with the same name)

◆ rtps_auto_id_kind() [1/2]

WireProtocol& rti::core::policy::WireProtocol::rtps_auto_id_kind ( rti::core::policy::WireProtocolAutoKind  the_kind)

Kind of auto mechanism used to calculate the GUID prefix.

[default] rti::core::policy::WireProtocolAutoKind_def::RTPS_AUTO_ID_FROM_UUID

◆ rtps_auto_id_kind() [2/2]

rti::core::policy::WireProtocolAutoKind rti::core::policy::WireProtocol::rtps_auto_id_kind ( ) const

Getter (see the setter with the same name)

◆ compute_crc() [1/2]

WireProtocol& rti::core::policy::WireProtocol::compute_crc ( bool  crc_needed)

Adds RTPS CRC submessage to every message when this field is set to true.

The computed CRC covers the entire RTPS message excluding the RTPS header.

[default] false

◆ compute_crc() [2/2]

bool rti::core::policy::WireProtocol::compute_crc ( ) const

Getter (see the setter with the same name)

◆ check_crc() [1/2]

WireProtocol& rti::core::policy::WireProtocol::check_crc ( bool  crc_checked)

Checks if the received RTPS message is valid by comparing the computed CRC with the received RTPS CRC submessage when this field is set to true.

rti::core::policy::WireProtocol::compute_crc must be enabled at the publishing application for validating the message at the subscribing application.

[default] false

◆ check_crc() [2/2]

bool rti::core::policy::WireProtocol::check_crc ( ) const

Getter (see the setter with the same name)

Member Data Documentation

◆ RTPS_AUTO_ID

OMG_DDS_API_CLASS_VARIABLE const uint32_t rti::core::policy::WireProtocol::RTPS_AUTO_ID
static