Setting DomainParticipant QosPolicies

16.3.7 Setting DomainParticipant QosPolicies

A DomainParticipant’s QosPolicies are used to configure discovery, database sizing, threads, information sent to other DomainParticipants, and the behavior of the DomainParticipant when acting as a factory for other Entities.

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

The DDS_DomainParticipantQos structure has the following format:

struct DDS_DomainParticipantQos {

	DDS_UserDataQosPolicy  			user_data; 
	DDS_EntityFactoryQosPolicy 		entity_factory; 
	DDS_WireProtocolQosPolicy 		wire_protocol; 
	DDS_TransportBuiltinQosPolicy		transport_builtin;
	DDS_TransportUnicastQosPolicy		default_unicast;
	DDS_DiscoveryQosPolicy 			discovery; 
	DDS_DomainParticipantResourceLimitsQosPolicy  resource_limits;
	DDS_EventQosPolicy  			event; 
	DDS_ReceiverPoolQosPolicy  		receiver_pool; 
	DDS_DatabaseQosPolicy  			database; 
	DDS_DiscoveryConfigQosPolicy 		discovery_config;
	DDS_PropertyQosPolicy			property;
	DDS_EntityNameQosPolicy			participant_name;
	DDS_TransportMulticastMappingQosPolicy	multicast_mapping;
	DDS_ServiceQosPolicy			service;
	DDS_TypeSupportQosPolicy		type_support;
};

Table 16.5 DomainParticipant QosPolicies summarizes the meaning of each policy (listed alphabetically). For information on why you would want to change a particular QosPolicy, see the section referenced in the table.

Table 16.5 DomainParticipant QosPolicies
QosPolicy	Description
Database	Various settings and resource limits used by Connext to control its internal database. See 44.1 DATABASE QosPolicy (DDS Extension).
Discovery	Configures the mechanism used by Connext to automatically discover and connect with new remote applications. See 44.2 DISCOVERY QosPolicy (DDS Extension).
DiscoveryConfig	Controls the amount of delay in discovering entities in the system and the amount of discovery traffic in the network. See 44.3 DISCOVERY_CONFIG QosPolicy (DDS Extension).
DomainParticipantResourceLimits	Various settings that configure how DomainParticipants allocate and use physical memory for internal resources, including the maximum sizes of various properties. See 44.4 DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension).
EntityFactory	Controls whether or not child entities are created in the enabled state. See 46.2 ENTITYFACTORY QosPolicy.
EntityName	Assigns a name to a DomainParticipant. See 47.11 ENTITY_NAME QosPolicy (DDS Extension).
Event	Configures the DomainParticipant’s internal thread that handles timed events. See 44.5 EVENT QosPolicy (DDS Extension).
Partition	Adds string identifiers that are used for partitioning DomainParticipants that have the same domain ID and domain tag. See 46.5 PARTITION QosPolicy.
Property	Stores name/value(string) pairs that can be used to configure certain parameters of Connext that are not exposed through formal QoS policies. It can also be used to store and propagate application-specific name/value pairs, which can be retrieved by user code during discovery. See 47.19 PROPERTY QosPolicy (DDS Extension) .
ReceiverPool	Configures threads used by Connext to receive and process data from transports (for example, UDP sockets). See 44.6 RECEIVER_POOL QosPolicy (DDS Extension).
Service	Intended for use by RTI infrastructure services. User applications should not modify its value. See 47.23 SERVICE QosPolicy (DDS Extension).
TransportBuiltin	Specifies which built-in transport plugins are used. See 44.7 TRANSPORT_BUILTIN QosPolicy (DDS Extension).
TransportMulticastMapping	Specifies the automatic mapping between a list of topic expressions and multicast address that can be used by a DataReader to receive data for a specific topic. See 44.8 TRANSPORT_MULTICAST_MAPPING QosPolicy (DDS Extension).
TransportUnicast	Specifies a subset of transports and port number that can be used by an Entity to receive data. See 47.28 TRANSPORT_UNICAST QosPolicy (DDS Extension).
TypeSupport	Used to attach application-specific value(s) to a DataWriter or DataReader. These values are passed to the serialization or deserialization routine of the associated data type. See 47.29 TYPESUPPORT QosPolicy (DDS Extension).
UserData	Along with Topic Data QosPolicy and Group Data QosPolicy, used to attach a buffer of bytes to Connext's discovery meta-data. See 47.30 USER_DATA QosPolicy.
WireProtocol	Specifies IDs used by the RTPS wire protocol to create globally unique identifiers. See 44.9 WIRE_PROTOCOL QosPolicy (DDS Extension).

16.3.7.1 Configuring QoS Settings when DomainParticipant is Created

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

Figure 16.4: Creating a DomainParticipant with Default QosPolicies has an example of how to create a DomainParticipant with default QosPolicies by using the special constant, DDS_PARTICIPANT_QOS_DEFAULT, which indicates that the default QoS values for a DomainParticipant should be used. The default DomainParticipant QoS values are configured in the DomainParticipantFactory; you can change them with set_default_participant_qos() or set_default_participant_qos_with_profile() (see 16.2.2 Getting and Setting Default QoS for DomainParticipants). Then any DomainParticipants created with the DomainParticipantFactory 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 DomainParticipant with non-default QoS without using a QoS Profile, see the example code in Figure 16.6: Creating DomainParticipant with Modified QosPolicies (not from profile). It uses the DomainParticipantFactory’s get_default_participant_qos() method to initialize a DDS_ParticipantQos structure. Then, the policies are modified from their default values before the structure is used in the create_participant() method.
You can also create a DomainParticipant and specify its QoS settings via a QoS Profile. To do so, you will call create_participant_with_profile(), as seen in Figure 16.7: Creating DomainParticipant with QoS Profile.
If you want to use a QoS profile, but then make some changes to the QoS before creating the DomainParticipant, call get_participant_qos_from_profile() and create_participant() as seen in Figure 16.8: Getting QoS from Profile, Creating DomainParticipant with Modified QoS Values.

For more information, see 16.3.1 Creating a DomainParticipant 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 "Participant 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.

Figure 16.6: Creating DomainParticipant with Modified QosPolicies (not from profile)

DDS_DomainId_t domain_id = 10;

DDS_DomainParticipantQos participant_qos;
// initialize participant_qos with default values
factory->get_default_participant_qos(participant_qos);
// make QoS changes here
participant_qos.wire_protocol.participant_id = 2;
// Create the participant with modified qos
DDSDomainParticipant* participant = factory->create_participant(
	domain_id, participant_qos, NULL, DDS_STATUS_MASK_NONE);
if (participant == NULL) {
	// ... error
}

Figure 16.7: Creating DomainParticipant with QoS Profile

DDS_DomainId_t domain_id = 10;

// MyDomainParticipantListener is user defined and
// extends DDSDomainParticipantListener
MyDomainParticipantListener* participant_listener
	= new MyDomainParticipantListener(); // or = NULL
// Create the participant
DDSDomainParticipant* participant =
	factory->create_participant_with_profile(domain_id,
	“MyDomainLibrary”, “MyDomainProfile”,		
	participant_listener, DDS_STATUS_MASK_ALL);
if (participant == NULL) {
	// ... error
};

Figure 16.8: Getting QoS from Profile, Creating DomainParticipant with Modified QoS Values

DDS_DomainParticipantQos participant_qos;

// Get DomainParticipant QoS from profile
retcode = factory->get_participant_qos_from_profile( participant_qos,
	“DomainParticipantProfileLibrary”, “DomainParticipantProfile”);
if (retcode != DDS_RETCODE_OK) {
	// handle error
}
// Makes QoS changes here
participant_qos.entity_factory.autoenable_created_entities = DDS_BOOLEAN_FALSE;
// create participant with modified QoS
DDSDomainParticipant* participant = factory->create_participant(domain_id,
	participant_qos, NULL, DDS_STATUS_MASK_NONE);
if (participant == NULL) {
	// handle error
}

16.3.7.2 Comparing QoS Values

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

16.3.7.3 Changing QoS Settings After DomainParticipant Has Been Created

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

Note:

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

Figure 16.9: Changing QoS of Existing Participant (without QoS Profile)

DDS_DomainParticipantQos participant_qos;
// Get current QoS
//participant points to an existing DDSDomainParticipant
if (participant->get_qos(participant_qos) != DDS_RETCODE_OK) {
	// handle error
}
// Make QoS changes
participant_qos.entity_factory.autoenable_created_entities =
	DDS_BOOLEAN_FALSE;
// Set the new QoS
if (participant->set_qos(participant_qos) != DDS_RETCODE_OK ) {
	// handle error
}

Figure 16.10: Changing QoS of Existing Participant with QoS Profile

DDS_DomainParticipantQos participant_qos;

// Get current QoS
//participant points to an existing DDSDomainParticipant
if (participant->get_qos(participant_qos) != DDS_RETCODE_OK) {
	// handle error
}
// Make QoS changes
participant_qos.entity_factory.autoenable_created_entities =
	DDS_BOOLEAN_FALSE;
// Set the new QoS
if (participant->set_qos(participant_qos) != DDS_RETCODE_OK ) {
	// handle error
}

16.3.7.4 Getting and Setting DomainParticipant’s Default QoS Profile and Library

You can get the default QoS profile for the DomainParticipant with the get_default_profile() operation. You can also get the default library for the DomainParticipant, as well as the library that contains the DomainParticipant’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 DomainParticipant’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)

If the default profile/library is not set, the DomainParticipant inherits the default from the DomainParticipantFactory.

set_default_profile() specifies the profile that will be used as the default the next time a default DomainParticipant profile is needed during a call to one of this DomainParticipant’s operations. When calling a DomainParticipant 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.)
set_default_profile() does not set the default QoS for entities created by the DomainParticipant; for this functionality, use the DomainParticipant’s set_default_<entity>_qos_with_profile() operation (you may pass in NULL after having called set_default_profile(), see 16.3.7.5 Getting and Setting Default QoS for Child Entities).
set_default_profile() does not set the default QoS for newly created DomainParticipants; for this functionality, use the DomainParticipantFactory’s set_default_participant_qos_with_profile(), see 16.2.2 Getting and Setting Default QoS for DomainParticipants).

16.3.7.5 Getting and Setting Default QoS for Child Entities

The set_default_<entity>_qos() and set_default_<entity>_qos_with_profile() operations set the default QoS that will be used for newly created entities (where <entity> may be publisher, subscriber, datawriter, datareader, or topic). The new QoS settings will only be used if DDS_<entity>_QOS_DEFAULT is specified as the qos parameter when create_<entity>() is called. For example, for a Publisher, you can use either:

DDS_ReturnCode_t set_default_publisher_qos (

    const DDS_PublisherQos &qos)
DDS_ReturnCode_t set_default_publisher_qos_with_profile (
    const char *library_name, 
    const char *profile_name)

The following operation gets the default QoS that will be used for creating Publishers if DDS_PUBLISHER_QOS_DEFAULT is specified as the ‘qos’ parameter when create_publisher() is called:

DDS_ReturnCode_t get_default_publisher_qos (
    DDS_PublisherQos & qos)

There are similar operations for Subscribers, DataWriters, DataReaders and Topics. These operations, get_default_<entity>_qos(), get the QoS settings that were specified on the last successful call to set_default_<entity>_qos() or set_default_<entity>_qos_with_profile(), or if the call was never made, the default values listed in DDS_<entity>Qos. They may potentially allocate memory depending on the sequences contained in some QoS policies.

Note: It is not safe to set default QoS values for an entity while another thread may be simultaneously getting or setting them, or using the QOS_DEFAULT constant to create the entity.