5.3. Sending Data

This section discusses how to create, configure, and use Publishers and DataWriters to send data. It describes how these Entities interact, as well as the types of operations that are available for them.

The goal of this section is to help you become familiar with the Entities you need for sending data. For up-to-date details such as formal parameters and return codes on any mentioned operations, please see the C API Reference and C++ API Reference documentation.

5.3.1. Preview: Steps to Sending Data

To send DDS samples of a data instance:

  1. Create and configure the required Entities:

    1. Create a DomainParticipant.

    2. Register user data types with the DomainParticipant. For example, the ‘FooDataType’.

    3. Use the DomainParticipant to create a Topic with the registered data type.

    4. Use the DomainParticipant to create a Publisher.

    5. Use the Publisher or DomainParticipant to create a DataWriter for the Topic.

    6. Use a type-safe method to cast the generic DataWriter created by the Publisher to a type-specific DataWriter. For example, ‘FooDataWriter’. Optionally, register data instances with the DataWriter. If the Topic’s user data type contain key fields, then registering a data instance (data with a specific key value) will improve performance when repeatedly sending data with the same key. You may register many different data instances; each registration will return an instance handle corresponding to the specific key value. For non-keyed data types, instance registration has no effect.

  2. Every time there is changed data to be published:

    1. Store the data in a variable of the correct data type (for instance, variable ‘Foo’ of the type ‘FooDataType’).

    2. Call the FooDataWriter’s write() operation, passing it a reference to the variable ‘Foo’.

      • For non-keyed data types or for non-registered instances, also pass in DDS_HANDLE_NIL.

      • For keyed data types, pass in the instance handle corresponding to the instance stored in ‘Foo’, if you have registered the instance previously. This means that the data stored in ‘Foo’ has the same key value that was used to create instance handle.

    3. The write() function will take a snapshot of the contents of ‘Foo’ and store it in Connext DDS internal buffers from where the DDS data sample is sent under the criteria set by the Publisher’s and DataWriter’s QosPolicies. If there are matched DataReaders, then the DDS data sample will have been passed to the physical transport plug-in/device driver by the time that write() returns.

5.3.2. Publishers

An application that intends to publish information needs the following Entities: DomainParticipant, Topic, Publisher, and DataWriter. All Entities have a corresponding specialized Listener and a set of QosPolicies. A Listener is how Connext DDS notifies your application of status changes relevant to the Entity. The QosPolicies allow your application to configure the behavior and resources of the Entity.

  • A DomainParticipant defines the DDS domain in which the information will be made available.

  • A Topic defines the name under which the data will be published, as well as the type (format) of the data itself.

  • An application writes data using a DataWriter. The DataWriter is bound at creation time to a Topic, thus specifying the name under which the DataWriter will publish the data and the type associated with the data. The application uses the DataWriter’s write() operation to indicate that a new value of the data is available for dissemination.

  • A Publisher manages the activities of several DataWriters. The Publisher determines when the data is actually sent to other applications. Depending on the settings of various QosPolicies of the Publisher and DataWriter, data may be buffered to be sent with the data of other DataWriters or not sent at all. By default, the data is sent as soon as the DataWriter’s write() function is called.

    You may have multiple Publishers, each managing a different set of DataWriters, or you may choose to use one Publisher for all your DataWriters.

5.3.3. DataWriters

To create a DataWriter, you need a DomainParticipant, Publisher, and a Topic.

You need a DataWriter for each Topic that you want to publish. For more details on all operations, see the C API Reference and C++ API Reference documentation.

For more details on creating, deleting, and setting up DataWriters, see replace:: the DataWriters section in the RTI Connext DDS Core Libraries User’s Manual (available here if you have Internet access).

5.3.4. Publisher/Subscriber QosPolicies

Please refer to the C API Reference and C++ API Reference for details on supported QosPolicies.

5.3.5. DataWriter QosPolicies

Please refer to the C API Reference and C++ API Reference for details on supported QosPolicies.