Setting DataReader QosPolicies

A DataReader’s QosPolicies control its behavior. Think of QosPolicies as the ‘properties’ for the DataReader. The DDS_DataReaderQos structure has the following format:

struct DDS_DataReaderQos {
	DDS_DurabilityQosPolicy               durability; 
	DDS_DeadlineQosPolicy                 deadline;
	DDS_LatencyBudgetQosPolicy            latency_budget;
	DDS_LivelinessQosPolicy               liveliness; 
	DDS_ReliabilityQosPolicy              reliability; 
	DDS_DestinationOrderQosPolicy         destination_order; 
	DDS_HistoryQosPolicy  		      history; 
	DDS_ResourceLimitsQosPolicy  	      resource_limits; 
	DDS_UserDataQosPolicy  		      user_data; 
	DDS_TimeBasedFilterQosPolicy 	      time_based_filter;
	DDS_ReaderDataLifecycleQosPolicy      reader_data_lifecycle;
	DDS_TransportPriorityQosPolicy        transport_priority;
	DDS_TypeConsistencyEnforcementQosPolicy type_consistency;
	// Extensions to the DDS standard:
	DDS_DataReaderResourceLimitsQosPolicy reader_resource_limits;
	DDS_DataReaderProtocolQosPolicy       protocol; 
	DDS_TransportSelectionQosPolicy       transport_selection;
	DDS_TransportUnicastQosPolicy         unicast; 
	DDS_TransportMulticastQosPolicy       multicast; 
	DDS_PropertyQosPolicy                 property; 
	DDS_ServiceQosPolicy                  service;
	DDS_AvailabilityQosPolicy             availability;
	DDS_EntityNameQosPolicy               subscription_name;
	DDS_TypeSupportQosPolicy              type_support; 
};

Note: set_qos() cannot always be used within a listener callback, see Restricted Operations in Listener Callbacks.

Table 16 summarizes the meaning of each policy. (They appear alphabetically in the table.) For information on why you would want to change a particular QosPolicy, see the referenced section. For defaults and valid ranges, please refer to the API Reference HTML documentation.

For a DataReader to communicate with a DataWriter, their corresponding QosPolicies must be compatible. For QosPolicies that apply both to the DataWriter and the DataReader, the setting in the DataWriter is considered what the DataWriter “offers” and the setting in the DataReader is what the DataReader “requests.” Compatibility means that what is offered by the DataWriter equals or surpasses what is requested by the DataReader. See QoS Requested vs. Offered Compatibility—the RxO Property.

Some of the policies may be changed after the DataReader has been created. This allows the application to modify the behavior of the DataReader while it is in use. To modify the QoS of an existing DataReader, use the get_qos() and set_qos() operations on the DataReader. This is a general pattern for all Entities, described in more detail in Changing the QoS for an Existing Entity.

Configuring QoS Settings when the DataReader is Created

As described in Creating DataReaders, there are different ways to create a DataReader, depending on how you want to specify its QoS (with or without a QoS Profile).

In Creating a DataReader with Default QosPolicies , we saw an example of how to create a DataReader with default QosPolicies by using the special constant, DDS_DATAREADER_QOS_DEFAULT, which indicates that the default QoS values for a DataReader should be used. The default DataReader QoS values are configured in the Publisher or DomainParticipant; you can change them with set_default_datareader_qos() or set_default_datareader_qos_with_profile(). Then any DataReaders created with the Subscriber will use the new default values. As described in Getting, Setting, and Comparing QosPolicies, this is a general pattern that applies to the construction of all Entities.

To create a DataReader with non-default QoS without using a QoS Profile, see the example code in Figure 11. It uses the Publisher’s get_default_reader_qos() method to initialize a DDS_DataReaderQos structure. Then, the policies are modified from their default values before the structure is used in the create_datareader() method.

You can also create a DataReader and specify its QoS settings via a QoS Profile. To do so, you will call create_datareader_with_profile(), as seen in Figure 12.

If you want to use a QoS profile, but then make some changes to the QoS before creating the DataReader, call get_datareader_qos_from_profile() and create_datareader() as seen in Figure 13.

For more information, see Creating DataReaders and Configuring QoS with XML.

DDS_DataReaderQos reader_qos;2Note: In C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C.
// initialize reader_qos with default values
subscriber->get_default_datareader_qos(reader_qos);
// make QoS changes here
reader_qos.history.depth = 5;
// Create the reader with modified qos
DDSDataReader * reader = subscriber->create_datareader(
    topic, reader_qos, NULL, DDS_STATUS_MASK_NONE);
if (reader == NULL) {
    // ... error
}
// narrow it for your specific data type
FooDataReader* foo_reader = FooDataReader::narrow(reader);

// Create the datareader
DDSDataReader * reader = 
	subscriber->create_datareader_with_profile(
		topic, “MyReaderLibrary”, “MyReaderProfile”, 
		NULL, DDS_STATUS_MASK_NONE);
if (reader == NULL) {
    // ... error
};
// narrow it for your specific data type
FooDataReader* foo_reader = FooDataReader::narrow(reader);

DDS_DataReaderQos reader_qos;3Note: In C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C.
// Get reader QoS from profile
retcode = factory->get_datareader_qos_from_profile(reader_qos,
    “ReaderProfileLibrary”, “ReaderProfile”);
if (retcode != DDS_RETCODE_OK) {
    // handle error
}
// Makes QoS changes here
reader_qos.history.depth = 5;
DDSDataReader * reader = subscriber->create_datareader(topic, reader_qos,
    NULL, DDS_STATUS_MASK_NONE);
if (reader == NULL) {
    // handle error
}

Comparing QoS Values

The equals() operation compares two DataReader’s DDS_DataWriterQoS structures for equality. It takes two parameters for the two DataReader’s QoS structures to be compared, then returns TRUE is they are equal (all values are the same) or FALSE if they are not equal.

Changing QoS Settings After DataReader Has Been Created

There are 2 ways to change an existing DataReader’s QoS after it is has been created—again depending on whether or not you are using a QoS Profile.

• To change QoS programmatically (that is, without using a QoS Profile), use get_qos() and set_qos(). See the example code in Figure 14. It retrieves the current values by calling the DataReader’s get_qos() operation. Then it modifies the value and calls set_qos() to apply the new value. Note, however, that some QosPolicies cannot be changed after the DataReader has been enabled—this restriction is noted in the descriptions of the individual QosPolicies.
• You can also change a DataReader’s (and all other Entities’) QoS by using a QoS Profile and calling set_qos_with_profile(). For an example, see Figure 15. For more information, see Configuring QoS with XML.

Figure 14 Changing the QoS of an Existing DataReader (without a QoS Profile)

// Get current QoS
if (datareader->get_qos(reader_qos) != DDS_RETCODE_OK) {
    // handle error
}
// Makes QoS changes here
reader_qos.history.depth = 5;
// Set the new QoS
if (datareader->set_qos(reader_qos) != DDS_RETCODE_OK ) {
    // handle error
}

Figure 15 Changing the QoS of an Existing DataReader with a QoS Profile

retcode = datareader->set_qos_with_profile(
    “ReaderProfileLibrary”,”ReaderProfile”);
if (retcode != DDS_RETCODE_OK) {
    // handle error
}

Using a Topic’s QoS to Initialize a DataWriter’s QoS

Several DataReader QosPolicies can also be found in the QosPolicies for Topics (see Setting Topic QosPolicies). The QosPolicies set in the Topic do not directly affect the DataReaders (or DataWriters) that use that Topic. In many ways, some QosPolicies are a Topic-level concept, even though the DDS standard allows you to set different values for those policies for different DataReaders and DataWriters of the same Topic. Thus, the policies in the DDS_TopicQos structure exist as a way to help centralize and annotate the intended or suggested values of those QoSs. Connext DDS does not check to see if the actual policies set for a DataReader is aligned with those set in the Topic to which it is bound.

There are many ways to use the QosPolicies’ values set in the Topic when setting the QosPolicies’ values in a DataReader. The most straight forward way is to get the values of policies directly from the Topic and use them in the policies for the DataReader. Figure 21 shows an example of how to this for a DataWriter; the pattern applies to DataReaders as well.

The Subscriber’s copy_from_topic_qos() operation can be used to copy all the common policies from the Topic QoS to a DataReaderQoS, as illustrated in Figure 22 for DataWriters.

The special macro, DDS_DATAREADER_QOS_USE_TOPIC_QOS, can be used to indicate that the DataReader should be created with the QoS that results from modifying the default DataReader QoS with the values specified by the Topic. See Figure 23 and Figure 24 for examples involving DataWriters. The same pattern applies to DataReaders. For more information on the use and manipulation of QoS, see Getting, Setting, and Comparing QosPolicies.

© 2015 RTI