Built-in DataReaders

28.2 Built-in DataReaders

Built-in DataReaders belong to a built-in Subscriber, which can be retrieved by using the DomainParticipant’s get_builtin_subscriber() operation. You can retrieve the built-in DataReaders by using the Subscriber’s lookup_datareader() operation, which takes the Topic name as a parameter. The built-in DataReader is created when lookup_datareader() is called on a built-in topic for the first time.

To conserve memory, built-in Subscribers and DataReaders are created only if and when you look them up. Therefore, if you do not want to miss any built-in data, you should look up the built-in readers before the DomainParticipant is enabled.

The following tables describe the built-in topics and their data types. The 47.30 USER_DATA QosPolicy, 45.1 TOPIC_DATA QosPolicy and 46.3 GROUP_DATA QosPolicy are included as part of the built-in data type and are not used by Connext. Therefore, you can use them to send application-specific information.

Built-in topics can be used in conjunction with the ignore_*() operations to ignore certain entities (see Chapter 27 Restricting Communication—Ignoring Entities).

Table 28.1 Participant Built-in Topic’s Data Type (DDS_ParticipantBuiltinTopicData)
Type	Field	Description
DDS_BuiltinTopicKey	key	Key to distinguish the discovered DomainParticipant
DDS_UserDataQosPolicy	user_data	Data that can be set when the related DomainParticipant is created (via the 47.30 USER_DATA QosPolicy) and that the application may use as it wishes (e.g., to perform some security checking).
DDS_PropertyQosPolicy	property	Pairs of names/values to be stored with the DomainParticipant. See 47.19 PROPERTY QosPolicy (DDS Extension) . The usage is strictly application-dependent.
DDS_ProtocolVersion_t	rtps_protocol_ version	Version number of the RTPS wire protocol used.
DDS_VendorId_t	rtps_vendor_id	ID of vendor implementing the RTPS wire protocol.
DDS_UnsignedLong	dds_builtin_ endpoints	Bitmap set by the discovery plugins. Each bit in this field indicates a built-in endpoint present for discovery.
DDS_LocatorSeq	default_unicast_ locators	If the TransportUnicastQosPolicy is not specified when a DataWriter/DataReader is created, the unicast_locators in the corresponding Publication/Subscription built-in topic data will be empty. When the unicast_locators in the Publication/SubscriptionBuiltinTopicData is empty, the default_unicast_locators in the corresponding Participant Builtin Topic Data is assumed. If default_unicast_locators is empty, it defaults to DomainParticipantQos.default_unicast.
DDS_ProductVersion_t	product_ version	Vendor-specific parameter. The current version of Connext.
DDS_EntityNameQosPolicy	participant_ name	Name and role_name assigned to the DomainParticipant. See 47.11 ENTITY_NAME QosPolicy (DDS Extension).
DDS_DomainId_t	domain_id	Domain ID associated with the discovered participant.
DDS_TransportInfoSeq	transport_ info	A sequence of DDS_TransportInfo_t containing information about each of the installed transports of the discovered DomainParticipant. A DDS_TransportInfo_t structure contains the class_id and message_size_max for a single transport. The maximum length of this sequence is controlled by the 44.4 DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) transport_info_list_max_length (see Table 44.5 DDS_DomainParticipantResourceLimitsQosPolicy ). Connext uses the transport information propagated via discovery to detect potential misconfigurations in a Connext distributed system. If two DomainParticipants that discover each other have one common transport with different values for message_size_max, Connext prints a warning message about that condition.
struct DDS_Duration_t	reachability_lease_duration	Value of the participant properties dds.domain_participant.locator_reachability_lease_duration.sec and dds.domain_participant.locator_reachability_lease_duration.nanosec used to configured the locator reachability lease duration.
struct DDS_PartitionQosPolicy	partition	Partition of the remote participant.See 44.6 PARTITION QosPolicy.
DDS_ServiceQosPolicy	service	Service associated with the discovered DomainParticipant.
DDS_ParticipantTrustInfo	trust_protection_info	Trust Plugins information associated with the discovered DomainParticipant. Trust Plugins is a generic abstraction that represents any plugin intended to do transformation, interception, and validation of exchanged DomainParticipant data and metadata. trust_protection_info contains information about how RTPS wire serialization, discovery, and liveliness interact with the loaded Trust Plugins. The meaning of the contents of this field may vary depending on what Trust Plugins the DomainParticipant is using. For information about how this field interacts with the RTI Security Plugins, see the RTI Security Plugins User's Manual.
DDS_ParticipantTrustAlgorithms	trust_algorithm_info	Trust Plugins algorithms associated with the discovered DomainParticipant. Trust Plugins is a generic abstraction that represents any plugin intended to do transformation, interception, and validation of exchanged DomainParticipant data and metadata. trust_algorithm_info contains information about what algorithms the loaded Trust Plugins are running. The meaning of the contents of this field may vary depending on what Trust Plugins the DomainParticipant is using. For information about how this field interacts with the RTI Security Plugins, see the RTI Security Plugins User's Manual.
DDS_Boolean	partial_configuration	Only populated by DomainParticipants using SPDP2. This flag indicates whether a DDS_ParticipantBuiltinTopicData contains only bootstrapping information or contains the full participant configuration. If this field is set to TRUE, the DDS_ParticipantBuiltinTopicData only contains bootstrapping information. The following fields are valid if this field is TRUE: key property (only dds.domain_participant.domain_tag is valid if set) rtps_protocol_version rtps_vendor_id product_version domain_id transport_info partition trust_protection_info trust_algorithm_info All other fields should not be used if this field as TRUE, since they have not been populated.

Table 28.2 Publication Built-in Topic’s Data Type (DDS_PublicationBuiltinTopicData)
Type	Field	Description
DDS_BuiltinTopicKey_t	key	Key to distinguish the discovered DataWriter
DDS_BuiltinTopicKey_t	participant_key	Key to distinguish the participant to which the discovered DataWriter belongs
DDS_String	topic_name	Topic name of the discovered DataWriter
DDS_String	type_name	Type name attached to the topic of the discovered DataWriter
DDS_DurabilityQosPolicy	durability	QosPolicies of the discovered DataWriter
DDS_DurabilityService-QosPolicy	durability_ service
DDS_DeadlineQosPolicy	deadline
DDS_DestinationOrder-QosPolicy	destination_ order
DDS_LatencyBudget-QosPolicy	latency_ budget
DDS_LivelinessQosPolicy	liveliness
DDS_ReliabilityQosPolicy	reliability
DDS_LifespanQosPolicy	lifespan
DDS_UserDataQosPolicy	user_data	Data that can be set when the DataWriter is created (via the 47.30 USER_DATA QosPolicy) and that the application may use as it wishes.
DDS_OwnershipQosPolicy	ownership	QosPolicies of the discovered DataWriter
DDS_OwnershipStrength-QosPolicy	ownership_ strength
DDS_DestinationOrder-QosPolicy	destination_ order
DDS_PresentationQosPolicy	presentation
DDS_PartitionQosPolicy	partition	Name of the partition, set in the 44.6 PARTITION QosPolicy for the publisher to which the discovered DataWriter belongs
DDS_TopicDataQosPolicy	topic_data	Data that can be set when the Topic (with which the discovered DataWriter is associated) is created (via the 45.1 TOPIC_DATA QosPolicy) and that the application may use as it wishes.
DDS_GroupDataQosPolicy	group_data	Data that can be set when the Publisher to which the discovered DataWriter belongs is created (via the 46.3 GROUP_DATA QosPolicy) and that the application may use as it wishes.
DDS_TypeObject *	type	Describes the type of the remote DataReader. See the API Reference HTML documentation.
DDS_DataRepresentationQosPolicy	representation	Data representations that the DataWriter offers. See 47.3 DATA_REPRESENTATION QosPolicy.
DDS_DataTagQosPolicy	data_tags	Data tags (pairs of names/values) assigned to the corresponding DataWriter. Usage is strictly application-dependent. See 47.4 DATATAG QosPolicy.
DDS_TypeCode *	type_code	Type code information about this Topic. See 17.7 Using Generated Types without Connext (Standalone) .
DDS_BuiltinTopicKey_t	publisher_key	The key of the Publisher to which the DataWriter belongs.
DDS_PropertyQosPolicy	property	Properties (pairs of names/values) assigned to the corresponding DataWriter. Usage is strictly application-dependent. See 47.19 PROPERTY QosPolicy (DDS Extension) .
DDS_LocatorSeq	unicast_ locators	If the TransportUnicastQosPolicy is not specified when a DataWriter/DataReader is created, the unicast_locators in the corresponding Publication/Subscription built-in topic data will be empty. When the unicast_locators in the Publication/SubscriptionBuiltinTopicData is empty, the default_unicast_locators in the corresponding Participant Builtin Topic Data is assumed.
DDS_GUID_t	virtual_guid	Virtual GUID for the corresponding DataWriter. For more information, see 21.2 Durability and Persistence Based on Virtual GUIDs.
DDS_ServiceQosPolicy	service	Service associated with the discovered DataWriter.
DDS_ProtocolVersion_t	rtps_protocol_ version	Version number of the RTPS wire protocol in use.
DDS_VendorId_t	rtps_vendor_id	ID of the vendor implementing the RTPS wire protocol.
DDS_Product_Version_t	product_version	Vendor-specific value. For RTI, this is the current version of Connext.
DDS_LocatorFilterQosPolicy	locator_filter	When the 47.16 MULTI_CHANNEL QosPolicy (DDS Extension) is used on the discovered DataWriter, the locator_filter contains the sequence of LocatorFilters in that policy. There is one LocatorFilter per DataWriter channel. A channel is defined by a filter expression and a sequence of multicast locators. See 28.2.1 LOCATOR_FILTER QoS Policy (DDS Extension).
DDS_Boolean	disable_positive_ acks	Vendor specific parameter. Determines whether matching DataReaders send positive acknowledgements for reliability.
DDS_EntityNameQosPolicy	publication_name	Name and role_name assigned to the DataWriter. See 47.11 ENTITY_NAME QosPolicy (DDS Extension).

Table 28.3 Subscription Built-in Topic’s Data Type (DDS_SubscriptionBuiltinTopicData)
Type	Field	Description
DDS_BuiltinTopicKey_t	key	Key to distinguish the discovered DataReader.
DDS_BuiltinTopicKey_t	participant_ key	Key to distinguish the participant to which the discovered DataReader belongs.
char *	topic_name	Topic name of the discovered DataReader.
char *	type_name	Type name attached to the Topic of the discovered DataReader.
DDS_DurabilityQosPolicy	durability	QosPolicies of the discovered DataReader
DDS_DeadlineQosPolicy	deadline
DDS_LatencyBudget-QosPolicy	latency_budget
DDS_LivelinessQosPolicy	liveliness
DDS_ReliabilityQosPolicy	reliability
DDS_OwnershipQosPolicy	ownership
DDS_ DestinationOrderQosPolicy	destination_ order
DDS_UserDataQosPolicy	user_data	Data that can be set when the DataReader is created (via the 47.30 USER_DATA QosPolicy) and that the application may use as it wishes.
DDS_ TimeBasedFilterQosPolicy	time_based_ filter	QosPolicies of the discovered DataReader
DDS_PresentationQosPolicy	presentation	QosPolicies of the discovered DataReader
DDS_PartitionQosPolicy	partition	Name of the partition, set in the 44.6 PARTITION QosPolicy for the Subscriber to which the discovered DataReader belongs.
DDS_TopicDataQosPolicy	topic_data	Data that can be set when the Topic to which the discovered DataReader belongs is created (via the 45.1 TOPIC_DATA QosPolicy) and that the application may use as it wishes.
DDS_GroupDataQosPolicy	group_data	Data that can be set when the Publisher to which the discovered DataReader belongs is created (via the 46.3 GROUP_DATA QosPolicy) and that the application may use as it wishes.
DDS_TypeObject *	type	Describes the type of the remote DataReader. See the API Reference HTML documentation.
DDS_TypeConsistencyEnforcementQosPolicy	type_ consistency	Indicates the type-consistency requirements of the remote DataReader. See 48.6 TYPE_CONSISTENCY_ENFORCEMENT QosPolicy and the RTI Connext Core Libraries Extensible Types Guide.
DDS_DataRepresentationQosPolicy	representation	Data representations that the DataReader requests. See47.3 DATA_REPRESENTATION QosPolicy.
DDS_DataTagQosPolicy	data_tags	Data tags (pairs of names/values) assigned to the corresponding DataReader. Usage is strictly application-dependent. See 47.4 DATATAG QosPolicy.
DDS_TypeCode *	type_code	Type code information about this Topic. See 17.7 Using Generated Types without Connext (Standalone) .
DDS_BuiltinTopicKey_t	subscriber_ key	Key of the Subscriber to which the DataReader belongs.
DDS_PropertyQosPolicy	property	Properties (pairs of names/values) assigned to the corresponding DataReader. Usage is strictly application-dependent. See 47.19 PROPERTY QosPolicy (DDS Extension) .
DDS_LocatorSeq	unicast_ locators	If the TransportUnicastQosPolicy is not specified when a DataWriter/DataReader is created, the unicast_locators in the corresponding Publication/Subscription builtin topic data will be empty. When the unicast_locators in the Publication/SubscriptionBuiltinTopicData is empty, the default_unicast_locators in the corresponding Participant Builtin Topic Data is assumed.
DDS_LocatorSeq	multicast_ locators	Custom multicast locators that the endpoint can specify.
DDS_ContentFilter-Property_t	content_filter_ property	Provides all the required information to enable content filtering on the writer side.
DDS_GUID_t	virtual_guid	Virtual GUID for the corresponding DataReader. For more information, see 21.2 Durability and Persistence Based on Virtual GUIDs.
DDS_ServiceQosPolicy	service	Service associated with the discovered DataReader.
DDS_ProtocolVersion_t	rtps_protocol_ version	Version number of the RTPS wire protocol in use.
DDS_VendorId_t	rtps_vendor_ id	ID of the vendor implementing the RTPS wire protocol.
DDS_Product_Version_t	product_ version	Vendor-specific value. For RTI, this is the current version of Connext.
DDS_Boolean	disable_positive_ acks	Vendor specific parameter. Determines whether matching DataReaders send positive acknowledgements for reliability.
DDS_EntityNameQosPolicy	subscription_ name	Name and role_name assigned to the DataReader. See 47.11 ENTITY_NAME QosPolicy (DDS Extension).

Table 28.4 Topic Built-in Topic’s Data Type (DDS_TopicBuiltinTopicData)
Type	Field	Description
DDS_BuiltinTopicKey_t	key	Key to distinguish the discovered Topic
DDS_String	name	Topic name
DDS_String	type_name	type name attached to the Topic
DDS_DurabilityQosPolicy	durability	QosPolicy of the discovered Topic
DDS_DurabilityServiceQosPolicy	durability_service
DDS_DeadlineQosPolicy	deadline
DDS_LatencyBudgetQosPolicy	latency_budget
DDS_LivelinessQosPolicy	liveliness
DDS_ReliabilityQosPolicy	reliability
DDS_TransportPriorityQosPolicy	transport_priority
DDS_LifespanQosPolicy	lifespan
DDS_DestinationOrderQosPolicy	destination_ order
DDS_HistoryQosPolicy	history
DDS_ResourceLimitsQosPolicy	resource_limits
DDS_OwnershipQosPolicy	ownership
DDS_TopicDataQosPolicy	topic_data	Data that can be set when the Topic to which the discovered DataReader belongs is created (via the 45.1 TOPIC_DATA QosPolicy) and that the application may use as it wishes.

Table 28.5 QoS of Built-in Subscriber and DataReader lists the QoS of the built-in Subscriber and DataReader created for accessing discovery data. These are provided for your reference only; they cannot be changed.

Table 28.5 QoS of Built-in Subscriber and DataReader
QosPolicy	Value
Deadline	period = infinite
DestinationOrder	kind = BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS
Durability	kind = TRANSIENT_LOCAL_DURABILITY_QOS
EntityFactory	autoenable_created_entities = TRUE
GroupData	value = empty sequence
History	kind = KEEP_LAST_HISTORY_QOS depth = 1
LatencyBudget	duration = 0
Liveliness	kind = AUTOMATIC_LIVELINESS_QOS lease_duration = infinite
Ownership	kind = SHARED_OWNERSHIP_QOS
Ownership Strength	value = 0
Presentation	access_scope = TOPIC_PRESENTATION_QOS coherent_access = FALSE ordered_access = FALSE
Partition	name = empty sequence
ReaderDataLifecycle	autopurge_nowriter_samples_delay = infinite
Reliability	kind = RELIABLE_RELIABILITY_QOS max_blocking_time is irrelevant for the DataReader
ResourceLimits	Depends on setting of DomainParticipantResourceLimitsQosPolicy and DiscoveryConfigQosPolicy in DomainParticipantQos: max_samples = domainParticipantQos.discovery_config. [participant/publication/subscription]_reader_resource_limits.max_samples max_instances = domainParticipantQos.resource_limits. [remote_writer/reader/participant]_allocation.max_count max_samples_per_instance = 1
TimeBasedFilter	minimum_separation = 0
TopicData	value = empty sequence
UserData	value = empty sequence

Note:

The DDS_TopicBuiltinTopicData built-in topic (described in Table 28.4 Topic Built-in Topic’s Data Type (DDS_TopicBuiltinTopicData) ) is meant to convey information about discovered Topics. However, this topic's data is not sent separately and therefore a DataReader for DDS_TopicBuiltinTopicData will not receive any data. Instead, DDS_TopicBuiltinTopicData data is included in the information carried by the built-in topics for Publications and Subscriptions (DDS_PublicationBuiltinTopicData and DDS_SubscriptionBuiltinTopicData) and can be accessed with their built-in DataReaders.