RTI Connext Java API
Version 5.3.1
|
Specifies the wire-protocol-related attributes for the com.rti.dds.domain.DomainParticipant. More...
Public Attributes | |
int | participant_id |
A value used to distinguish among different participants belonging to the same domain on the same host. | |
RtpsWellKnownPorts_t | rtps_well_known_ports |
Configures the RTPS well-known port mappings. | |
int | rtps_host_id |
The RTPS Host ID of the domain participant. | |
int | rtps_app_id |
The RTPS App ID of the domain participant. | |
int | rtps_instance_id |
The RTPS Instance ID of the com.rti.dds.domain.DomainParticipant. | |
int | rtps_reserved_port_mask |
Specifies which well-known ports to reserve when enabling the participant. | |
WireProtocolQosPolicyAutoKind | rtps_auto_id_kind = WireProtocolQosPolicyAutoKind.RTPS_AUTO_ID_FROM_IP |
Kind of auto mechanism used to calculate the GUID prefix. | |
boolean | compute_crc |
Adds RTPS CRC submessage to every message when this field is set to com.rti.dds.infrastructure.true. | |
boolean | check_crc |
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 com.rti.dds.infrastructure.true. | |
Public Attributes inherited from QosPolicy | |
final QosPolicyId_t | id |
The ID of this QoS policy. | |
final String | policy_name |
The name of this QoS policy. | |
Static Public Attributes | |
static final int | RTPS_AUTO_ID = 0 |
Indicates that RTI Connext should choose an appropriate host, app, instance or object ID automatically. | |
Additional Inherited Members | |
Public Member Functions inherited from Struct | |
abstract boolean | equals (Object obj) |
abstract int | hashCode () |
String | toString () |
Protected Member Functions inherited from Struct | |
Struct () | |
abstract void | pull_from_nativeI (long native_status) |
abstract void | push_to_nativeI (long native_status) |
Specifies the wire-protocol-related attributes for the com.rti.dds.domain.DomainParticipant.
This QoS policy configures some participant-wide properties of the DDS Real-Time Publish Subscribe (RTPS) on-the-wire protocol. (com.rti.dds.infrastructure.DataWriterProtocolQosPolicy and com.rti.dds.infrastructure.DataReaderProtocolQosPolicy configure RTPS and reliability properties on a per com.rti.dds.publication.DataWriter or com.rti.dds.subscription.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 com.rti.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 com.rti.dds.domain.DomainParticipant must have a unique value for this prefix relative to all other participants in its domain. To make it easier to control how this 96-bit value is generated, RTI Connext divides it into three integers: a host ID, the value of which is based on the identity of the identity of the machine on which the participant is executing; an application ID, the value of which is based on the process or task in which the particpant is contained; and an instance ID, which identifies the participant itself.
This QoS policy provides you with a choice of algorithms for generating these values automatically. In case none of these algorithms suit your needs, you may also choose to specify some or all of them yourself.
The following three fields:
comprise the GUID prefix and by default are set to com.rti.dds.infrastructure.WireProtocolQosPolicy.RTPS_AUTO_ID. The meaning of this flag depends on the value assigned to the com.rti.dds.infrastructure.WireProtocolQosPolicy.rtps_auto_id_kind field.
Depending on the com.rti.dds.infrastructure.WireProtocolQosPolicy.rtps_auto_id_kind value, there are two different scenarios:
In the default and most common scenario, com.rti.dds.infrastructure.WireProtocolQosPolicy.rtps_auto_id_kind is set to com.rti.dds.infrastructure.WireProtocolQosPolicyAutoKind.RTPS_AUTO_ID_FROM_IP. Doing so, each field is interpreted as follows:
NOTE: If the IP assigned to the interface is not unique within the network (for instance, if it is not configured), it is possible that the GUID (specifically, the rtps_host_id portion) may also not be unique.
In this situation, RTI Connext provides a different value for rtps_auto_id_kind: com.rti.dds.infrastructure.WireProtocolQosPolicyAutoKind.RTPS_AUTO_ID_FROM_MAC. As the name suggests, this alternative mechanism uses the MAC address instead of the IPv4 address. Since the MAC address size is up to 64 bits, the logical mapping of the host information, the application ID, and the instance identifiers has to change.
Note to Solaris Users: To use com.rti.dds.infrastructure.WireProtocolQosPolicyAutoKind.RTPS_AUTO_ID_FROM_MAC, you must run the RTI Connext application while logged in as root.
Using com.rti.dds.infrastructure.WireProtocolQosPolicyAutoKind.RTPS_AUTO_ID_FROM_MAC, the default value of each field is interpreted as follows:
If com.rti.dds.infrastructure.WireProtocolQosPolicyAutoKind.RTPS_AUTO_ID_FROM_MAC is used, the rtps_instance_id has been logically split into two parts: 24 bits for the process/task ID and 8 bits for the per new participant counter. To give to users the ability to manually set the two parts independently, a bit-field mechanism has been introduced for the rtps_instance_id field when it is used in combination with com.rti.dds.infrastructure.WireProtocolQosPolicyAutoKind.RTPS_AUTO_ID_FROM_MAC. If one of the two parts is set to 0, only this part will be handled by RTI Connext and you will be able to handle the other one manually.
Some examples are provided to clarify the behavior of this QoSPolicy in case you want to change the default behavior with com.rti.dds.infrastructure.WireProtocolQosPolicyAutoKind.RTPS_AUTO_ID_FROM_MAC.
First, get the participant QoS from the DomainParticipantFactory:
Second, change the com.rti.dds.infrastructure.WireProtocolQosPolicy using one of the options shown below.
Third, create the com.rti.dds.domain.DomainParticipant as usual, using the modified QoS structure instead of the default one.
Option 1: Use com.rti.dds.infrastructure.WireProtocolQosPolicyAutoKind.RTPS_AUTO_ID_FROM_MAC to explicitly set just the application/task identifier portion of the rtps_instance_id field.
Option 2: Handle only the per participant counter and let RTI Connext handle the application/task identifier:
Option 3: Handle the entire rtps_instance_id field yourself:
NOTE: If you are using com.rti.dds.infrastructure.WireProtocolQosPolicyAutoKind.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:
NOTE: If you are using com.rti.dds.infrastructure.WireProtocolQosPolicyAutoKind.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.
|
static |
Indicates that RTI Connext should choose an appropriate host, app, instance or object ID automatically.
If this special value is assigned to com.rti.dds.infrastructure.WireProtocolQosPolicy.rtps_host_id, com.rti.dds.infrastructure.WireProtocolQosPolicy.rtps_app_id, com.rti.dds.infrastructure.WireProtocolQosPolicy.rtps_instance_id, com.rti.dds.infrastructure.DataWriterProtocolQosPolicy.rtps_object_id or com.rti.dds.infrastructure.DataReaderProtocolQosPolicy.rtps_object_id RTI Connext will assign the ID automatically.
The actual ID value is chosen when the QoS is set: the QoS returned from com.rti.dds.domain.DomainParticipant.get_qos, com.rti.dds.publication.DataWriter.get_qos or com.rti.dds.subscription.DataReader.get_qos will never have this value.
int 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 com.rti.dds.subscription.DataReaderQos.unicast or com.rti.dds.publication.DataWriterQos.unicast).
For more information on port mapping, please refer to com.rti.dds.infrastructure.RtpsWellKnownPorts_t.
Each com.rti.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.
[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 com.rti.dds.infrastructure.RtpsWellKnownPorts_t.
RtpsWellKnownPorts_t 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] com.rti.dds.infrastructure.RtpsWellKnownPorts_t.INTEROPERABLE_RTPS_WELL_KNOWN_PORTS
int rtps_host_id |
The RTPS Host ID of the domain participant.
A machine/operating system specific host ID that is unique in the domain.
[default] com.rti.dds.infrastructure.WireProtocolQosPolicy.RTPS_AUTO_ID. The default value is interpreted as follows:
If com.rti.dds.infrastructure.WireProtocolQosPolicy.rtps_auto_id_kind is equal to com.rti.dds.infrastructure.WireProtocolQosPolicyAutoKind.RTPS_AUTO_ID_FROM_IP (the default value), the value will be interpreted as the IPv4 address of the first up and running interface of the host machine.
If com.rti.dds.infrastructure.WireProtocolQosPolicy.rtps_auto_id_kind is equal to com.rti.dds.infrastructure.WireProtocolQosPolicyAutoKind.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.
[range] [0,0xffffffff]
int 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] com.rti.dds.infrastructure.WireProtocolQosPolicy.RTPS_AUTO_ID. The default value is interpreted as follows:
If com.rti.dds.infrastructure.WireProtocolQosPolicy.rtps_auto_id_kind is equal to com.rti.dds.infrastructure.WireProtocolQosPolicyAutoKind.RTPS_AUTO_ID_FROM_IP (default value for this field) the value will be the process (or task) ID.
If com.rti.dds.infrastructure.WireProtocolQosPolicy.rtps_auto_id_kind is equal to com.rti.dds.infrastructure.WireProtocolQosPolicyAutoKind.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. [range] [0,0xffffffff]
int rtps_instance_id |
The RTPS Instance ID of the com.rti.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] com.rti.dds.infrastructure.WireProtocolQosPolicy.RTPS_AUTO_ID. The default value is interpreted as follows:
If com.rti.dds.infrastructure.WireProtocolQosPolicy.rtps_auto_id_kind is equal to com.rti.dds.infrastructure.WireProtocolQosPolicyAutoKind.RTPS_AUTO_ID_FROM_IP (the default value), 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 com.rti.dds.infrastructure.WireProtocolQosPolicy.rtps_auto_id_kind is equal to com.rti.dds.infrastructure.WireProtocolQosPolicyAutoKind.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.
[range] [0,0xffffffff] NOTE: If you use com.rti.dds.infrastructure.WireProtocolQosPolicyAutoKind.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)
int 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 com.rti.dds.infrastructure.RtpsWellKnownPorts_t will be detected at this time, and the enable operation will fail.
[default] com.rti.dds.infrastructure.RtpsReservedPortKind.MASK_DEFAULT
WireProtocolQosPolicyAutoKind rtps_auto_id_kind = WireProtocolQosPolicyAutoKind.RTPS_AUTO_ID_FROM_IP |
Kind of auto mechanism used to calculate the GUID prefix.
[default] com.rti.dds.infrastructure.WireProtocolQosPolicyAutoKind.RTPS_AUTO_ID_FROM_IP
boolean compute_crc |
Adds RTPS CRC submessage to every message when this field is set to com.rti.dds.infrastructure.true.
The computed CRC covers the entire RTPS message excluding the RTPS header.
[default] com.rti.dds.infrastructure.false
boolean check_crc |
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 com.rti.dds.infrastructure.true.
com.rti.dds.infrastructure.WireProtocolQosPolicy.compute_crc must be enabled at the publishing application for validating the message at the subscribing application.
[default] com.rti.dds.infrastructure.false