How to Load XML-Specified QoS Settings

You are here:

19.5 How to Load XML-Specified QoS Settings

There are several ways to load XML QoS profiles into your application. In C, Traditional C++, Java and .NET, it's the singleton DomainParticipantFactory that loads these profiles. Applications using the Modern C++ API can create any number of instances of dds::core::QosProvider with different parameters to load different QoS profiles or, they can use the singleton QosProvider::Default(). The profiles configured in the default QosProvider are used when creating an Entity without an explicit QoS parameter.

Here are the various approaches, listed in load order:

$NDDSHOME/resource/xml/NDDS_QOS_PROFILES.xml
This file is loaded automatically if it exists (not the default) and ignore_resource_profile in the 9.4.2 PROFILE QosPolicy (DDS Extension) is FALSE (the default). NDDS_QOS_PROFILES.xml does not exist by default. However, NDDS_QOS_PROFILES.example.xml is shipped with the host bundle of the product; you can copy it to NDDS_QOS_PROFILES.xml and modify it for your own use. The file contains the default QoS values that will be used for all entity kinds. (First to be loaded)
XML files in NDDS_QOS_PROFILES
One or more XML files separated by semicolons referenced by the environment variable NDDS_QOS_PROFILES are loaded automatically if they exist and ignore_environment_profile in 9.4.2 PROFILE QosPolicy (DDS Extension) is FALSE (the default).

Semicolons indicate to Connext DDS to load multiple files or strings all at once. For example:

On UNIX-like systems with bash

export NDDS_QOS_PROFILES=file:///usr/local/default_dds_1.xml; file:///usr/local/default_dds_2.xml

On UNIX-like systems with tcsh

setenv NDDS_QOS_PROFILES file:///usr/local/default_dds_1.xml; file:///usr/local/default_dds_2.xml

In a Windows command prompt

set NDDS_QOS_PROFILES=file://D:/Data/ConnextDDSExample/default_dds_1.xml; file://D:/Data/ConnextDDSExample/default_dds_2.xml

<working directory>/USER_QOS_PROFILES.xml
This file is loaded automatically if it exists and ignore_user_profile in 9.4.2 PROFILE QosPolicy (DDS Extension) is FALSE (the default).
XML files in url_profile
One or more XML files referenced by url_profile (in 9.4.2 PROFILE QosPolicy (DDS Extension) ) will be loaded automatically if specified.

XML strings in string_profile
The sequence of XML strings referenced by string_profile (in 9.4.2 PROFILE QosPolicy (DDS Extension) ) will be loaded automatically if specified. See 19.7 XML String Syntax. (Last to be loaded)

Note: The url_profile and string_profile fields are useful for adding profiles programmatically, when you do not want to use an environment variable.

You may use a combination of the above approaches.

The location of the XML documents (only files and strings are supported) is specified using URL (Uniform Resource Locator) format. For example:

File Specification: file:///usr/local/default_dds.xml
String Specification: str://"<dds><qos_library>…</qos_library></dds>"

If you omit the URL schema name, Connext DDS will assume a file name. For example:

File Specification: /usr/local/default_dds.xml

Note: The path you specify can be absolute or relative. If you specify a relative path, it should be a path to a file that is lower down in the file hierarchy, not higher up.

Duplicate QoS profiles are not allowed. Connext DDS will report an error message in these scenarios. To overwrite a QoS profile, use 19.3.3 QoS Profile Inheritance and Composition.

Several QoS profiles are built into the Connext DDS core libraries and can be used as starting points when configuring QoS for your Connext DDS applications. For details, see 19.4 Configuring QoS with XML.

To load redundant locations for a single XML file, see 19.8 URL Groups (Loading Redundant Locations).