Setting Publisher QosPolicies

A Publisher’s QosPolicies control its behavior. Think of the policies as the configuration and behavior ‘properties’ of the Publisher. The DDS_PublisherQos structure has the following format:

DDS_PublisherQos struct  {
    DDS_PresentationQosPolicy  presentation; 
    DDS_PartitionQosPolicy  partition; 
    DDS_GroupDataQosPolicy  group_data; 
    DDS_EntityFactoryQosPolicy  entity_factory;
    DDS_AsynchronousPublisherQosPolicy  asynchronous_publisher;
    DDS_ExclusiveAreaQosPolicy  exclusive_area; 
    DDS_EntityNameQosPolicy  publisher_name;
} DDS_PublisherQos;

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

Publisher 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 for each policy.

Configuring QoS Settings when the Publisher is Created

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

• In Figure 2 we saw an example of how to explicitly create a Publisher with default QosPolicies. It used the special constant, DDS_PUBLISHER_QOS_DEFAULT, which indicates that the default QoS values for a Publisher should be used. Default Publisher QosPolicies are configured in the DomainParticipant; you can change them with the DomainParticipant’s set_default_publisher_qos() or set_default_publisher_qos_with_profile() operation (see Getting and Setting Default QoS for Child Entities).
• To create a Publisher with non-default QoS settings, without using a QoS profile, see Figure 3. It uses the DomainParticipant’s get_default_publisher_qos() method to initialize a DDS_PublisherQos structure. Then the policies are modified from their default values before the QoS structure is passed to create_publisher().
• You can also create a Publisher and specify its QoS settings via a QoS Profile. To do so, call create_publisher_with_profile(), as seen in Figure 4.
• If you want to use a QoS profile, but then make some changes to the QoS before creating the Publisher, call the DomainParticipantFactory’s get_publisher_qos_from_profile(), modify the QoS and use the modified QoS structure when calling create_publisher(), as seen in Figure 5.

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

DDS_PublisherQos publisher_qos;1For the C API, you need to use DDS_PublisherQos_INITIALIZER or DDS_PublisherQos_initialize(). See
Special QosPolicy Handling Considerations for C (Section on page 1)
// get defaults
if (participant->get_default_publisher_qos(publisher_qos) != DDS_RETCODE_OK){
    // handle error
}
// make QoS changes here
// for example, this changes the ENTITY_FACTORY QoS
publisher_qos.entity_factory.autoenable_created_entities = DDS_BOOLEAN_FALSE;
    // create the publisher
    DDSPublisher* publisher = participant->create_publisher(publisher_qos,
        NULL, DDS_STATUS_MASK_NONE);
if (publisher == NULL) {
    // handle error
}

// create the publisher with QoS profile
DDSPublisher* publisher = participant->create_publisher_with_profile(
    “MyPublisherLibary”, “MyPublisherProfile”,
    NULL, DDS_STATUS_MASK_NONE);
if (publisher == NULL) {
    // handle error
}

DDS_PublisherQos publisher_qos;2For the C API, you need to use DDS_PublisherQos_INITIALIZER or DDS_PublisherQos_initialize(). See
Special QosPolicy Handling Considerations for C (Section on page 1)
// Get publisher QoS from profile
retcode = factory->get_publisher_qos_from_profile(publisher_qos,
    “PublisherLibrary”, “PublisherProfile”);
if (retcode != DDS_RETCODE_OK) {
    // handle error
}
// Makes QoS changes here
// New entity_factory autoenable_created_entities will be true
publisher_qos.entity_factory.autoenable_created_entities = DDS_BOOLEAN_TRUE;
// create the publisher with modified QoS
DDSPublisher* publisher = participant->create_publisher(
    “Example Foo”, type_name, publisher_qos,
    NULL, DDS_STATUS_MASK_NONE);
if (publisher == NULL) {
    // handle error
}

Comparing QoS Values

The equals() operation compares two Publisher’s DDS_PublisherQoS structures for equality. It takes two parameters for the two Publisher’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 the Publisher Has Been Created

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

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

DDS_PublisherQos publisher_qos;3For the C API, you need to use DDS_PublisherQos_INITIALIZER or DDS_PublisherQos_initialize(). See
Special QosPolicy Handling Considerations for C (Section on page 1)
// Get current QoS. publisher points to an existing DDSPublisher.
if (publisher->get_qos(publisher_qos) != DDS_RETCODE_OK) {
    // handle error
}
// make changes
// New entity_factory autoenable_created_entities will be true
publisher_qos.entity_factory.autoenable_created_entities =DDS_BOOLEAN_TRUE;
// Set the new QoS
if (publisher->set_qos(publisher_qos) != DDS_RETCODE_OK ) {
    // handle error
}

retcode = publisher->set_qos_with_profile(
    “PublisherProfileLibrary”,”PublisherProfile”);
if (retcode != DDS_RETCODE_OK) {
    // handle error
}

Getting and Setting the Publisher’s Default QoS Profile and Library

You can retrieve the default QoS profile used to create Publishers with the get_default_profile() operation.

You can also get the default library for Publishers, as well as the library that contains the Publisher’s default profile (these are not necessarily the same library); these operations are called get_default_library() and get_default_library_profile(), respectively. These operations are for informational purposes only (that is, you do not need to use them as a precursor to setting a library or profile.) For more information, see Configuring QoS with XML.

virtual const char *  get_default_library ()
const char *  get_default_profile ()
const char *  get_default_profile_library ()

There are also operations for setting the Publisher’s default library and profile:

DDS_ReturnCode_t set_default_library (const char *  library_name) 
DDS_ReturnCode_t set_default_profile (const char *  library_name, 
    const char *  profile_name) 

These operations only affect which library/profile will be used as the default the next time a default Publisher library/profile is needed during a call to one of this Publisher’s operations.

When calling a Publisher operation that requires a profile_name parameter, you can use NULL to refer to the default profile. (This same information applies to setting a default library.) If the default library/profile is not set, the Publisher inherits the default from the DomainParticipant.

set_default_profile() does not set the default QoS for DataWriters created by the Publisher; for this functionality, use the Publisher’s set_default_datawriter_qos_with_profile(), see Getting and Setting Default QoS for DataWriters (you may pass in NULL aftercalling the Publisher’s set_default_profile()).

set_default_profile() does not set the default QoS for newly created Publishers; for this functionality, use the DomainParticipant’s set_default_publisher_qos_with_profile() operation, see Getting and Setting Default QoS for Child Entities.

Getting and Setting Default QoS for DataWriters

These operations set the default QoS that will be used for new DataWriters if create_datawriter() is called with DDS_DATAWRITER_QOS_DEFAULT as the qos parameter:

DDS_ReturnCode_t set_default_datawriter_qos (const DDS_DataWriterQos &qos)
DDS_ReturnCode_t set_default_datawriter_qos_with_profile (
   const char *library_name, 
   const char *profile_name)

The above operations may potentially allocate memory, depending on the sequences contained in some QoS policies.

To get the default QoS that will be used for creating DataWriters if create_datawriter() is called with DDS_PARTICIPANT_QOS_DEFAULT as the qos parameter:

DDS_ReturnCode_t get_default_datawriter_qos (DDS_DataWriterQos & qos)   

This operation gets the QoS settings that were specified on the last successful call to set_default_datawriter_qos() or set_default_datawriter_qos_with_profile(), or if the call was never made, the default values listed in DDS_DataWriterQos.

Note: It is not safe to set the default DataWriter QoS values while another thread may be simultaneously calling get_default_datawriter_qos(), set_default_datawriter_qos(), or create_datawriter() with DDS_DATAWRITER_QOS_DEFAULT as the qos parameter. It is also not safe to get the default DataWriter QoS values while another thread may be simultaneously calling set_default_datawriter_qos().

Other Publisher QoS-Related Operations

• Copying a Topic’s QoS into a DataWriter’s QoS

This method is provided as a convenience for setting the values in a DataWriterQos structure before using that structure to create a DataWriter. As explained in Setting Topic QosPolicies, most of the policies in a TopicQos structure do not apply directly to the Topic itself, but to the associated DataWriters and DataReaders of that Topic. The TopicQos serves as a single container where the values of QosPolicies that must be set compatibly across matching DataWriters and DataReaders can be stored.

Thus instead of setting the values of the individual QosPolicies that make up a DataWriterQos structure every time you need to create a DataWriter for a Topic, you can use the Publisher’s copy_from_topic_qos() operation to “import” the Topic’s QosPolicies into a DataWriterQos structure. This operation copies the relevant policies in the TopicQos to the corresponding policies in the DataWriterQos.

This copy operation will often be used in combination with the Publisher’s get_default_datawriter_qos() and the Topic’s get_qos() operations. The Topic’s QoS values are merged on top of the Publisher’s default DataWriter QosPolicies with the result used to create a new DataWriter, or to set the QoS of an existing one (see Setting DataWriter QosPolicies).

• Copying a Publisher’s QoS

C API users should use the DDS_PublisherQos_copy() operation rather than using structure assignment when copying between two QoS structures. The copy() operation will perform a deep copy so that policies that allocate heap memory such as sequences are copied correctly. In C++, C++/CLI, C# and Java, a copy constructor is provided to take care of sequences automatically.

• Clearing QoS-Related Memory

Some QosPolicies contain sequences that allocate memory dynamically as they grow or shrink. The C API’s DDS_PublisherQos_finalize() operation frees the memory used by sequences but otherwise leaves the QoS unchanged. C API users should call finalize() on all DDS_PublisherQos objects before they are freed, or for QoS structures allocated on the stack, before they go out of scope. In C++, C++/CLI, C# and Java, the memory used by sequences is freed in the destructor.

© 2017 RTI