31.15 Setting DataWriter QosPolicies

The DataWriter’s QosPolicies control its resources and behavior.

The DDS_DataWriterQos structure has the following format:

DDS_DataWriterQos struct  {

	DDS_DurabilityQosPolicy			durability; 

	DDS_DurabilityServiceQosPolicy		durability_service; 

	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_TransportPriorityQosPolicy  	transport_priority; 

	DDS_LifespanQosPolicy  			lifespan; 

	DDS_UserDataQosPolicy  			user_data; 

	DDS_OwnershipQosPolicy  		ownership; 

	DDS_OwnershipStrengthQosPolicy  	ownership_strength; 

	DDS_WriterDataLifecycleQosPolicy  	writer_data_lifecycle;

	DDS_DataRepresentationQosPolicy         representation;

	DDS_DataTagQosPolicy                    data_tags;

	// extensions to the DDS standard: 

	DDS_DataWriterResourceLimitsQosPolicy	writer_resource_limits; 

	DDS_DataWriterProtocolQosPolicy  	protocol; 

	DDS_TransportSelectionQosPolicy  	transport_selection;

	DDS_TransportUnicastQosPolicy		unicast; 

	DDS_PublishModeQosPolicy		publish_mode;

	DDS_PropertyQosPolicy			property;

	DDS_ServiceQosPolicy			service;

	DDS_BatchQosPolicy			batch;

	DDS_MultiChannelQosPolicy		multi_channel;

	DDS_AvailabilityQosPolicy		availability;

	DDS_EntityNameQosPolicy			publication_name;

	DDS_TopicQueryDispatchQosPolicy		topic_query_dispatch;

        DDS_DataWriterTransferModeQosPolicy     transfer_mode;

	DDS_TypeSupportQosPolicy		type_support;

} DDS_DataWriterQos;

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

Table 31.16 DataWriter QosPolicies 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.

Many of the DataWriter QosPolicies also apply to DataReaders (see 40. DataReaders). For a DataWriter to communicate with a DataReader, their QosPolicies must be compatible. Generally, for the QosPolicies that apply both to the DataWriter and the DataReader, the setting in the DataWriter is considered an “offer” and the setting in the DataReader is a “request.” Compatibility means that what is offered by the DataWriter equals or surpasses what is requested by the DataReader. Each policy’s description includes compatibility restrictions. For more information on compatibility, see 42.1 QoS Requested vs. Offered Compatibility—the RxO Property.

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

31.15.1 Configuring QoS Settings when the DataWriter is Created

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

• In Figure 31.1: Creating a DataWriter with Default QosPolicies and a Listener , there is an example of how to create a DataWriter with default QosPolicies by using the special constant, DDS_DATAWRITER_QOS_DEFAULT, which indicates that the default QoS values for a DataWriter should be used. The default DataWriter QoS values are configured in the Publisher or DomainParticipant; you can change them with set_default_datawriter_qos() or set_default_datawriter_qos_with_profile(). Then any DataWriters created with the Publisher will use the new default values. As described in 49. Configuring Qos Programmatically, this is a general pattern that applies to the construction of all Entities.
• To create a DataWriter with non-default QoS without using a QoS Profile, see the example code in Figure 31.8: Creating a DataWriter with Modified QosPolicies (not from a profile). It uses the Publisher’s get_default_writer_qos() method to initialize a DDS_DataWriterQos structure. Then the policies are modified from their default values before the structure is used in the create_datawriter() method.
• You can also create a DataWriter and specify its QoS settings via a QoS Profile. To do so, you will call create_datawriter_with_profile(), as seen in Figure 31.9: Creating a DataWriter with a QoS Profile.
• If you want to use a QoS profile, but then make some changes to the QoS before creating the DataWriter, call get_datawriter_qos_from_profile() and create_datawriter() as seen in Figure 31.10: Getting QoS Values from a Profile, Changing QoS Values, Creating a DataWriter with Modified QoS Values.

For more information, see 31.1 Creating DataWriters and 50. Configuring QoS with XML.

Notes:

• The examples in this section use the Traditional C++ API; for examples in the Modern C++ API, see the sections "DataWriter Use Cases," "Qos Use Cases," and "Qos Provider Use Cases" in the API Reference HTML documentation, under "Programming How-To's."
• In C, you must initialize the QoS structures before they are used, see 42.2 Special QosPolicy Handling Considerations for C.

DDS_DataWriterQos writer_qos;

// initialize writer_qos with default values
publisher->get_default_datawriter_qos(writer_qos);
// make QoS changes
writer_qos.history.depth = 5;
// Create the writer with modified qos
DDSDataWriter * writer = publisher->create_datawriter(
    topic, writer_qos, NULL, DDS_STATUS_MASK_NONE);
if (writer == NULL) {
    // ... error
}
// narrow it for your specific data type
FooDataWriter* foo_writer = FooDataWriter::narrow(writer);

// Create the datawriter

DDSDataWriter * writer =
    publisher->create_datawriter_with_profile(
        topic, “MyWriterLibrary”, “MyWriterProfile”,
        NULL, DDS_STATUS_MASK_NONE);
if (writer == NULL) {
    // ... error
};
// narrow it for your specific data type
FooDataWriter* foo_writer = FooDataWriter::narrow(writer);

DDS_DataWriterQos writer_qos;

// Get writer QoS from profile
retcode = factory->get_datawriter_qos_from_profile(
    writer_qos, “WriterProfileLibrary”, “WriterProfile”);
if (retcode != DDS_RETCODE_OK) {
    // handle error
}
// Makes QoS changes
writer_qos.history.depth = 5;
DDSDataWriter * writer = publisher->create_datawriter(
    topic, writer_qos, NULL, DDS_STATUS_MASK_NONE);
if (participant == NULL) {
    // handle error
}

31.15.2 Comparing QoS Values

The equals() operation compares two DataWriter’s DDS_DataWriterQoS structures for equality. It takes two parameters for the two DataWriter’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.

31.15.3 Changing QoS Settings After the DataWriter Has Been Created

There are two ways to change an existing DataWriter’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 31.11: Changing the QoS of an Existing DataWriter (without a QoS Profile). It retrieves the current values by calling the DataWriter’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 DataWriter has been enabled—this restriction is noted in the descriptions of the individual QosPolicies.
• You can also change a DataWriter’s (and all other Entities’) QoS by using a QoS Profile and calling set_qos_with_profile(). For an example, see Figure 31.12: Changing the QoS of an Existing DataWriter with a QoS Profile . For more information, see 50. Configuring QoS with XML.

DDS_DataWriterQos writer_qos;

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

retcode = writer->set_qos_with_profile(

    “WriterProfileLibrary”,”WriterProfile”);
if (retcode != DDS_RETCODE_OK) {
    // handle error
}

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

Several DataWriter QosPolicies can also be found in the QosPolicies for Topics (see 18.1.3 Setting Topic QosPolicies). The QosPolicies set in the Topic do not directly affect the DataWriters (or DataReaders) 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 DataWriters and DataReaders 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 QosPolicies. Connext does not check to see if the actual policies set for a DataWriter 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 DataWriter. The most straightforward way is to get the values of policies directly from the Topic and use them in the policies for the DataWriter, as shown in Figure 31.13: Copying Selected QoS from a Topic when Creating a DataWriter.

DDS_DataWriterQos writer_qos;

DDS_TopicQos topic_qos;
// topic and publisher already created
// get current QoS for the topic, default QoS for the writer
if (topic->get_qos(topic_qos) != DDS_RETCODE_OK) {
    // handle error
}
if (publisher->get_default_datawriter_qos(writer_qos) 
    != DDS_RETCODE_OK) {
    // handle error
}
// Copy specific policies from topic QoS to writer QoS
writer_qos.deadline = topic_qos.deadline;
writer_qos.reliability = topic_qos.reliability;
// Create the DataWriter with the modified QoS
DDSDataWriter* writer = publisher->create_datawriter(topic,
   writer_qos,NULL, DDS_STATUS_MASK_NONE);

DDS_DataWriterQos writer_qos;
DDS_TopicQos topic_qos;
// topic, publisher, writer_listener already created
if (topic->get_qos(topic_qos) != DDS_RETCODE_OK) {
// handle error
}
if (publisher->get_default_datawriter_qos(writer_qos) 
    != DDS_RETCODE_OK)
{
    // handle error
}
// copy relevant QoS from topic into writer’s qos
publisher->copy_from_topic_qos(writer_qos, topic_qos);
// Optionally, modify policies as desired
writer_qos.deadline.duration.sec = 1;
writer_qos.deadline.duration.nanosec = 0;
// Create the DataWriter with the modified QoS
DDSDataWriter* writer = publisher->create_datawriter(topic,
    writer_qos, writer_listener, DDS_STATUS_MASK_ALL);

In another design pattern, you may want to start with the default QoS values for a DataWriter and override them with the QoS values of the Topic. Figure 31.15: Combining Default Topic and DataWriter QoS (Option 1) gives an example of how to do this.

Because this is a common pattern, Connext provides a special macro, DDS_DATAWRITER_QOS_USE_TOPIC_QOS, that can be used to indicate that the DataWriter should be created with the set of QoS values that results from modifying the default DataWriter QosPolicies with the QoS values specified by the Topic. Figure 31.16: Combining Default Topic and DataWriter QoS (Option 2) shows how the macro is used.

The code fragments shown in Figure 31.15: Combining Default Topic and DataWriter QoS (Option 1) and Figure 31.16: Combining Default Topic and DataWriter QoS (Option 2) result in identical QoS settings for the created DataWriter.

Note:

• In C, you must initialize the QoS structures before they are used, see 42.2 Special QosPolicy Handling Considerations for C.

DDS_DataWriterQos writer_qos;

DDS_TopicQos topic_qos;
// topic, publisher, writer_listener already created
if (topic->get_qos(topic_qos) != DDS_RETCODE_OK) {
// handle error
}
if (publisher->get_default_datawriter_qos(writer_qos) 
    != DDS_RETCODE_OK) {
// handle error
}
if (publisher->copy_from_topic_qos(writer_qos, topic_qos) 
    != DDS_RETCODE_OK) {
// handle error
}
// Create the DataWriter with the combined QoS
DDSDataWriter* writer = 
    publisher->create_datawriter(topic, writer_qos,
    writer_listener,DDS_STATUS_MASK_ALL);

// topic, publisher, writer_listener already created

DDSDataWriter* writer = publisher->create_datawriter (topic,
DDS_DATAWRITER_QOS_USE_TOPIC_QOS,
writer_listener, DDS_STATUS_MASK_ALL);

For more information on the general use and manipulation of QosPolicies, see 49. Configuring Qos Programmatically.