Public Attributes | |
| DDS_Long | participant_id |
| A value used to distinguish between different participants belonging to the same domain on the same host. | |
| DDS_UnsignedLong | rtps_host_id |
| The RTPS Host ID of the domain participant. | |
| DDS_UnsignedLong | rtps_app_id |
| The RTPS App ID of the domain participant. | |
| DDS_UnsignedLong | rtps_instance_id |
| The RTPS Instance ID of the domain participant. | |
| struct DDS_RtpsWellKnownPorts_t | rtps_well_known_ports |
| Configures the RTPS well-known port mappings. | |
| DDS_RtpsReservedPortKindMask | rtps_reserved_port_mask |
| Specifies which well-known ports to reserve when enabling the participant. | |
| DDS_WireProtocolQosPolicyAutoKind | rtps_auto_id_kind |
| Kind of auto mechanism used to calculate the GUID prefix. | |
NOTE: The default Qos policies returned by RTI Data Distribution Service contain the correctly initialized wire protocol attributes. The defaults are not expected to be modified normally, 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 DDSDomainParticipant 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 DDSDomainParticipant must have a unique value of this prefix relative to all other participants in its domain. In order to make it easier to control how this 96-bit value is generated, RTI Data Distribution Service 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 choiche 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:
NOTE: If the IP assigned to the interface is not unique within the network (for instance, if it is not configured), then is it possible that the GUID (specifically, the rtps_host_id portion) may also not be unique.
Note to Solaris Users: To use DDS_RTPS_AUTO_ID_FROM_MAC, you must run the RTI Data Distribution Service application while logged in as 'root.'
Using DDS_RTPS_AUTO_ID_FROM_MAC, the default value of each field is interpreted as follows:
If DDS_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 indepently, a bit field mechanism has been introduced for the rtps_instance_id field when it is used in combination with DDS_RTPS_AUTO_ID_FROM_MAC. If one of the two parts is set to 0, only this part will be handled by RTI Data Distribution Service and you will be able to handle the other one manually.
DDSDomainParticipantFactory *factory = NULL; factory = DDSTheParticipantFactory->get_instance(); factory->get_default_participant_qos(participant_qos);
Second, change the DDS_WireProtocolQosPolicy using one of the options shown below.
Third, create the DDSDomainParticipant as usual using the modified QoS structure instead of the default one.
Option 1: Use DDS_RTPS_AUTO_ID_FROM_MAC to explicitly set just the application/task identifier portion of the rtps_instance_id field.
participant_qos.wire_protocol.rtps_auto_id_kind = DDS_RTPS_AUTO_ID_FROM_MAC; participant_qos.wire_protocol.rtps_host_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_app_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_instance_id = (/* App ID */ (12 << 8) | /* Instance ID*/ (DDS_RTPS_AUTO_ID));
Option 2: Handle only the per participant counter and let RTI Data Distribution Service handle the application/task identifier:
participant_qos.wire_protocol.rtps_auto_id_kind = DDS_RTPS_AUTO_ID_FROM_MAC; participant_qos.wire_protocol.rtps_host_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_app_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_instance_id = (/* App ID */ (DDS_RTPS_AUTO_ID) | /* Instance ID*/ (12));
Option 3: Handle the entire rtps_instance_id field yourself:
participant_qos.wire_protocol.rtps_auto_id_kind = DDS_RTPS_AUTO_ID_FROM_MAC; participant_qos.wire_protocol.rtps_host_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_app_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_instance_id = ( /* App ID */ (12 << 8)) | /* Instance ID */ (9) )
NOTE: If you are using DDS_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 Data Distribution Service will take responsibility for them). RTI recommends that you always specify the two parts separately in order to avoid errors.
Option 4: Let RTI Data Distribution Service handle the entire rtps_instance_id field:
participant_qos.wire_protocol.rtps_auto_id_kind = DDS_RTPS_AUTO_ID_FROM_MAC; participant_qos.wire_protocol.rtps_host_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_app_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_instance_id = DDS_RTPS_AUTO_ID;
NOTE: If you are using DDS_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 Data Distribution Service will take responsibility for them). RTI recommends that you always specify the two parts separately in order to clearly show the difference.
A value used to distinguish between 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 DDS_DataReaderQos::unicast or by the DDS_DataWriterQos::unicast).
For more information on port mapping, please refer to DDS_RtpsWellKnownPorts_t.
Each DDSDomainParticipant in the same domain, 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 Data Distribution Service will automatically resolve the participant ID as follows.
participant_id, as described above. [range] [>= 0], or -1, and does not violate guidelines stated in DDS_RtpsWellKnownPorts_t.
The RTPS Host ID of the domain participant.
A machine/operating system specific host ID, that is unique in the domain.
[default] DDS_RTPS_AUTO_ID. The default value is interpreted as follows:
If DDS_WireProtocolQosPolicy::rtps_auto_id_kind is equals to RTPS_AUTO_ID_FROM_IP (default value for this field) the value will be interpreted as the IPv4 address of the first up and running interface of the host machine.
If DDS_WireProtocolQosPolicy::rtps_auto_id_kind is equals to RTPS_AUTO_ID_FROM_MAC the value will be interpreted as the first 32 bit of the MAC address assigned to the first up and running interface of the host machine.
[range] [0,0xffffffff]
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] DDS_RTPS_AUTO_ID. The default value is interpreted as follows:
If DDS_WireProtocolQosPolicy::rtps_auto_id_kind is equals to RTPS_AUTO_ID_FROM_IP (default value for this field) the value will be the process (or task) ID.
If DDS_WireProtocolQosPolicy::rtps_auto_id_kind is equals to RTPS_AUTO_ID_FROM_MAC the value will be the last 32 bit of the MAC address assigned to the first up and running interface of the host machine. [range] [0,0xffffffff]
The RTPS Instance ID of the domain participant.
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] DDS_RTPS_AUTO_ID. The default value is interpreted as follows:
If DDS_WireProtocolQosPolicy::rtps_auto_id_kind is equal to RTPS_AUTO_ID_FROM_IP (default value for this field) 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 DDS_WireProtocolQosPolicy::rtps_auto_id_kind is equal to 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 incremented per new paricipant.
[range] [0,0xffffffff] NOTE: if we are using DDS_RTPS_AUTO_ID_FROM_MAC as rtps_auto_id_kind and you decide to manually handle the rtps_instance_id field, you have to ensure that both the two parts are different from zero otherwise the middleware will take responsability for them. We recommend to always specify the two parts separately in order to avoid errors. (examples)
Configures the RTPS well-known port mappings.
Determines the well-known multicast and unicast port mappings for discovery (meta) traffic and user traffic.
[default] DDS_INTEROPERABLE_RTPS_WELL_KNOWN_PORTS
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 domain participant is enabled. Failure to allocate a port that is computed based on the DDS_RtpsWellKnownPorts_t will be detected at this time, and the enable operation will fail.
[default] DDS_RTPS_RESERVED_PORT_MASK_DEFAULT
Kind of auto mechanism used to calculate the GUID prefix.
[default] RTPS_AUTO_ID_FROM_IP
RTI Data Distribution Service C++ API Version 4.5e
Copyright © 23 Oct 2011
Real-Time Innovations, Inc