DataWriter Use Cases

The following #includes are needed for the examples on this page

#include <dds/pub/ddspub.hpp>
#include <dds/domain/ddsdomain.hpp>
#include <dds/core/ddscore.hpp>
#include <dds/topic/ddstopic.hpp>
#include <dds/sub/ddssub.hpp>
#include <rti/core/ListenerBinder.hpp>

#include "Foo.hpp"

Setting up a DataWriter

• Set up a Publisher

• Set up a Topic

• Create a DataWriter of user-defined type Foo with each of the available constructors

      // Create the Participant
      dds::domain::DomainParticipant participant(0);
  
      // Create a Topic
      dds::topic::Topic<Foo> topic(participant, "MyTopicName");
  
      // When not explicitly provided to the constructor, the 
      // created DataWriter's QoS is default, has a NULL listener, and a status mask
      // dds::core::status::StatusMask::all()
  
      // Creating a DataWriter, creating the subscriber inline
      dds::pub::DataWriter<Foo> writer1(dds::pub::Publisher(participant), topic);
  
      // Create a Publisher
      dds::pub::Publisher publisher(participant);
  
      // Create a DataWriter with modified QoS
      dds::pub::qos::DataWriterQos writer_qos = 
              dds::core::QosProvider::Default().datawriter_qos();
      writer_qos << dds::core::policy::Liveliness::ManualByParticipant();
      dds::pub::DataWriter<Foo> writer2(publisher, topic, writer_qos);
  
      // Create a DataWriter with the Qos of a topic
      writer_qos = topic.qos(); // Copy the policies in TopicQos into a DataWriterQos
      dds::pub::DataWriter<Foo> writer3(publisher, topic, writer_qos);
  
      // Create a DataWriter with modified QoS and a listener
      ExampleDataWriterListener<Foo> listener;
      dds::pub::DataWriter<Foo> writer4(
         publisher, 
         topic, 
         writer_qos, 
         &listener);
  
      // Create a DataWriter with modified QoS, a listener, and a liveliness_lost() 
      // status mask
      dds::pub::DataWriter<Foo> writer5(
         publisher, 
         topic, 
         writer_qos, 
         &listener, 
         dds::core::status::StatusMask::liveliness_lost());
  
      // Create a DataWriter, then set a listener using bind_and_manage_listener
      dds::pub::DataWriter<Foo> writer6(publisher, topic);
      auto listener_binder = rti::core::bind_and_manage_listener(
          writer6,
          new ExampleDataWriterListener<Foo>, 
          dds::core::status::StatusMask::liveliness_lost());
  
      // Creating an entity with a listener automatically retains the entity, so 
      // we must either explicitly close the DataWriter...
      writer4.close();
      
      // ... or set the listener to null
      writer5.listener(NULL, dds::core::status::StatusMask::none());
  
      // For writer6 we don't need to do anything, since the listener binder
      // takes care of setting the listener to null

Managing instances

• The snippets in this section assume the following setup

      dds::domain::DomainParticipant participant(0);
      dds::topic::Topic<Foo> topic(participant, "MyTopic");
      dds::pub::DataWriter<Foo> writer(dds::pub::Publisher(participant), topic);
  
      Foo sample;
      sample.x(100);

  
  
• Getting an instance "key" value of user data type Foo

      // Instead of a sample of type Foo, key_value() could also take a 
      // TopicInstance<Foo> object. key_value only populates the key field in the 
      // sample
      Foo retrieved_sample_key;
      writer.key_value(retrieved_sample_key, handle);

  
  
• Registering an instance of type Foo

      dds::core::InstanceHandle handle = writer.register_instance(sample);

  
  
• Unregistering an instance of type Foo

      writer.unregister_instance(handle);

  
  
• Disposing of an instance of type Foo

      writer.dispose_instance(handle);

Sending data

• Set up a DataWriter

• Register an instance

• Write instances of type Foo (see also Working with IDL types)

      Foo data;
      dds::core::InstanceHandle handle = 
          dds::core::InstanceHandle::nil();
      dds::core::Time timestamp(123);
  
      // Write a sample 
      writer.write(data);
  
      // You can also write a sample with a timestamp that will be used as the 
      // source timestamp for this sample
      writer.write(data, timestamp);
  
      // You can also write a sample with an InstanceHandle
      writer.write(data, handle);
  
      // The above call to write is equivalent to the following
      writer.write(dds::topic::TopicInstance<Foo>(handle, data));
  
      // Or a combination of handle and timestamp
      writer.write(data, handle, timestamp);
  
      // The above call to write is equivalent to the following
      writer.write(dds::topic::TopicInstance<Foo>(handle, data), timestamp);
  
      // Create a vector of three default-constructed samples
      std::vector<Foo> samples(3, Foo());
  
      // You can also write samples that are stored in a container by 
      // passing in an iterator range to write()
      writer.write(samples.begin(), samples.end());
  
      // You can add a timestamp to the above call to write
      writer.write(samples.begin(), samples.end(), timestamp);
  
      // Create a vector of three instance handles
      std::vector<dds::core::InstanceHandle> handles(
         3, dds::core::InstanceHandle::nil());
  
      // Write 3 samples along with their handles
      writer.write(samples.begin(), samples.end(), 
                   handles.begin(), handles.end());
  
      // You can add a timestamp to the above call to write
      writer.write(samples.begin(), samples.end(), 
                   handles.begin(), handles.end(), 
                   timestamp);
  
      // You can also use operator << to write samples
      writer << Foo(1, 2)
             << std::make_pair(Foo(3, 4), timestamp) // add a timestamp
             << std::make_pair(Foo(5, 6), handle); // add an instance handle
  
  

DataWriter Listeners

• Implementing a DataWriterListener class

  // To create a DataWriterListener, inherit from the NoOpDataWriterListener class
  // and then override any of the listener callback functions 
  template <typename T>
  class ExampleDataWriterListener : public dds::pub::NoOpDataWriterListener<T> 
  {
  public:
      ExampleDataWriterListener() {}
  
  public:
      void on_publication_matched(
         dds::pub::DataWriter<T>&,
         const dds::core::status::PublicationMatchedStatus &status)
      {
          std::cout << "on_publication_matched callback" << std::endl;
  
          // Access information from the status
          std::cout << "total_count = " << status.total_count() << std::endl;
          std::cout << "total_count_change = " << status.total_count_change() << std::endl;
          std::cout << "current_count = " << status.current_count() << std::endl;
          std::cout << "current_count_change = " << status.current_count_change() << std::endl;
  
          dds::core::InstanceHandle handle = status.last_subscription_handle();
  
          // Extension
          std::cout << "current_count_peak = " << status->current_count_peak() << std::endl;
      }
  
      void on_offered_incompatible_qos(
         dds::pub::DataWriter<T>&,
         const dds::core::status::OfferedIncompatibleQosStatus &status)
      {
          std::cout << "on_offered_incompatible_qos callback" << std::endl;
  
          // Access information from the status
          std::cout << "total_count = " << status.total_count() << std::endl;
          std::cout << "total_count_change = " << status.total_count_change() << std::endl;
          std::cout << "last_policy_id = " << status.last_policy_id() << std::endl;
  
          dds::core::policy::QosPolicyCountSeq qos_seq = status.policies();
          if (qos_seq.size() > 0) {
              std::cout << "policy_id of one first incompatible Qos policy = " 
                  << qos_seq[0].policy_id() << std::endl;
          }
      }
  
      void on_offered_deadline_missed(
         dds::pub::DataWriter<T>&,
         const dds::core::status::OfferedDeadlineMissedStatus &status)
      {
          std::cout << "on_offered_deadline_missed callback" << std::endl;
  
          // Access information from the status
          std::cout << "total_count = " << status.total_count() << std::endl;
          std::cout << "total_count_change = " << status.total_count_change() << std::endl;
  
          dds::core::InstanceHandle handle = status.last_instance_handle();
      }
  
      void on_liveliness_lost(
         dds::pub::DataWriter<T>&,
         const dds::core::status::LivelinessLostStatus &status)
      {
          std::cout << "on_liveliness_lost callback" << std::endl;
  
          // Access information from the status
          std::cout << "total_count = " << status.total_count() << std::endl;
          std::cout << "total_count_change = " << status.total_count_change() << std::endl;
      }
  
  };

  
  
• Setting a listener on a DataWriter

      dds::domain::DomainParticipant participant(0);
      dds::topic::Topic<Foo> topic(participant, "Topic1");
  
      ExampleDataWriterListener<Foo> *listener = new ExampleDataWriterListener<Foo>;
  
      // Create a DataWriter with a listener and default 
      // dds::core::status::StatusMask::all()
      dds::pub::DataWriter<Foo> writer1(
         dds::pub::Publisher(participant), 
         topic,
         dds::pub::qos::DataWriterQos(), 
         listener);
  
      // Create a DataWriter with a null listener
      dds::pub::DataWriter<Foo> writer2(
         dds::pub::Publisher(participant), topic);
  
      // Set the listener for the DataWriter after creation
      writer2.listener(
         listener, 
         dds::core::status::StatusMask::offered_incompatible_qos());
  
      // Setting a listener on an entity automatically retains the entity so 
      // we must explicitly call close() in order for the DataWriter to be
      // destroyed 
      writer1.close();
  
      // Instead of calling close, you can set the DataWriter's listener to null 
      // and this will implicitly unretain the DataWriter so that it will be 
      // destructed once all references to it go out of scope
      writer2.listener(NULL, dds::core::status::StatusMask::none());
  
      delete listener;

  
  
• The ListenerBinder class will take care of setting the listener and mask for an entity during creation and detaching the listener from the entity when the ListenerBinder is destructed. This is helpful because you will not have to explcitly close the entity or detach the listener yourself in order to teardown the entity

      dds::domain::DomainParticipant participant(0);
      dds::topic::Topic<Foo> topic(participant, "Topic1");
  
      // Create a DataWriter with a null listener
      dds::pub::DataWriter<Foo> writer(dds::pub::Publisher(participant), topic);
  
      // Attach the listener to the DataWriter after creation using a 
      // ListenerBinder. (Note: rti/core/ListenerBinder.hpp needs to be included)
      auto listener_binder = rti::core::bind_and_manage_listener(
              writer, 
              new ExampleDataWriterListener<Foo>, 
              dds::core::status::StatusMask::liveliness_lost());
  
      // To get the listener:
      ExampleDataWriterListener<Foo> *listener = listener_binder.listener(); 
  
      // To get the entity:
      dds::pub::DataWriter<Foo> writer2 = listener_binder.entity();
      assert(writer == writer2);
  
      // When the reference count reaches zero, the listener_binder destructor 
      // sets the writer's listener to NULL, and deletes the listener (to not
      // delete the listener we would have used bind_listener() instead of 
      // bind_and_manage_listener()).
      //

Looking up DataWriters

• Lookup DataWriters by topic name

      dds::domain::DomainParticipant participant(0);
      dds::pub::Publisher publisher(participant);
  
      dds::topic::Topic<Foo> topic1(participant, "Topic1");
      dds::topic::Topic<Foo> topic2(participant, "Topic2");
  
      // Create three DataWriters for topic1 and one for topic2 and retain them
      create_and_retain_writer(publisher, topic1);
      create_and_retain_writer(publisher, topic1);
      create_and_retain_writer(publisher, topic2);
  
      // We don't have any references to the created DataWriters but we can look 
      // them up using the publisher and topic name that they were created with
      std::vector<dds::pub::DataWriter<Foo> > writers;
  
      // writer_count will equal 1. If more than one DataWriter belongs to a 
      // publisher with the same topic name then find may return any one of them
      int writer_count = 
          dds::pub::find<dds::pub::DataWriter<Foo> >(
             publisher, 
             "Topic1", 
             std::back_inserter(writers));
  
      writer_count = 
          dds::pub::find<dds::pub::DataWriter<Foo> >(
             publisher, 
             "Topic2", 
             std::back_inserter(writers));
  

  For more examples, see Looking up DataReaders

Getting Matched Subscriptions

• Lookup a DataWriter's matched subscriptions

      dds::domain::DomainParticipant participant(0);
      dds::topic::Topic<Foo> topic(participant, "Topic1");
      dds::pub::DataWriter<Foo> writer(dds::pub::Publisher(participant), topic);
  
      // Create two readers that will match with the above writer
      dds::sub::DataReader<Foo> reader1(dds::sub::Subscriber(participant), topic);
      dds::sub::DataReader<Foo> reader2(dds::sub::Subscriber(participant), topic);
  
      // Get a list of the InstanceHandles corresponding to the DataWriter's 
      // matched subscriptions.
      dds::core::InstanceHandleSeq subscription_handles1 = 
          dds::pub::matched_subscriptions(writer);
  
      // matched_subscriptions also takes in an iterator range and will return
      // an InstanceHandle iterator to the end of the InstanceHandleSeq
      dds::core::InstanceHandleSeq subscription_handles2(2, dds::core::null);
  
      dds::core::InstanceHandleSeq::iterator last = 
          dds::pub::matched_subscriptions(
             writer, 
             subscription_handles2.begin(), 
             subscription_handles2.end());
  
      // now last == subscription_handles2.end()

  
  
• Use the InstanceHandles obtained from matched_subscriptions() to get the SubscriptionBuiltinTopicData for the subscriptions

      dds::topic::SubscriptionBuiltinTopicData subscription_data =
          dds::pub::matched_subscription_data(writer, subscription_handles1[0]);

Tearing down a DataWriter

• See Tearing Down An Entity for eamples of the various ways to teardown a DataWriter