RTI Connext C# API Version 7.3.0
Entity examples

How to use Rti.Dds.Core.Entity types: set QoS, monitor status changes, and more.

How to use Rti.Dds.Core.Entity types: set QoS, monitor status changes, and more.

The following code snippets show common operations for all Rti.Dds.Core.Entity types, including:

Sections:

Configuring an Entity's QoS

Example: set the default DomainParticipantQos for new DomainParticipants

// This assignment does several things:
// 1) Gets the current default DomainParticipantQos
// 2) Creates a new DefaultParticipantQos object by modifying two
// policies (Property and Database)
// 3) Uses this object to set a new default DomainParticipantQos
factory.DefaultParticipantQos = factory.DefaultParticipantQos
.WithProperty(policy => policy.Add("CompanyName", "Acme, Inc."))
.WithDatabase(policy => policy.ShutdownCleanupPeriod = Duration.FromMilliseconds(100));
// This DomainParticipant uses the new DomainParticipantQos we just set
using Rti.Dds.Domain.DomainParticipant participant =
factory.CreateParticipant(domainId: 0);
Debug.Assert(
participant.Qos.Property.Value["CompanyName"].Value == "Acme, Inc.");
Singleton that manages the creation of DomainParticipant objects.
Definition: DomainParticipantFactory.cs:25
static DomainParticipantFactory Instance
Gets the singleton instance of this class.
Definition: DomainParticipantFactory.cs:39
DomainParticipantQos DefaultParticipantQos
Gets or sets the default DomainParticipantQos
Definition: DomainParticipantFactory.cs:69
DomainParticipantQos WithProperty(Property policy)
Creates an instance with a new Property policy.
Definition: DomainParticipantQos.cs:477
DomainParticipantQos WithDatabase(Database policy)
Creates an instance with a new Database policy.
Definition: DomainParticipantQos.cs:296
Container for all other Entity objects.
Definition: DomainParticipant.cs:39
@ Debug
The message contains debug information that might be relevant to your application.
Contains DomainParticipant and related classes.
Definition: DomainParticipant.cs:33
Contains the RTI Connext DDS C# API.
Definition: AsyncWaitSetProperty.cs:18
Contains the RTI Connext C# API.
Definition: Logger.cs:20

Example: set the default DataReaderQos for new DataReaders created from a Subscriber

participant.CreateSubscriber();
// Update the default QoS as we did in the previous example
subscriber.DefaultDataReaderQos = subscriber.DefaultDataReaderQos
.WithReliability(policy => policy.Kind = ReliabilityKind.Reliable)
.WithDurability(policy => policy.Kind = DurabilityKind.TransientLocal)
.WithHistory(policy =>
{
policy.Kind = HistoryKind.KeepLast;
policy.Depth = 20;
});
// The new QoS we just set applies to all new readers created by this
// subscriber
var reader = subscriber.CreateDataReader(topic);
Debug.Assert(
reader.Qos.Durability.Kind == DurabilityKind.TransientLocal);
DataReaderQos WithReliability(Reliability policy)
Creates an instance with a new Reliability policy.
Definition: DataReaderQos.cs:312
DataReaderQos WithDurability(Durability policy)
Creates an instance with a new Durability policy.
Definition: DataReaderQos.cs:192
DataReaderQos WithHistory(History policy)
Creates an instance with a new History policy.
Definition: DataReaderQos.cs:372
A subscriber is the object responsible for actually receiving data from a subscription.
Definition: Subscriber.cs:32
DataReaderQos DefaultDataReaderQos
Copies the default DataReaderQos values into the provided DataReaderQos instance.
Definition: Subscriber.cs:126
DurabilityKind
Kinds of durability
Definition: IDurability.cs:17
ReliabilityKind
Kinds of reliability
Definition: Reliability.cs:190
HistoryKind
History kinds
Definition: History.cs:167
Contains the classes to support subscribing to topics.
Definition: Namespaces.cs:81

Example: create a DataReader with specific QoS

participant.CreateSubscriber();
// Create a DataReaderQos as a copy of subscriber.DefaultDataReaderQos
// with a few changes.
//
// Each "With<Policy>" call returns a new DataReaderQos
// object with the same values as before, except for the new policy
// that is being set. At the end, readerQos is a new object containing
// the values we set for the Reliability, Durability, ResourceLimits, and
// Property QoS policies.
// The rest of the QoS policies retain the value in subscriber.DefaultDataReaderQos.
DataReaderQos readerQos = subscriber.DefaultDataReaderQos
.WithReliability(policy => policy.Kind = ReliabilityKind.Reliable)
.WithDurability(policy => policy.Kind = DurabilityKind.TransientLocal)
.WithResourceLimits(policy =>
{
policy.InitialSamples = 10;
policy.MaxSamples = 40;
policy.MaxSamplesPerInstance = 10;
})
.WithProperty(policy =>
{
policy.Add("Company", "Acme, Inc.");
policy.Add("Group", "GroupA");
});
// Create the DataReader with the QoS we just defined
var reader = subscriber.CreateDataReader(topic, readerQos);
Debug.Assert(
reader.Qos.Property.Value["Company"].Value == "Acme, Inc.");
DataReaderQos WithResourceLimits(ResourceLimits policy)
Creates an instance with a new ResourceLimits policy.
Definition: DataReaderQos.cs:402

Example: modify a mutable DataReader QoS policy after creation

subscriber.CreateDataReader(topic);
reader.Qos = reader.Qos
.WithProperty(property => property["Group"] = "GroupB");
Debug.Assert(reader.Qos.Property.Value["Group"].Value == "GroupB");
Example C# class generated from the IDL struct MyType
Definition: MyType.cs:135
Allows the application to: (1) declare the data it wishes to receive (i.e. make a subscription) and (...
Definition: DataReader.cs:27
Definition: MyType.cs:17

Example: create a DataReader with a built-in QoS profile

// The built-in profiles are available in any QosProvider, including
// the default one. The default QosProvider also automatically loads
// the profiles in the file USER_QOS_PROFILES.xml in the working
// directory if it exists, and a few other locations.
var strictReliableQos = QosProvider.Default.GetDataReaderQos(
"BuiltinQosLib::Generic.StrictReliable");
// You can optionally modify additional QoS policies:
strictReliableQos = strictReliableQos.WithSubscriptionName("MyReader");
// Create the DataReader with the QoS we just defined
var reader = subscriber.CreateDataReader(topic, strictReliableQos);

Example: create a DataReader with a custom QoS profile

// To load a custom XML file with QoS profiles, create a QosProvider
var qosProvider = new QosProvider("MyProfiles.xml");
var subscriberQos = qosProvider.GetSubscriberQos("MyLibrary::MyProfile");
var subscriber = participant.CreateSubscriber(subscriberQos);
// If you don't specify a "Library::Profile" string, the QosProvider will
// look for one with the attribute is_default_qos="true"
var readerQos = qosProvider.GetDataReaderQos();
var reader = subscriber.CreateDataReader(topic, readerQos);

These examples from the rticonnextdds-examples GitHub repository show other uses cases related to configuring QoS:

Monitoring an Entity's Status Changes

Example: set up events to handle status updates for an Entity

// The event handlers for status updates can be set at the moment of
// creation to avoid missing any status update.
var reader = subscriber.CreateDataReader(
topic,
preEnableAction: reader =>
{
// In this function, reader has not been enabled yet
reader.SubscriptionMatched += (_, status)
=> Console.WriteLine($"Total matched publications = {status.TotalCount}");
reader.LivelinessChanged += MyLivelinessChangedHandler;
});
// Event handlers can be removed or added after creation:
reader.LivelinessChanged -= MyLivelinessChangedHandler;
reader.RequestedIncompatibleQos += (_, status) =>
{
var policy = status.LastPolicy.Name;
Console.WriteLine($"Incompatible QoS: {policy}");
};
// To remove multiple events handlers:
reader.ResetEvents(StatusMask.SubscriptionMatched | StatusMask.DataAvailable);
// To remove all event handlers:
reader.ResetEvents(StatusMask.All);
StatusMask
Each flag identifies a Entity status.
Definition: StatusMask.cs:19

Example: lookup the current status of an Entity

var samplesLost = reader.SampleLostStatus.TotalCount;
var incompatiblePublications = reader.RequestedIncompatibleQosStatus.TotalCount;
Console.WriteLine($"Reader has lost {samplesLost} samples and found {incompatiblePublications} incompatible publications");

The Instance Statistics example from the rticonnextdds-examples GitHub repository shows how to look up statistics related to a DataWriter and a DataReader.

Disposing an Entity

An Entity can be deleted by explicitly disposing it or by disposing its factory. In many applications, it is only necessary to dispose the DomainParticipants.

To dispose an entity call its Dispose() method or scope it with the using keyword.

See, for example, Writing data and instances.

Accessing Information on Entity Discovery

Information about discovered DomainParticipants, DataReaders, and DataWriters can be accessed using the built-in discovery readers in Rti.Dds.Domain.DomainParticipant.BuiltinSubscriber. See the Builtin Topics example from the rticonnextdds-examples GitHub repository.

You can also look up information about the publications/subscriptions that match with a local subscription/publication. See Looking up matched publications.