![]() |
OpenSplice C# API
v6.x
OpenSplice C# Data Distribution Service Data-Centric Publish-Subscribe API
|
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:
QoS Policy | Value |
---|---|
USER_DATA | empty |
TOPIC_DATA | empty |
GROUP_DATA | empty |
DURABILITY | TRANSIENT |
DURABILITY_SERVICE | service_cleanup_delay = 0 history_kind = KEEP_LAST history_depth = 1 max_samples = LENGTH_UNLIMITED max_instances = LENGTH_UNLIMITED max_samples_per_instance = LENGTH_UNLIMITED |
PRESENTATION | access_scope = TOPIC coherent_access = FALSE ordered_access = FALSE |
DEADLINE | Period = infinite |
LATENCY_BUDGET | duration = 0 |
OWNERSHIP | SHARED |
LIVELINESS | kind = AUTOMATIC lease_duration = 0 |
TIME_BASED_FILTER | minimum_separation = 0 |
PARTITION | __BUILT-IN PARTITION__ |
RELIABILITY | kind = RELIABLE max_blocking_time = 100 milliseconds synchronous = FALSE |
DESTINATION_ORDER | BY_RECEPTION_TIMESTAMP |
HISTORY | kind = KEEP_LAST depth = 1 |
RESOURCE_LIMITS | max_samples = LENGTH_UNLIMITED max_instances = LENGTH_UNLIMITED max_samples_per_instance = LENGTH_UNLIMITED |
READER_DATA_LIFECYCLE | autopurge_nowriter_samples_delay = infinite autopurge_disposed_samples_delay = infinite invalid_sample_visibility = MINIMUM_INVALID_SAMPLES |
ENTITY_FACTORY | autoenable_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.
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.
Name | Type | Description |
---|---|---|
key | BuiltinTopicKey_t | Globally unique identifier of the participant |
user_data | UserDataQosPolicy | User-defined data attached to the participant via a QosPolicy |
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.
Name | Type | Description |
---|---|---|
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_service | DurabilityServiceQosPolicy | QosPolicy 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_priority | TransportPriorityQosPolicy | QosPolicy 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 |
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.
Name | Type | Description |
---|---|---|
key | BuiltinTopicKey_t | Global unique identifier of the DataWriter |
participant_key | BuiltinTopicKey_t | Global unique identifier of the Participant to which the DataWriter belongs |
topic_name | String | Name of the Topic used by the DataWriter |
type_name | String | Type name of the Topic used by the DataWriter |
durability | DurabilityQosPolicy | QosPolicy attached to the DataWriter |
deadline | DeadlineQosPolicy | QosPolicy attached to the DataWriter |
latency_budget | LatencyBudgetQosPolicy | QosPolicy attached to the DataWriter |
liveliness | LivelinessQosPolicy | QosPolicy attached to the DataWriter |
reliability | ReliabilityQosPolicy | QosPolicy attached to the DataWriter |
lifespan | LifespanQosPolicy | QosPolicy attached to the DataWriter |
destination_order | DestinationOrderQosPolicy | QosPolicy attached to the DataWriter |
user_data | UserDataQosPolicy | QosPolicy attached to the DataWriter |
ownership | OwnershipQosPolicy | QosPolicy attached to the DataWriter |
ownership_strength | OwnershipStrengthQosPolicy | QosPolicy attached to the DataWriter |
presentation | PresentationQosPolicy | QosPolicy attached to the Publisher to which the DataWriter belongs |
partition | PartitionQosPolicy | QosPolicy attached to the Publisher to which the DataWriter belongs |
topic_data | TopicDataQosPolicy | QosPolicy attached to the Topic used by the DataWriter |
group_data | GroupDataQosPolicy | QosPolicy attached to the Publisher to which the DataWriter belongs |
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.
Name | Type | Description |
---|---|---|
key | BuiltinTopicKey_t | Global unique identifier of the DataReader |
participant_key | BuiltinTopicKey_t | Global unique identifier of the Participant to which the DataReader belongs |
topic_name | String | Name of the Topic used by the DataReader |
type_name | String | Type name of the Topic used by the DataReader |
durability | DurabilityQosPolicy | QosPolicy attached to the DataReader |
deadline | DeadlineQosPolicy | QosPolicy attached to the DataReader |
latency_budget | LatencyBudgetQosPolicy | QosPolicy attached to the DataReader |
liveliness | LivelinessQosPolicy | QosPolicy attached to the DataReader |
reliability | ReliabilityQosPolicy | QosPolicy attached to the DataReader |
ownership | LifespanQosPolicy | QosPolicy attached to the DataReader |
destination_order | DestinationOrderQosPolicy | QosPolicy attached to the DataReader |
user_data | UserDataQosPolicy | QosPolicy attached to the DataReader |
time_based_filter | TimeBasedFilterQosPolicy | QosPolicy attached to the DataReader |
presentation | PresentationQosPolicy | QosPolicy attached to the Subscriber to which the DataReader belongs |
partition | PartitionQosPolicy | QosPolicy attached to the Subscriber to which the DataReader belongs |
topic_data | TopicDataQosPolicy | QosPolicy attached to the Topic used by theDataReader |
group_data | GroupDataQosPolicy | QosPolicy attached to the Subscriber to which the DataReader belongs |
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.