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 Restricted Operations in Listener Callbacks.

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

Subscriber QosPolicies

QosPolicy

Description

ENTITYFACTORY QosPolicy

Whether or not new entities created from this entity will start out as ‘enabled.’

ENTITY_NAME QosPolicy (DDS Extension)

Assigns a name and role_name to a Subscriber.

EXCLUSIVE_AREA QosPolicy (DDS Extension)

Whether or not the entity uses a multi-thread safe region with deadlock protection.

GROUP_DATA QosPolicy

A place to pass group-level information among applications. Usage is application-dependent.

PARTITION QosPolicy

Set of strings that introduces a logical partition among Topics visible by Publisher/Subscriber.

PRESENTATION QosPolicy

The order in which instance changes are presented to the Subscriber. By default, no order is used.

Configuring QoS Settings when the Subscriber is Created

As described in 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).

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

Figure: Creating a Subscriber with Non-Default QosPolicies (not from a profile)

DDS_SubscriberQos subscriber_qos;1Note: 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
}

Figure: Creating a Subscriber with a QoS Profile

// 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
}  

Figure: Getting QoS Values from a Profile, Changing QoS Values, Creating a Subscriber with Modified QoS Values

DDS_SubscriberQos subscriber_qos;2Note: 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
}

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.

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.

Figure: Changing the Qos of an Existing Subscriber

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
}

Figure: Changing the QoS of an Existing Subscriber with a QoS Profile

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

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 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 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 Getting and Setting Default QoS for Child Entities.

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().

Subscriber QoS-Related Operations

© 2018 RTI