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.
QosPolicy |
Description |
Whether or not new entities created from this entity will start out as ‘enabled.’ |
|
Assigns a name and role_name to a Subscriber. |
|
Whether or not the entity uses a multi-thread safe region with deadlock protection. |
|
A place to pass group-level information among applications. Usage is application-dependent. |
|
Set of strings that introduces a logical partition among Topics visible by Publisher/Subscriber. |
|
The order in which instance changes are presented to the Subscriber. By default, no order is used. |
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 }
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.
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 }
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.
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().
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 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 Setting DataReader QosPolicies).
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++/CLI, C# and Java, a copy constructor is provided to take care of sequences automatically.
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++/CLI, C# and Java, the memory used by sequences is freed in the destructor.
© 2018 RTI