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 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; };
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.
QosPolicy |
Description |
Database |
Various settings and resource limits used by Connext DDS to control its internal database. See DATABASE QosPolicy (DDS Extension). |
Discovery |
Configures the mechanism used by Connext DDS to automatically discover and connect with new remote applications. See 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 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 DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension). |
EntityFactory |
Controls whether or not child entities are created in the enabled state. See ENTITYFACTORY QosPolicy. |
EntityName |
Assigns a name to a DomainParticipant. See ENTITY_NAME QosPolicy (DDS Extension). |
Event |
Configures the DomainParticipant’s internal thread that handles timed events. See EVENT QosPolicy (DDS Extension). |
Property |
Stores name/value(string) pairs that can be used to configure certain parameters of Connext DDS 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 PROPERTY QosPolicy (DDS Extension) . |
ReceiverPool |
Configures threads used by Connext DDS to receive and process data from transports (for example, UDP sockets). See RECEIVER_POOL QosPolicy (DDS Extension). |
Service |
Intended for use by RTI infrastructure services. User applications should not modify its value. See SERVICE QosPolicy (DDS Extension). |
TransportBuiltin |
Specifies which built-in transport plugins are used. See 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 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 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 TYPESUPPORT QosPolicy (DDS Extension). |
UserData |
Along with Topic Data QosPolicy and Group Data QosPolicy, used to attach a buffer of bytes to Connext DDS's discovery meta-data. See USER_DATA QosPolicy. |
WireProtocol |
Specifies IDs used by the RTPS wire protocol to create globally unique identifiers. See WIRE_PROTOCOL QosPolicy (DDS Extension). |
As described in 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).
For more information, see Creating a DomainParticipant and Configuring QoS with XML.
Figure 6 Creating DomainParticipant with Modified QosPolicies (not from profile)
DDS_DomainId_t domain_id = 10; DDS_DomainParticipantQos participant_qos;1In C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C. // 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 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 8 Getting QoS from Profile, Creating DomainParticipant with Modified QoS Values
DDS_DomainParticipantQos participant_qos;2In C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C. // 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 }
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.
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.
Figure 9 Changing QoS of Existing Participant (without QoS Profile)
DDS_DomainParticipantQos participant_qos;3In C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C. // 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 10 Changing QoS of Existing Participant with QoS Profile
DDS_DomainParticipantQos participant_qos;4In C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C. // 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 }
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 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.
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.
© 2017 RTI