39.4 Setting Subscriber QosPolicies

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

struct DDS_SubscriberQos {
	DDS_PresentationQosPolicy   presentation; 
	DDS_PartitionQosPolicy      partition;
	DDS_GroupDataQosPolicy      group_data; 
	DDS_EntityFactoryQosPolicy  entity_factory; 
	DDS_ExclusiveAreaQosPolicy  exclusive_area;
	DDS_EntityNameQosPolicy     subscriber_name; 
};

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

Table 39.2 Subscriber QosPolicies summarizes the meaning of each policy. Subscribers have the same set of QosPolicies as Publishers; they are described in detail in 46. Publisher/Subscriber QosPolicies. 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.

39.4.1 Configuring QoS Settings when the Subscriber is Created

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

• In 39.2 Creating Subscribers is an example of how to explicitly create a Subscriber with default QosPolicies. It used the special constant, DDS_SUBSCRIBER_QOS_DEFAULT, which indicates that the default QoS values for a Subscriber should be used. The default Subscriber QosPolicies are configured in the DomainParticipant; you can change them with the DomainParticipant’s set_default_subscriber_qos() or set_default_subscriber_qos_with_profile() operation (see 16.3.7.5 Getting and Setting Default QoS for Child Entities).
• To create a Subscriber with non-default QoS settings, without using a QoS profile, see Figure 39.3: Creating a Subscriber with Non-Default QosPolicies (not from a profile) . It uses the DomainParticipant’s get_default_subscriber_qos() method to initialize a DDS_SubscriberQos structure. Then the policies are modified from their default values before the QoS structure is passed to create_subscriber().
• You can also create a Subscriber and specify its QoS settings via a QoS Profile. To do so, call create_subscriber_with_profile(), as seen in Figure 39.4: Creating a Subscriber with a QoS Profile.
• If you want to use a QoS profile, but then make some changes to the QoS before creating the Subscriber, call get_subscriber_qos_from_profile(), modify the QoS and use the modified QoS structure when calling create_subscriber(), as seen in Figure 39.5: Getting QoS Values from a Profile, Changing QoS Values, Creating a Subscriber with Modified QoS Values.

For more information, see 39.2 Creating Subscribers and 50. Configuring QoS with XML.

DDS_SubscriberQos subscriber_qos;1 Note: In C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C.
// get defaults
if (participant->get_default_subscriber_qos(subscriber_qos) !=
    DDS_RETCODE_OK){
// handle error
}
// make QoS changes here. for example, this changes the ENTITY_FACTORY QoS
subscriber_qos.entity_factory.autoenable_created_entities=DDS_BOOLEAN_FALSE;
// create the subscriber
DDSSubscriber * subscriber = participant->create_subscriber(subscriber_qos,
    NULL, DDS_STATUS_MASK_NONE);
if (subscriber == NULL) {
    // handle error
}

// create the subscriber with QoS profile
DDSSubscriber * subscriber = participant->create_subscriber_with_profile(
    “MySubscriberLibary”, “MySubscriberProfile”, NULL, DDS_STATUS_MASK_NONE);
if (subscriber == NULL) {
    // handle error
}  

DDS_SubscriberQos subscriber_qos;2 Note: In C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C.
// Get subscriber QoS from profile
retcode = factory->get_subscriber_qos_from_profile(subscriber_qos,
    “SubscriberLibrary”, “SubscriberProfile”);
if (retcode != DDS_RETCODE_OK) {
    // handle error
}
// Makes QoS changes here
// for example, this changes the ENTITY_FACTORY QoS
subscriber_qos.entity_factory.autoenable_created_entities = DDS_BOOLEAN_TRUE;
// create the subscriber with modified QoS
DDSPublisher* subscriber = participant->create_subscriber(
    “Example Foo”, type_name, subscriber_qos,
    NULL, DDS_STATUS_MASK_NONE);
if (subscriber == NULL) {
    // handle error
}

39.4.2 Comparing QoS Values

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

39.4.3 Changing QoS Settings After Subscriber Has Been Created

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

• To change an existing Subscriber’s QoS programmatically (that is, without using a QoS profile), get_qos() and set_qos(). See the example code in Figure 39.6: Changing the Qos of an Existing Subscriber . It retrieves the current values by calling the Subscriber’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 Subscriber has been enabled—this restriction is noted in the descriptions of the individual QosPolicies.
• You can also change a Subscriber’s (and all other Entities’) QoS by using a QoS Profile and calling set_qos_with_profile(). For an example, see Figure 39.7: Changing the QoS of an Existing Subscriber with a QoS Profile. For more information, see 50. Configuring QoS with XML.

DDS_SubscriberQos subscriber_qos;
// Get current QoS. subscriber points to an existing DDSSubscriber.
if (subscriber->get_qos(subscriber_qos) != DDS_RETCODE_OK) {
    // handle error
}
// make changes
// New entity_factory autoenable_created_entities will be true
subscriber_qos.entity_factory.autoenable_created_entities =
    DDS_BOOLEAN_TRUE;
// Set the new QoS
if (subscriber->set_qos(subscriber_qos) != DDS_RETCODE_OK ) {
    // handle error
}

retcode = subscriber->set_qos_with_profile(
         “SubscriberProfileLibrary”,”SubscriberProfile”);
if (retcode != DDS_RETCODE_OK) {
    // handle error
}

39.4.4 Getting and Settings Subscriber’s Default QoS Profile and Library

You can retrieve the default QoS profile used to create Subscribers with the get_default_profile() operation. You can also get the default library for Subscribers, as well as the library that contains the Subscriber’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 50. 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 Subscriber’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 Subscriber library/profile is needed during a call to one of this Subscriber’s operations.

When calling a Subscriber 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 Subscriber inherits the default from the DomainParticipant.

set_default_profile() does not set the default QoS for DataReaders created by the Subscriber; for this functionality, use the Subscriber’s set_default_datareader_qos_with_profile(), see 39.4.5 Getting and Setting Default QoS for DataReaders (you may pass in NULL after having called the Subscriber’s set_default_profile()).

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

39.4.5 Getting and Setting Default QoS for DataReaders

These operations set the default QoS that will be used for new DataReaders if create_datareader() is called with DDS_DATAREADER_QOS_DEFAULT as the ‘qos’ parameter:

DDS_ReturnCode_t set_default_datareader_qos (const DDS_DataReaderQos &qos)

DDS_ReturnCode_t set_default_datareader_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 DataReaders if create_datareader() is called with DDS_DATAREADER_QOS_DEFAULT as the ‘qos’ parameter:

DDS_ReturnCode_t get_default_datareader_qos (DDS_DataReaderQos & qos)   

The above operation gets the QoS settings that were specified on the last successful call to set_default_datareader_qos() or set_default_datareader_qos_with_profile(), or if the call was never made, the default values listed in DDS_DataReaderQos.

Note: It is not safe to set the default DataReader QoS values while another thread may be simultaneously calling get_default_datareader_qos(), set_default_datareader_qos() or create_datareader() with DDS_DATAREADER_QOS_DEFAULT as the qos parameter. It is also not safe to get the default DataReader QoS values while another thread may be simultaneously calling set_default_datareader_qos().

39.4.6 Subscriber QoS-Related Operations

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

This method is provided as a convenience for setting the values in a DataReaderQos structure before using that structure to create a DataReader. As explained in 18.1.3 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 DataReaderQos structure every time you need to create a DataReader for a Topic, you can use the Subscriber’s copy_from_topic_qos() operation to “import” the Topic’s QosPolicies into a DataReaderQos structure. This operation copies the relevant policies in the TopicQos to the corresponding policies in the DataReaderQos.

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

• Copying a Subscriber’s QoS

In the C API users should use the DDS_SubscriberQos_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# 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_SubscriberQos_finalize() operation frees the memory used by sequences but otherwise leaves the QoS unchanged. C users should call finalize() on all DDS_SubscriberQos objects before they are freed, or for QoS structures allocated on the stack, before they go out of scope. In C++, C# and Java, the memory used by sequences is freed in the destructor.