DataReader Use Cases
[Programming How-To's]

Working with data readers. More...

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
    }