Subscriber Use Cases
[Programming How-To's]

Working with subscribers. More...

Setting up a subscriber

• Set up participant

• Create a DDSSubscriber

    DDS_SubscriberQos subscriber_qos;
    DDS_ReturnCode_t retcode;
  
    // MySubscriberListener is user defined and 
    // extends DDSSubscriberListener
    DDSSubscriberListener* subscriber_listener =
                                    new MySubscriberListener(); // or = NULL
  
    retcode = participant->get_default_subscriber_qos(subscriber_qos);
  
    if (retcode != DDS_RETCODE_OK) {
        // ... error 
  
    };
  
    DDSSubscriber* subscriber = 
                          participant->create_subscriber(subscriber_qos, 
                                                         subscriber_listener,
                                                         DDS_STATUS_MASK_ALL);
    if (subscriber == NULL) {
        // ... error 
  
    };
  

Set up subscriber to access received data

• Set up subscriber

• Set up to handle the DDS_DATA_ON_READERS_STATUS status, in one or both of the following two ways.

• Enable DDS_DATA_ON_READERS_STATUS for the DDSSubscriberListener associated with the subscriber
  • The processing to handle the status change is done in the DDSSubscriberListener::on_data_on_readers() method of the attached listener.
  • Typical processing will access the received data, either in arbitrary order or in a coherent and ordered manner.

• Enable DDS_DATA_ON_READERS_STATUS for the DDSStatusCondition associated with the subscriber
  • The processing to handle the status change is done when the subscriber's attached status condition is triggered and the DDS_DATA_ON_READERS_STATUS status on the subscriber is changed.
  • Typical processing will access the received data, either in an arbitrary order or in a coherent and ordered manner.

Access received data via a subscriber

• Ensure subscriber is set up to access received data

• Get the list of readers that have data samples available:

    DDSDataReaderSeq reader_seq;  // holder for list/set of readers
    DDS_SampleStateMask     sample_state_mask = DDS_NOT_READ_SAMPLE_STATE;
    DDS_ViewStateMask       view_state_mask = DDS_ANY_VIEW_STATE;
    DDS_InstanceStateMask   instance_state_mask = DDS_ANY_INSTANCE_STATE;
  
  
    DDS_ReturnCode_t retcode;
  
    // get_datareadersX is not supported yet.
    retcode = subscriber->get_datareaders(reader_seq, 
                                           sample_state_mask,
                                           view_state_mask,
                                           instance_state_mask);
  
    if (retcode != DDS_RETCODE_OK) {
        // ... check for cause of failure
    } 
  

• Upon successfully getting the list of readers with data, process the data readers to either:
  • Read the data in each reader, OR
  • Take the data in each reader
  If the intent is to access the data coherently or in order, the list of data readers must be processed in the order returned:

      for(int i = 0; i < reader_seq.length(); ++i) {
        
        TDataReader* reader = reader_seq[i];
  
        // Take the data from reader, 
        //            OR
        // Read the data from reader
      }
  

• Alternatively, call DDSSubscriber::notify_datareaders() to invoke the DDSDataReaderListener for each of the data readers.

      retcode = subscriber->notify_datareaders(); 
  
      if (retcode != DDS_RETCODE_OK) {
          // ... check for cause of failure
      } 
  

Access received data coherently and/or in order

To access the received data coherently and/or in an ordered manner, according to the settings of the DDS_PresentationQosPolicy attached to a DDSSubscriber:

• Ensure subscriber is set up to access received data

• Indicate that data will be accessed via the subscriber:

    retcode = subscriber->begin_access();
  
    if (retcode != DDS_RETCODE_OK) {
        // ... check for cause of failure
    } 
  

• Access received data via the subscriber, making sure that the data readers are processed in the order returned.

• Indicate that the data access via the subscriber is done:

    retcode = subscriber->end_access();
  
    if (retcode != DDS_RETCODE_OK) {
        // ... check for cause of failure
    } 
  

Tearing down a subscriber

• Delete DDSSubscriber:

    DDS_ReturnCode_t retcode;
  
    retcode = participant->delete_subscriber(subscriber);
  
    if (retcode != DDS_RETCODE_OK) {
        // ... check for cause of failure
    }