3.4.4. DataReader

A DataReader is attached to exactly one Subscriber that acts as a factory for it. Additionally, each DataReader is bound to a single Topic since its creation. This Topic must exist prior to the creation of the DataReader, and must be bound to the data type that the DataReader wants to publish.

The effect of creating a new DataReader in a Subscriber for a specific Topic is to initiate a new subscription with the name and data type described by the Topic.

Once the DataReader is created, the application will be informed when changes in the data value are received from remote publications. These changes can then be retrieved using the DataReader::read_next_sample() or DataReader::take_next_sample() member functions of the DataReader.

3.4.4.1. DataReaderQos

DataReaderQoS controls the behavior of the DataReader. Internally it contains the following QosPolicy objects:

QosPolicy class

Accessor/Mutator

Mutable

DurabilityQosPolicy

durability()

No

DurabilityServiceQosPolicy

durability_service()

Yes

DeadlineQosPolicy

deadline()

Yes

LatencyBudgetQosPolicy

latency_budget()

Yes

LivelinessQosPolicy

liveliness()

No

ReliabilityQosPolicy

reliability()

No (*)

DestinationOrderQosPolicy

destination_order()

No

HistoryQosPolicy

history()

No

ResourceLimitsQosPolicy

resource_limits()

No

LifespanQosPolicy

lifespan()

Yes

UserDataQosPolicy

user_data()

Yes

OwnershipQosPolicy

ownership()

No

PropertyPolicyQos

properties()

Yes

RTPSEndpointQos

endpoint()

Yes

ReaderResourceLimitsQos

reader_resource_limits()

Yes

RTPSEndpointTimeBasedFilterQosPolicy

time_based_filter()

Yes

ReaderDataLifecycleQosPolicy

reader_data_lifecycle()

Yes

RTPSReliableReaderQos

reliable_reader_qos()

Yes (*)

TypeConsistencyEnforcementQosPolicy

type_consistency()

Yes

DataRepresentationQosPolicy

representation()

Yes

DataSharingQosPolicy

data_sharing()

No

boolean

expects_inline_qos()

Yes

The following non-consolidated property-assigned QoS apply to DataReaders:

Property name

Non-consolidated QoS

partitions

Endpoint Partitions

Refer to the detailed description of each QosPolicy class for more information about their usage and default values.

Note

Reliability kind (whether the publication is reliable or best effort) is not mutable. However, the max_blocking_time data member of ReliabilityQosPolicy can be modified any time.

Note

Not all data members of RTPSReliableReaderQos are mutable, please refer to RTPSReliableReaderQos for more information.

The QoS value of a previously created DataReader can be modified using the DataReader::set_qos() member function.

// Create a DataReader with default DataReaderQos
DataReader* data_reader =
        subscriber->create_datareader(topic, DATAREADER_QOS_DEFAULT);
if (nullptr == data_reader)
{
    // Error
    return;
}

// Get the current QoS or create a new one from scratch
DataReaderQos qos = data_reader->get_qos();

// Modify QoS attributes
// (...)

// Assign the new Qos to the object
data_reader->set_qos(qos);

3.4.4.1.1. Default DataReaderQos

The default DataReaderQos refers to the value returned by the get_default_datareader_qos() member function on the Subscriber instance. The special value DATAREADER_QOS_DEFAULT can be used as QoS argument on create_datareader() or DataReader::set_qos() member functions to indicate that the current default DataReaderQos should be used.

When the system starts, the default DataReaderQos is equivalent to the default constructed value DataReaderQos(). The default DataReaderQos can be modified at any time using the set_default_datareader_qos() member function on the Subscriber instance. Modifying the default DataReaderQos will not affect already existing DataReader instances.

// Get the current QoS or create a new one from scratch
DataReaderQos qos_type1 = subscriber->get_default_datareader_qos();

// Modify QoS attributes
// (...)

// Set as the new default DataReaderQos
if (subscriber->set_default_datareader_qos(qos_type1) != RETCODE_OK)
{
    // Error
    return;
}

// Create a DataReader with the new default DataReaderQos.
DataReader* data_reader_with_qos_type1 =
        subscriber->create_datareader(topic, DATAREADER_QOS_DEFAULT);
if (nullptr == data_reader_with_qos_type1)
{
    // Error
    return;
}

// Get the current QoS or create a new one from scratch
DataReaderQos qos_type2;

// Modify QoS attributes
// (...)

// Set as the new default DataReaderQos
if (subscriber->set_default_datareader_qos(qos_type2) != RETCODE_OK)
{
    // Error
    return;
}

// Create a DataReader with the new default DataReaderQos.
DataReader* data_reader_with_qos_type2 =
        subscriber->create_datareader(topic, DATAREADER_QOS_DEFAULT);
if (nullptr == data_reader_with_qos_type2)
{
    // Error
    return;
}

// Resetting the default DataReaderQos to the original default constructed values
if (subscriber->set_default_datareader_qos(DATAREADER_QOS_DEFAULT)
        != RETCODE_OK)
{
    // Error
    return;
}

// The previous instruction is equivalent to the following
if (subscriber->set_default_datareader_qos(DataReaderQos())
        != RETCODE_OK)
{
    // Error
    return;
}

set_default_datareader_qos() member function also accepts the special value DATAREADER_QOS_DEFAULT as input argument. This will reset the current default DataReaderQos to default constructed value DataReaderQos().

// Create a custom DataReaderQos
DataReaderQos custom_qos;

// Modify QoS attributes
// (...)

// Create a DataWriter with a custom DataReaderQos
DataReader* data_reader = subscriber->create_datareader(topic, custom_qos);
if (nullptr == data_reader)
{
    // Error
    return;
}

// Set the QoS on the DataWriter to the default
if (data_reader->set_qos(DATAREADER_QOS_DEFAULT) != RETCODE_OK)
{
    // Error
    return;
}

// The previous instruction is equivalent to the following:
if (data_reader->set_qos(subscriber->get_default_datareader_qos())
        != RETCODE_OK)
{
    // Error
    return;
}

Note

The value DATAREADER_QOS_DEFAULT has different meaning depending on where it is used: