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:

    DataReaderQos reader_qos = new DataReaderQos();
    DataReaderListener reader_listener = null;
  
    try {
        subscriber.get_default_datareader_qos(reader_qos);
    } catch (DDS.Exception) {
        Console.WriteLine(
            "***Error: failed to get default datareader qos");
    }
  
    DataReader reader = subscriber.create_datareader(
        topic,
        reader_qos,
        reader_listener,
        StatusMask.STATUS_MASK_NONE);
    if (reader == null) {
            Console.WriteLine("***Error: failed to create reader");
    }
  

Managing instances

• Given a data reader

   FooDataReader reader = ...;
  

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

    Foo data = new Foo(); // user data of type Foo
    // ...
    try {
        reader.get_key_value(data, instance_handle);
    } catch (DDS.Exception) {
        // ... check for cause of failure
    }    
  

Set up reader to access received data

• Set up data reader

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

• Enable DATA_AVAILABLE_STATUS for the DataReaderListener associated with the data reader
  • The processing to handle the status change is done in the DDS::DataReaderListener::on_data_available method of the attached listener.
  • Typical processing will access the received data.

• Enable DATA_AVAILABLE_STATUS for the StatusCondition 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 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 = new FooSeq(); // sequence of user data type Foo
    SampleInfoSeq info_seq = new SampleInfoSeq(); // sequence of SampleInfo
    int max_samples = ResourceLimitsQosPolicy.LENGTH_UNLIMITED;
    SampleStateKind sample_state_mask =
        SampleStateKind.ANY_SAMPLE_STATE;
    ViewStateKind view_state_mask =
        ViewStateKind.ANY_VIEW_STATE;
    InstanceStateKind instance_state_mask =
        InstanceStateKind.ANY_INSTANCE_STATE;
  
    try {
        reader.take(data_seq, info_seq, 
            max_samples,
            sample_state_mask, 
            view_state_mask, 
            instance_state_mask); 
    } catch (Retcode_NoData) {
        return;
    } catch (DDS.Exception) {
        Console.WriteLine(
            "***Error: failed to access data from the reader");
    }
  

• Use the received data

    // Use the received data samples 'data_seq' and associated
    // meta-information 'info_seq'
    for (int i = 0; i < data_seq.length; ++i) {
        SampleInfo info = info_seq.get_at(i);
        if (!info.valid_data) {
            continue;
        }
        Foo data = data_seq.get_at(i);
  
        Console.WriteLine(
            "  Data = (%d, %d)   sample_state = %d",
            data.x, data.y, info.sample_state);
    }
  

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

    try {
        reader.return_loan(data_seq, info_seq);
    } catch (DDS.Exception) {
        Console.WriteLine("***Error: failed to return loan");
    }
  

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 = new FooSeq(); // sequence of user data type Foo
    SampleInfoSeq info_seq = new SampleInfoSeq(); // sequence of SampleInfo
    int max_samples = ResourceLimitsQosPolicy.LENGTH_UNLIMITED;
    SampleStateKind sample_state_mask =
        SampleStateKind.ANY_SAMPLE_STATE;
    ViewStateKind view_state_mask =
        ViewStateKind.ANY_VIEW_STATE;
    InstanceStateKind instance_state_mask =
        InstanceStateKind.ANY_INSTANCE_STATE;
  
    try {
        reader.read(data_seq, info_seq, 
            max_samples,
            sample_state_mask, 
            view_state_mask, 
            instance_state_mask); 
    } catch (Retcode_NoData) {
        return;
    } catch (DDS.Exception) {
        Console.WriteLine(
            "***Error: failed to access data from the reader");
    }
  

• Use the received data

    // Use the received data samples 'data_seq' and associated
    // meta-information 'info_seq'
    for (int i = 0; i < data_seq.length; ++i) {
        SampleInfo info = info_seq.get_at(i);
        if (!info.valid_data) {
            continue;
        }
        Foo data = data_seq.get_at(i);
  
        Console.WriteLine(
            "  Data = (%d, %d)   sample_state = %d",
            data.x, data.y, info.sample_state);
    }
  

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

    try {
        reader.return_loan(data_seq, info_seq);
    } catch (DDS.Exception) {
        Console.WriteLine("***Error: failed to return loan");
    }
  

Tearing down a data reader

• Delete DataReader:

    try {
        subscriber.delete_datareader(ref reader);
    } catch (DDS.Exception) {
        Console.WriteLine("***Error: failed to delete reader");
    }