DataReader Use Cases

Working with data readers.

Working with data readers.

Setting up a data reader

• Set up subscriber
• Set up a topic
• Create a data reader, FooDataReader, of user data type Foo:

  DDS_DataReaderQos reader_qos;
  DDS_ReturnCode_t retcode;
   
  // MyReaderListener is user defined and 
  // extends DDSDataReaderListener
  DDSDataReaderListener* reader_listener =
        new MyReaderListener(); // or = NULL
   
  retcode = subscriber->get_default_datareader_qos(reader_qos);
   
  if (retcode != DDS_RETCODE_OK) {
      // ... error 
   
  };
   
  FooDataReader* reader = subscriber->create_datareader(topic,
                                                        reader_qos, 
                                                        reader_listener,
                                                  DDS_STATUS_MASK_ALL);
  if (reader == NULL) {
      // ... error 
   
  };

Managing instances

• Given a data reader

  FooDataReader* reader = ...;

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

  Foo data;     // user data of type Foo
  // ...
  retcode = reader->get_key_value(data, instance_handle);
   
  if (retcode != DDS_RETCODE_OK) {
      // ... check for cause of failure
  }    

Set up reader to access received data

• Set up data reader
• Set up to handle the DDS_DATA_AVAILABLE_STATUS status, in one or both of the following two ways.
• Enable DDS_DATA_AVAILABLE_STATUS for the DDSDataReaderListener associated with the data reader
  • The processing to handle the status change is done in the DDSDataReaderListener::on_data_available method of the attached listener.
  • Typical processing will access the received data.
• Enable DDS_DATA_AVAILABLE_STATUS for the DDSStatusCondition associated with the data reader
  
  • The processing to handle the status change is done when the data reader's attached status condition is triggered and the DDS_DATA_AVAILABLE_STATUS status on the data reader is changed.
  • Typical processing will access the received data.

Access received data via a reader

• Ensure reader is set up to access received data
• Access the received data, by either:
  • Taking the received data in the reader, OR
  • Reading the received data in the reader

Taking data

• Ensure reader is set up to access received data
• Take samples of user data type T. The samples are removed from the Service. The caller is responsible for deallocating the buffers.

  FooSeq                data_seq; // holder for sequence of user data type Foo
  DDS_SampleInfoSeq     info_seq; // holder for sequence of DDS_SampleInfo
  long                  max_samples       = DDS_LENGTH_UNLIMITED;
  DDS_SampleStateMask   sample_state_mask = DDS_ANY_SAMPLE_STATE;
  DDS_ViewStateMask     view_state_mask = DDS_ANY_VIEW_STATE;
  DDS_InstanceStateMask instance_state_mask = DDS_ANY_INSTANCE_STATE;
   
  DDS_ReturnCode_t retcode;
   
  retcode = reader->take(data_seq, info_seq, 
                   max_samples,
                         sample_state_mask, 
                         view_state_mask,
                         instance_state_mask); 
   
  if (retcode == DDS_RETCODE_NO_DATA) {
      return;
  } else if (retcode != DDS_RETCODE_OK) {
      // ... check for cause of failure
  }

• Use the received data

  // Use the received data samples 'data_seq' and associated information 'info_seq'
  for(int i = 0; i < data_seq.length(); ++i) {
      // use... data_seq[i] ...
      // use... info_seq[i] ...
  }

• Return the data samples and the information buffers back to the middleware. IMPORTANT: Once this call returns, you must not retain any pointers to any part of any sample or sample info object.

  retcode = reader->return_loan(data_seq, info_seq); 
   
  if (retcode != DDS_RETCODE_OK) {
      // ... check for cause of failure
  }

Reading data

• Ensure reader is set up to access received data
• Read samples of user data type Foo. The samples are not removed from the Service. It remains responsible for deallocating the buffers.

  FooSeq                data_seq; // holder for sequence of user data type Foo
  DDS_SampleInfoSeq      info_seq; // holder for sequence of DDS_SampleInfo
  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;
   
  retcode = reader->read(data_seq, info_seq,
                   max_samples,
                         sample_state_mask, 
                         view_state_mask,
                         instance_state_mask); 
   
  if (retcode == DDS_RETCODE_NO_DATA) {
      return;
  } else if (retcode != DDS_RETCODE_OK) {
      // ... check for cause of failure
  }

• Use the received data

  // Use the received data samples 'data_seq' and associated 
  // information 'info_seq'
  for(int i = 0; i < data_seq.length(); ++i) {
      // use... data_seq[i] ...
      // use... info_seq[i] ...
  }

• Return the data samples and the information buffers back to the middleware

  retcode = reader->return_loan(data_seq, info_seq);
   
  if (retcode != DDS_RETCODE_OK) {
      // ... check for cause of failure
  }

Tearing down a data reader

• Delete DDSDataReader:

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