Subscriber Use Cases

Working with subscribers.

Working with subscribers.

Setting up a subscriber

• Set up participant
• Create a DDS_Subscriber

  struct DDS_SubscriberQos subscriber_qos = DDS_SubscriberQos_INITIALIZER;
  DDS_Subscriber* subscriber;
  struct DDS_SubscriberListener subscriber_listener = DDS_SubscriberListener_INITIALIZER;
  DDS_ReturnCode_t retcode;
   
  /* MySubscriberListener_* functions are user defined to match
     DDS_SubscriberListener functions */
  subscriber_listener.on_data_on_readers = 
      MySubscriberListener_DataOnReaders;
  subscriber_listener.as_datareaderlistener.on_requested_deadline_missed = 
      MySubscriberListener_RequestedDeadlineMissed;
  subscriber_listener.as_datareaderlistener.on_requested_incompatible_qos = 
      MySubscriberListener_RequestedIncompatibleQos;
  subscriber_listener.as_datareaderlistener.on_sample_rejected =  
      MySubscriberListener_SampleRejected;
  subscriber_listener.as_datareaderlistener.on_liveliness_changed =  
      MySubscriberListener_LivelinessChanged;
  subscriber_listener.as_datareaderlistener.on_data_available =  
      MySubscriberListener_DataAvailable;
  subscriber_listener.as_datareaderlistener.on_subscription_matched = 
      MySubscriberListener_SubscriptionMatch;
  subscriber_listener.as_datareaderlistener.on_sample_lost = 
      MySubscriberListener_SampleLost;
   
  retcode = DDS_DomainParticipant_get_default_subscriber_qos(participant, 
                                                   &subscriber_qos);
   
  if (retcode != DDS_RETCODE_OK) {
      printf("***Error: failed to get default subscriber qos\n");
  }
   
  subscriber =  DDS_DomainParticipant_create_subscriber(participant, 
                                                        &subscriber_qos, 
                                                        &subscriber_listener /*or NULL*/,
                                                  DDS_STATUS_MASK_ALL);
   
  if (subscriber == NULL) {
      printf("***Error: failed to create subscriber\n");
  }

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 DDS_SubscriberListener associated with the subscriber
  • The processing to handle the status change is done in the DDS_SubscriberListener_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 DDS_StatusCondition 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:

  struct DDS_DataReaderSeq reader_seq = DDS_SEQUENCE_INITIALIZER;
  long                     max_samples = DDS_LENGTH_UNLIMITED;
  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 = DDS_RETCODE_OK;  
   
  retcode = DDS_Subscriber_get_datareaders(subscriber,
                                           &reader_seq, 
                                           max_samples,
                                           sample_state_mask,
                                           view_state_mask, 
                                           instance_state_mask);
   
   
  if (retcode != DDS_RETCODE_OK) {
         printf("***Error: failed to access received data via subscriber\n");
         return;
  }

• 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:

  int i;
  for(i = 0; i < DDS_DataReaderSeq_get_length(&reader_seq); ++i) {
    
    TDataReader* reader = DDS_DataReaderSeq_get_reference(&reader_seq, i);
   
    /* Take the data from reader, 
                  OR
       Read the data from reader  */
  }

• Alternatively, call DDS_Subscriber_notify_datareaders to invoke the DDS_DataReaderListener for each of the data readers.

  DDS_ReturnCode_t retcode;
   
  retcode = DDS_Subscriber_notify_datareaders(subscriber);
   
  if (retcode != DDS_RETCODE_OK) {
      printf("***Error: failed to notify datareaders\n");
  }

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 DDS_Subscriber:

• Ensure subscriber is set up to access received data
• Indicate that data will be accessed via the subscriber:

  retcode = DDS_Subscriber_begin_access(subscriber);
   
  if (retcode != DDS_RETCODE_OK) {
      printf("***Error: failed to begin access\n");
  }

• 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 = DDS_Subscriber_end_access(subscriber);
   
  if (retcode != DDS_RETCODE_OK) {
      printf("***Error: failed to end access\n");
  }

Tearing down a subscriber

• Delete DDS_Subscriber:

  DDS_ReturnCode_t retcode;
   
  retcode = DDS_DomainParticipant_delete_subscriber(participant, subscriber);
   
  if (retcode != DDS_RETCODE_OK) {
      printf("***Error: failed to delete subscriber\n");
  }