OpenSplice C# API  v6.x
OpenSplice C# Data Distribution Service Data-Centric Publish-Subscribe API
Built-in Topics

Built-in Topics

As part of its operation, the middleware must discover and possibly keep track of the presence of remote entities such as a new participant in the domain. This information may also be important to the application, which may want to react to this discovery, or else access it on demand.

To make this information accessible to the application, the DCPS specification introduces a set of built-in topics and corresponding DataReader objects that can then be used by the application. The information is then accessed as normal application data. This approach avoids introducing a new API to access this information and allows the application to become aware of any changes in those values by means of any of the mechanisms presented in Listeners and Conditions and Waitsets.

The built-in data-readers all belong to a built-in Subscriber. This subscriber can be retrieved by using the method get_builtin_subscriber provided by the DomainParticipant. The built-in DataReader objects can be retrieved by using the operation lookup_datareader, with the Subscriber and the topic name as parameter.

The QoS of the built-in Subscriber and DataReader objects is given by the following table:

Built-in Subscriber and DataReader QoS
QoS PolicyValue
USER_DATAempty
TOPIC_DATAempty
GROUP_DATAempty
DURABILITYTRANSIENT
DURABILITY_SERVICEservice_cleanup_delay = 0
history_kind = KEEP_LAST
history_depth = 1
max_samples = LENGTH_UNLIMITED
max_instances = LENGTH_UNLIMITED
max_samples_per_instance = LENGTH_UNLIMITED
PRESENTATIONaccess_scope = TOPIC
coherent_access = FALSE
ordered_access = FALSE
DEADLINEPeriod = infinite
LATENCY_BUDGETduration = 0
OWNERSHIPSHARED
LIVELINESSkind = AUTOMATIC
lease_duration = 0
TIME_BASED_FILTERminimum_separation = 0
PARTITION__BUILT-IN PARTITION__
RELIABILITYkind = RELIABLE
max_blocking_time = 100 milliseconds
synchronous = FALSE
DESTINATION_ORDERBY_RECEPTION_TIMESTAMP
HISTORYkind = KEEP_LAST
depth = 1
RESOURCE_LIMITSmax_samples = LENGTH_UNLIMITED
max_instances = LENGTH_UNLIMITED
max_samples_per_instance = LENGTH_UNLIMITED
READER_DATA_LIFECYCLEautopurge_nowriter_samples_delay = infinite
autopurge_disposed_samples_delay = infinite
invalid_sample_visibility = MINIMUM_INVALID_SAMPLES
ENTITY_FACTORYautoenable_created_entities = TRUE
SHARE (proprietary)enable = FALSE
name = NULL
READER_DATA_LIFESPAN (proprietary)used = FALSE
duration = INFINITE
USER_KEY (proprietary)enable = FALSE
expression = NULL

Built-in entities have default listener settings as well. The built-in Subscriber and all of its built-in Topics have nil listeners with all statuses appearing in their listener masks. The built-in DataReaders have nil listeners with no statuses in their masks.

The information that is accessible about the remote entities by means of the built-in topics includes all the QoS policies that apply to the corresponding remote Entity. The QoS policies appear as normal 'data' fields inside the data read by means of the built-in Topic. Additional information is provided to identify the Entity and facilitate the application logic.

The tables below list the built-in topics, their names, and the additional information (beyond the QoS policies that apply to the remote entity) that appears in the data associated with the built-in topic.

ParticipantBuiltinTopicData

The DCPSParticipant topic communicates the existence of DomainParticipants by means of the ParticipantBuiltinTopicData datatype. Each ParticipantBuiltinTopicData sample in a Domain represents a DomainParticipant that participates in that Domain: a new ParticipantBuiltinTopicData instance is created when a newly added DomainParticipant is enabled, and it is disposed when that DomainParticipant is deleted. An updated ParticipantBuiltinTopicData sample is written each time the DomainParticipant modifies its UserDataQosPolicy.

ParticipantBuiltinTopicData Members
NameTypeDescription
keyBuiltinTopicKey_tGlobally unique identifier of the participant
user_dataUserDataQosPolicyUser-defined data attached to the participant via a QosPolicy

TopicBuiltinTopicData

The DCPSTopic topic communicates the existence of topics by means of the TopicBuiltinTopicData datatype. Each TopicBuiltinTopicData sample in a Domain represents a Topic in that Domain: a new TopicBuiltinTopicData instance is created when a newly added Topic is enabled. However, the instance is not disposed when a Topic is deleted by its participant because a topic lifecycle is tied to the lifecycle of a Domain, not to the lifecycle of an individual participant. An updated TopicBuiltinTopicData sample is written each time a Topic modifies one or more of its QosPolicy values.

Information published in the DCPSTopicTopic is critical to the data distribution service, therefore it cannot be disabled by means of the Domain/BuiltinTopics element in the configuration file.

TopicBuiltinTopicData Members
NameTypeDescription
key BuiltinTopicKey_t Global unique identifier of the Topic
name String Name of the Topic
type_name String Type name of the Topic (i.e. the fully scoped IDL name)
durability DurabilityQosPolicy QosPolicy attached to the Topic
durability_serviceDurabilityServiceQosPolicyQosPolicy attached to the Topic
deadline DeadlineQosPolicy QosPolicy attached to the Topic
latency_budget LatencyBudgetQosPolicy QosPolicy attached to the Topic
liveliness LivelinessQosPolicy QosPolicy attached to the Topic
reliability ReliabilityQosPolicy QosPolicy attached to the Topic
transport_priorityTransportPriorityQosPolicyQosPolicy attached to the Topic
lifespan LifespanQosPolicy QosPolicy attached to the Topic
destination_order DestinationOrderQosPolicy QosPolicy attached to the Topic
history HistoryQosPolicy QosPolicy attached to the Topic
resource_limits ResourceLimitsQosPolicy QosPolicy attached to the Topic
ownership OwnershipQosPolicy QosPolicy attached to the Topic
topic_data TopicDataQosPolicy QosPolicy attached to the Topic

PublicationBuiltinTopicData

The DCPSPublication topic communicates the existence of datawriters by means of the PublicationBuiltinTopicData datatype. Each PublicationBuiltinTopicData sample in a Domain represents a datawriter in that Domain: a new PublicationBuiltinTopicData instance is created when a newly added DataWriter is enabled, and it is disposed when that DataWriter is deleted. An updated PublicationBuiltinTopicData sample is written each time the DataWriter (or the Publisher to which it belongs) modifies a QosPolicy that applies to the entities connected to it. Also will it be updated when the writer looses or regains its liveliness.

The PublicationBuiltinTopicData Topic is also used to return data through the get_matched_publication_data operation on the DataReader.

PublicationBuiltinTopicData Members
NameTypeDescription
keyBuiltinTopicKey_tGlobal unique identifier of the DataWriter
participant_keyBuiltinTopicKey_tGlobal unique identifier of the Participant to which the DataWriter belongs
topic_nameStringName of the Topic used by the DataWriter
type_nameStringType name of the Topic used by the DataWriter
durabilityDurabilityQosPolicyQosPolicy attached to the DataWriter
deadlineDeadlineQosPolicyQosPolicy attached to the DataWriter
latency_budgetLatencyBudgetQosPolicyQosPolicy attached to the DataWriter
livelinessLivelinessQosPolicyQosPolicy attached to the DataWriter
reliabilityReliabilityQosPolicyQosPolicy attached to the DataWriter
lifespanLifespanQosPolicyQosPolicy attached to the DataWriter
destination_orderDestinationOrderQosPolicyQosPolicy attached to the DataWriter
user_dataUserDataQosPolicyQosPolicy attached to the DataWriter
ownershipOwnershipQosPolicyQosPolicy attached to the DataWriter
ownership_strengthOwnershipStrengthQosPolicyQosPolicy attached to the DataWriter
presentationPresentationQosPolicyQosPolicy attached to the Publisher to which the DataWriter belongs
partitionPartitionQosPolicyQosPolicy attached to the Publisher to which the DataWriter belongs
topic_dataTopicDataQosPolicyQosPolicy attached to the Topic used by the DataWriter
group_dataGroupDataQosPolicyQosPolicy attached to the Publisher to which the DataWriter belongs

SubscriptionBuiltinTopicData

The DCPSSubscription topic communicates the existence of datareaders by means of the SubscriptionBuiltinTopicData datatype. Each SubscriptionBuiltinTopicData sample in a Domain represents a datareader in that Domain: a new SubscriptionBuiltinTopicData instance is created when a newly added DataReader is enabled, and it is disposed when that DataReader is deleted. An updated SubscriptionBuiltinTopicData sample is written each time the DataReader (or the Subscriber to which it belongs) modifies a QosPolicy that applies to the entities connected to it.

The SubscriptionBuiltinTopicData Topic is also used to return data through the get_matched_subscription_data operation on the DataWriter.

SubscriptionBuiltinTopicData Members
NameTypeDescription
keyBuiltinTopicKey_tGlobal unique identifier of the DataReader
participant_keyBuiltinTopicKey_tGlobal unique identifier of the Participant to which the DataReader belongs
topic_nameStringName of the Topic used by the DataReader
type_nameStringType name of the Topic used by the DataReader
durabilityDurabilityQosPolicyQosPolicy attached to the DataReader
deadlineDeadlineQosPolicyQosPolicy attached to the DataReader
latency_budgetLatencyBudgetQosPolicyQosPolicy attached to the DataReader
livelinessLivelinessQosPolicyQosPolicy attached to the DataReader
reliabilityReliabilityQosPolicyQosPolicy attached to the DataReader
ownershipLifespanQosPolicyQosPolicy attached to the DataReader
destination_orderDestinationOrderQosPolicyQosPolicy attached to the DataReader
user_dataUserDataQosPolicyQosPolicy attached to the DataReader
time_based_filterTimeBasedFilterQosPolicyQosPolicy attached to the DataReader
presentationPresentationQosPolicyQosPolicy attached to the Subscriber to which the DataReader belongs
partitionPartitionQosPolicyQosPolicy attached to the Subscriber to which the DataReader belongs
topic_dataTopicDataQosPolicyQosPolicy attached to the Topic used by theDataReader
group_dataGroupDataQosPolicyQosPolicy attached to the Subscriber to which the DataReader belongs

Other built-in topics

There are a number of other built-in topics that have not been mentioned. These topics (e.g. DCPSDelivery, DCPSHeartbeat and potentially some others) are proprietary and for internal use only. Users are discouraged from doing anything with these topics, so as not to interfere with internal mechanisms that rely on them. The structure of these topics may change without notification.