Qos Provider Use Cases

How to use the QosProvider class to access XML QoS profiles. More...

How to use the QosProvider class to access XML QoS profiles.

Managing Qos Profiles

The QosProvider class provides a way for a user to control and access the XML QoS profiles that are loaded by RTI Connext. A QosProvider is created with a URI that identifies a file location containing QoS profiles, a string representation of the QoS profiles that you want the QosProvider to load, or a URL group that has a combination of files and strings from which to load profiles. For more information on the correct format of these URIs and URL groups, please see section 17.11 URL Groups in the RTI_CoreLibrariesAndUtilities_Users_Manual.pdf. More information about QoS Profiles can be found in section 17.9 QoS Profiles, also in the User's Manual.

A QosProvider can also load type definitions.

The following #includes are needed for the examples on this page

#include <dds/dds.hpp>

#include "Foo.hpp"

• The Qos Profile that will be used in the following examples. 'a_string_uri' in any of the following examples is this profile in the form of str://"<dds>...</dds>"

  const int MY_XML_SIZE = 20;
  
  const char * MyXML[MY_XML_SIZE] =
  {
  "<dds>",
      "<qos_library name=\"MyLibrary\">",
          "<qos_profile name=\"MyProfile\" is_default_qos=\"true\">",
              "<participant_qos>",
                  "<participant_name>",
                      "<name>ExampleParticipantName</name>",
                  "</participant_name>",
              "</participant_qos>",
          "</qos_profile>",
      "</qos_library>",
      "<qos_library name=\"MySecondLibrary\">",
          "<qos_profile name=\"MySecondProfile\">",
              "<participant_qos>",
                  "<participant_name>",
                      "<name>SecondExampleParticipantName</name>",
                  "</participant_name>",
              "</participant_qos>",
          "</qos_profile>",
      "</qos_library>",
  "</dds>"
  };

  
  
• Creating a QosProvider

      // Create a QosProvider which ignores any is_default_qos tags found in XML
      // by passing in the USE_DDS_DEFAULT_QOS_PROFILE constant to the QosProvider's
      // constructor.
      // Creating the QosProvider this way will allow you to access the 
      // RTI Connext default Qos values for each entity. The following 
      // QosProvider will not have a default library or profile, even though
      // MyLibrary::MyProfile has been marked as is_default_qos
      dds::core::QosProvider qos_provider_no_default_profile(
         a_string_uri, rti::core::USE_DDS_DEFAULT_QOS_PROFILE);
  
      // You can also create a QosProvider which overrides any is_default_qos tag 
      // found in XML with a new default profile. In this case, instead of 
      // MyLibrary::MyProfile as the default profile, the new default will be the 
      // built-in BuiltinQosLib::Baseline.5.1.0 profile
      dds::core::QosProvider qos_provider_new_default(
         a_string_uri, "BuiltinQosLib::Baseline.5.1.0");

  
  
• Configuring a QosProvider

      // The ProfileQosPolicy that is available in all other RTI Connext language 
      // APIs is renamed rti::core::QosProviderParams in the new C++ PSM. These 
      // parameters allow you to control which QoS profiles RTI Connext will 
      // load
      dds::core::QosProvider qos_provider(a_string_uri);
  
      // Get the current QosProviderParams from the qos_provider
      rti::core::QosProviderParams params = qos_provider->provider_params();
  
      // Ignore any qos profiles in the USER_QOS_PROFILES.xml file 
      params.ignore_user_profile(true);
  
      // Setting the params automatically reloads the profiles
      qos_provider->provider_params(params);

  
  
• Accessing, changing and using the QoS libraries and profiles that are loaded by a QosProvider

      // After you have created the qos_provider with the QoS profiles that 
      // you want to load, you can access the names of the loaded libraries and 
      // profiles and use the profiles to create entities
      dds::core::QosProvider qos_provider(a_string_uri);
      
      // This participant will have the name "ExampleParticipantName" from the 
      // MyLibrary::MyProfile marked with the is_default_qos tag
      dds::domain::DomainParticipant participant(0, qos_provider.participant_qos());
  
      // Get a list of the currently loaded libraries. This list will include 
      // all of the built-in QoS libraries as well as the two libraries from the 
      // string URI that this QoS Provider was created with
      dds::core::StringSeq libraries = qos_provider->qos_profile_libraries();
  
      // Get a list of the currently loaded profiles for a given library
      if (libraries.size() > 0) {
          dds::core::StringSeq profiles = qos_provider->qos_profiles(libraries[0]);
      }
  
      // Get the current default library, default_library_name will be "MyLibrary"
      // This is the library that is checked in if you set the default
      // profile without specifying a library name
      rti::core::optional_value<std::string> default_library_name = 
          qos_provider->default_library();
  
      // Set the current default library
      qos_provider->default_library("BuiltinQosLibExp");
  
      // Get the current default profile library. default_profile_library_name
      // will be "MyLibrary". This is the library that the default profile 
      // is a part of. You cannot explicitly set this field, it gets set anytime 
      // that the default profile is changed
      rti::core::optional_value<std::string> default_profile_library_name = 
          qos_provider->default_profile_library();
  
      // Get the current default profile, default_profile_name will be "MyProfile"
      rti::core::optional_value<std::string> default_profile_name = 
          qos_provider->default_profile();
  
      // default_library(), default_profile_library(), and default_profile() 
      // all return rti::core::optional_value<std::string> types because it is 
      // possible to not have a default library or profile. You can also clear 
      // the default library and profile using 
      // rti::core::USE_DDS_DEFAULT_QOS_PROFILE
      qos_provider->default_profile(rti::core::USE_DDS_DEFAULT_QOS_PROFILE);
  
      // In order for all of the changes to the default library and profile 
      // names to take effect the QoS libraries must be reloaded
      qos_provider->reload_profiles();
  
      // This topic will get created with the default RTI Connext TopicQos values
      dds::topic::Topic<Foo> 
          topic(participant, "ExampleTopic", qos_provider.topic_qos());
  
      // Setting the default profile. Because we set the default library to 
      // BuiltinQosLibExp above, we only need to specify the profile name here.
      // If the default_library name hadn't been changed then we could
      // still set the default to this same profile profile by using the string 
      // "BuiltinQosLibExp::Generic.StrictReliable"
      qos_provider->default_profile("Generic.StrictReliable");
  
      qos_provider->reload_profiles();
  
      // Retrieve the DataWriterQos from the QosProvider and edit any desired 
      // values. The assignment results in a copy so any changes made to the
      // writer_qos object will not be reflected in any subsequent calls to
      // qos_provider.datawriter_qos()
      dds::pub::qos::DataWriterQos writer_qos = qos_provider.datawriter_qos();
  
      writer_qos << dds::core::policy::Reliability::Reliable();
  
      // Create a strict reliable DataWriter
      dds::pub::DataWriter<Foo>(
         dds::pub::Publisher(participant), topic, writer_qos);

  
  
• Using and configuring the default QosProvider

      // QoS profiles from any XML file specified in the environment variable
      // NDDS_QOS_PROFILES file will not be loaded by the application
      rti::core::QosProviderParams params;
      params.ignore_environment_profile(true);
  
      // Have the default QosProvider load the example XML QoS profile at the
      // top of this page
      dds::core::StringSeq my_string_profile(MyXML, MyXML + MY_XML_SIZE);
      params.string_profile(my_string_profile);
  
      dds::core::QosProvider::Default()->default_provider_params(params);
  
      // This participant will be created with the  name "ExampleParticipantName" 
      // because "MyLibrary::MyProfile" has been has been marked as the default 
      // with the is_default_qos tag and was loaded because we set the 
      // string_profile field of the default QosProvider's QosProviderParams. 
      // The Qos values that this participant is created with are equal to 
      // dds::core::QosProvider::Default().participant_qos()
      dds::domain::DomainParticipant participant1(0);
  
      // Change the default profile
      dds::core::QosProvider::Default()->default_profile(
         "MySecondLibrary::MySecondProfile");
      dds::core::QosProvider::Default()->reload_profiles();
  
      // This participant will be created with the name "SecondExampleParticipantName"
      dds::domain::DomainParticipant participant2(1);
  
      // Reset the QosProviderParams for the default QosProvider
      dds::core::QosProvider::reset_default();
  
      // This participant will not have a participant name (the default 
      // RTI Connext value) because we reset the default QosProviderParams, 
      // meaning that the value for string_profile is empty and the above example 
      // XML Qos profile is not loaded.
      dds::domain::DomainParticipant participant3(2);

  See Also

  Create a DynamicType from an XML description

The Default Qos Provider

The default QoS values that are used to create an entity are determined by which QoS profiles have been loaded at the time of that entity's creation and which of these profiles has been marked as the default profile. RTI Connext will automatically load XML Qos profiles from a number of locations (see section 17.2 How to Load XML-Specified QoS Setting in the RTI_CoreLibrariesAndUtilities_Users_Manual.pdf). Marking a profile as the default profile to use during entity creation can be done with an is_default_qos tag in the XML profile or by setting the default profile of the default QosProvider in code.

The default QosProvider is a singleton that can be used to access and control the Qos XML profiles that will be used when creating entities without explicitly providing a Qos object with which to construct the entity. Changing the QosProviderParams of the default QosProvider will affect all future entity creation with default Qos values.

• Using and configuring the default QosProvider

      // QoS profiles from any XML file specified in the environment variable
      // NDDS_QOS_PROFILES file will not be loaded by the application
      rti::core::QosProviderParams params;
      params.ignore_environment_profile(true);
  
      // Have the default QosProvider load the example XML QoS profile at the
      // top of this page
      dds::core::StringSeq my_string_profile(MyXML, MyXML + MY_XML_SIZE);
      params.string_profile(my_string_profile);
  
      dds::core::QosProvider::Default()->default_provider_params(params);
  
      // This participant will be created with the  name "ExampleParticipantName" 
      // because "MyLibrary::MyProfile" has been has been marked as the default 
      // with the is_default_qos tag and was loaded because we set the 
      // string_profile field of the default QosProvider's QosProviderParams. 
      // The Qos values that this participant is created with are equal to 
      // dds::core::QosProvider::Default().participant_qos()
      dds::domain::DomainParticipant participant1(0);
  
      // Change the default profile
      dds::core::QosProvider::Default()->default_profile(
         "MySecondLibrary::MySecondProfile");
      dds::core::QosProvider::Default()->reload_profiles();
  
      // This participant will be created with the name "SecondExampleParticipantName"
      dds::domain::DomainParticipant participant2(1);
  
      // Reset the QosProviderParams for the default QosProvider
      dds::core::QosProvider::reset_default();
  
      // This participant will not have a participant name (the default 
      // RTI Connext value) because we reset the default QosProviderParams, 
      // meaning that the value for string_profile is empty and the above example 
      // XML Qos profile is not loaded.
      dds::domain::DomainParticipant participant3(2);