Request-Reply Examples

Examples on how to use the request-reply API. More...

Examples on how to use the request-reply API.

Request-Reply code examples.

Request-Reply Examples

DDS Types

RTI Connext uses DDS data types for sending and receiving requests and replies. Valid types are those generated by the rtiddsgen code generator, the DDS built-in types, and DynamicData. Refer to the User's Manual and the following links for more information:

• Creating user data types using rtiddsgen,
• Using the DDS built-in types,
• Using DynamicData

Set up

• Create a DomainParticipant
• Create a requester
• Create a requester with parameters
• Create a replier

Requester: sending requests and receiving replies

• Basic Requester example
• Taking loaned samples
• Taking samples by copy
• Correlation between requests and replies

Replier: receiving requests and sending replies

• Basic Replier example
• SimpleReplier example
• Taking loaned samples
• Taking samples by copy

Error handling

• Error handling example

Creating a Requester

• Setting up a participant
• Creating a Requester

  
              // Note: error checking omitted for simplicity
  
              // Create a DomainParticipant
              DomainParticipant participant =
                  DomainParticipantFactory.get_instance().create_participant(
                      domainId, DomainParticipantFactory.PARTICIPANT_QOS_DEFAULT,
                      null, StatusMask.STATUS_MASK_NONE);
  
              // Create a Requester (if creation fails an exception is thrown)
              // Foo is the request type and FooTypeSupport is its DDS TypeSupport
              // Bar is the reply type and BarTypeSupport is its DDS TypeSupport
              Requester<Foo, Bar> requester =
                  new Requester<Foo, Bar>(
                          participant, "TestService",
                          FooTypeSupport.get_instance(),
                          BarTypeSupport.get_instance());
  

• Finalizing a Requester

              // A Requester is IDisposable
              requester.Dispose();

  See also

  Creating a Requester with optional parameters

  Configuring Request-Reply QoS profiles

Creating a Requester with optional parameters

• Setting up a participant
• Creating a Requester with optional parameters

  
              // Note: error checking omitted for simplicity
  
              // Create a DomainParticipant
              DomainParticipant participant =
                  DomainParticipantFactory.get_instance().create_participant(
                          0, DomainParticipantFactory.PARTICIPANT_QOS_DEFAULT,
                          null, StatusMask.STATUS_MASK_NONE);
  
              // Create a Requester with a QoS profile (located for example in
              // USER_QOS_PROFILES.xml, in the current working directory)
              Requester<Foo, Bar> requester =
                  new Requester<Foo, Bar>(
                      new RequesterParams(
                          participant,
                          FooTypeSupport.get_instance(),
                          BarTypeSupport.get_instance())
                      .SetServiceName("TestService")
                      .SetQosProfile("RequestReplyExampleProfiles",
                                     "RequesterExampleProfile"));
  

  See also

  Creating a Requester

Basic Requester example

• Creating a Requester
• Creating a Requester with optional parameters
• Basic Requester example

  
              // Send request
              Foo request = new Foo();
              request.message = "A request";
              requester.SendRequest(request);
  
              // Create reply Sample
              Sample<Bar> reply = requester.CreateReplySample();
  
              // Receive reply (wait for it and get the sample)
              bool received = requester.ReceiveReply(reply, MAX_WAIT);
  
              if (received)
              {
                  if (reply.Info.valid_data)
                  {
                      Console.WriteLine("Received reply: " + reply.Data.message);
                  }
                  else
                  {
                      Console.WriteLine("Received invalid reply");
                  }
              }
              else
              {
                  Console.WriteLine("Reply not received");
              }
  

• Basic Requester example using the String built-in type

  
              // Create a requester using the String 
              // type with the DDS StringTypeSupport. The actual
              // type is StringWrapper
              Requester<StringWrapper, StringWrapper> requester =
                  new Requester<StringWrapper, StringWrapper>(
                      participant, "TestServiceString",
                      StringTypeSupport.get_instance(),
                      StringTypeSupport.get_instance());
  
              // Send request
              // Conversions between StringWrapper and String are supported
              requester.SendRequest("A request");
  
              // Create reply Sample
              Sample<StringWrapper> reply = requester.CreateReplySample();
  
              // Receive reply (wait for it and get the sample)
              bool received = requester.ReceiveReply(reply, MAX_WAIT);
  
              if (received && reply.Info.valid_data)
              {
                  Console.WriteLine("Received reply: " + reply.Data);
              }
  

• Basic Requester example using DynamicData.

  
              // Instantiate DynamicData type support. For simplicity we create them
              // from existing, generated TypeCode objects (Foo and Bar)
              DynamicDataTypeSupport fooDynamicTypeSupport =
                  new DynamicDataTypeSupport(
                      Foo.get_typecode(), new DynamicDataTypeProperty_t());
              DynamicDataTypeSupport barDynamicTypeSupport =
                  new DynamicDataTypeSupport(
                      Bar.get_typecode(), new DynamicDataTypeProperty_t());
  
              // Create a requester using a DynamicData type support
              Requester<DynamicData, DynamicData> requester =
                  new Requester<DynamicData, DynamicData>(
                      participant, "TestService",
                      fooDynamicTypeSupport,
                      barDynamicTypeSupport);
  
              // Create a Foo instance
              DynamicData foo = (DynamicData)fooDynamicTypeSupport.create_data();
              foo.set_string("message", DynamicData.MEMBER_ID_UNSPECIFIED,
                      "A dynamic request");
  
              // Send request
              requester.SendRequest(foo);
  
              // Create reply Sample
              Sample<DynamicData> reply = requester.CreateReplySample();
  
              // Receive reply (wait for it and get the sample)
              bool received = requester.ReceiveReply(reply, MAX_WAIT);
  
              if (received && reply.Info.valid_data)
              {
                  Console.WriteLine("Received reply: " +
                      reply.Data.get_string("message",
                          DynamicData.MEMBER_ID_UNSPECIFIED));
              }
  

  See also

  Basic Replier example

Taking loaned samples

• Get iterator to loaned replies (no copies)

  
              // Take loaned samples
              // Unlike ReceiveReplies(), TakeReplies()  doesn't block. It returns an
              // empty collection if there are no replies at that moment.
              // (before that we can call requester.wait_for_replies)
              //
              // LoanedSamples is IDisposable, so the loan is automatically returned
              // to the middleware when the application exits the using block.
              using (LoanedSamples<Bar> replies = requester.TakeReplies())
              {
                  foreach (Sample<Bar> reply in replies)
                  {
                      Console.WriteLine("Received: " + reply.Data.message);
                  }
              }
  

  See also

  Basic Requester example

  Basic Replier example

  Taking samples by copy

Taking samples by copy

• Get copies of the replies:

  
              List<Sample<Bar>> replies = new List<Sample<Bar>>();
  
              // Add to existing list, reusing and overwriting any existing elements
              requester.TakeReplies(replies, 10);
  
  
              foreach (Sample<Bar> reply in replies)
              {
                  Console.WriteLine("Received: " + reply.Data.message);
              }
  
              // Get replies in a newly created IList
              IList<Sample<Bar>> newList = requester.TakeReplies(null, 10);
              foreach (Sample<Bar> reply in newList)
              {
                  Console.WriteLine("Received: " + reply.Data.message);
              }
  

  See also

  Basic Replier example

  Taking loaned samples

Correlating requests and replies

• Creating a Requester
• Example 1) Waiting for a reply for a specific request

  
              // Create requests
              WriteSample<Foo> request1 = requester.CreateRequestSample();
              request1.Data.message = "Request 1";
              WriteSample<Foo> request2 = requester.CreateRequestSample();
              request2.Data.message = "Request 2";
  
              // Send requests using WriteSample
              requester.SendRequest(request1);
              requester.SendRequest(request2);
  
              // Wait for a reply to the second request
              Console.WriteLine("Waiting for reply to request2");
              Sample<Bar> reply = requester.CreateReplySample();
              requester.WaitForReplies(1, MAX_WAIT, request2.Identity);
              requester.TakeReply(reply, request2.Identity);
  
              Debug.Assert(
                  reply.RelatedIdentity.Equals(request2.Identity));
              Console.WriteLine("Received reply: " + reply.Data.message);
  
              // Wait for a reply to the first request
              Console.WriteLine("Waiting for reply to request1");
              requester.WaitForReplies(1, MAX_WAIT, request1.Identity);
              requester.TakeReply(reply, request1.Identity);
  
              Debug.Assert(
                  reply.RelatedIdentity.Equals(request1.Identity));
              Console.WriteLine("Received reply: " + reply.Data.message);
  

• Example 2) Correlate reply after receiving it

  
              // Create requests
              WriteSample<Foo> request1 = requester.CreateRequestSample();
              request1.Data.message = "Request 1";
              WriteSample<Foo> request2 = requester.CreateRequestSample();
              request2.Data.message = "Request 2";
  
              // Send requests using WriteSample
              requester.SendRequest(request1);
              requester.SendRequest(request2);
  
              // Wait for two replies
              bool received = requester.WaitForReplies(2, MAX_WAIT);
              if (!received)
              {
                  Console.WriteLine("Replies not received");
                  return;
              }
  
  
              using (LoanedSamples<Bar> replies = requester.TakeReplies())
              {
                  foreach (Sample<Bar> reply in replies)
                  {
                      if (reply.RelatedIdentity.Equals(request1.Identity))
                      {
                          Console.WriteLine(
                              "Received reply for request 1: " + reply.Data.message);
                      }
                      else if (reply.RelatedIdentity.Equals(request2.Identity))
                      {
                          Console.WriteLine(
                              "Received reply for request 2: " + reply.Data.message);
                      }
                      else
                      {
                          // Should not happen
                          Console.WriteLine("Received unexpected reply");
                      }
                  }
              }
  

  See also

  Basic Requester example

  Basic Replier example

Creating a Replier

• Setting up a participant
• Creating a Replier

  
              // Create a DomainParticipant
              DomainParticipant participant =
                  DomainParticipantFactory.get_instance().create_participant(
                      domain_id, DomainParticipantFactory.PARTICIPANT_QOS_DEFAULT,
                      null, StatusMask.STATUS_MASK_NONE);
  
              // Create a Requester
              Replier<Foo, Bar> replier = new Replier<Foo, Bar>(
                  participant, "TestService",
                  FooTypeSupport.get_instance(),
                  BarTypeSupport.get_instance());
  

• Finalizing a Replier

              // A Replier is IDisposable
              replier.Dispose();

Basic Replier example

• Creating a Replier
• Basic Replier example

  
              // Create a Sample for reading
              Sample<Foo> request = replier.CreateRequestSample();
  
              // Receive one request
              bool received = replier.ReceiveRequest(request, MAX_WAIT);
  
              if (!received)
              {
                  Console.WriteLine("Request not received");
                  return false;
              }
  
              if (request.Info.valid_data)
              {
                  // Send a reply for that request
                  Bar reply = new Bar();
                  reply.message = "Reply for " + request.Data.message;
                  replier.SendReply(reply, request.Identity);
              }
  
              // Note: a replier can send more than one reply for the same request
  

  See also

  Basic Requester example

SimpleReplier example

• Implement a listener

          class MySimpleReplierListener : SimpleReplierListener<Foo, Bar>
          {
  
              private Bar reply = new Bar();
  
              public Bar OnRequestAvailable(Sample<Foo> request)
              {
                  if (request.Info.valid_data)
                  {
                      // Return a reply
                      reply.message = "Simple reply for " + request.Data.message;
                      return reply;
                  }
                  else
                  {
                      // Do not reply to dispose/unregister samples
                      return null;
                  }
              }
  
              public void ReturnLoan(Bar reply)
              {
                  // nothing to do
              }
  
          }

• And create a SimpleReplier with the listener:

  
              // Create a SimpleReplier using a DomainParticipant, service name and
              // the a SimpleReplierListener implementation
              SimpleReplier<Foo, Bar> replier =
                  new SimpleReplier<Foo, Bar>(
                      participant, "TestService",
                      new MySimpleReplierListener(),
                      FooTypeSupport.get_instance(),
                      BarTypeSupport.get_instance());
  
              // After creation the SimpleReplier is already active and may call
              // the listener
  

  See also

  Basic Requester example

Error handling example

• Catching an exception from the request-reply API

  
              // All the operations in the request-reply API
              // throw exceptions in case of error.
  
              // You can also set the verbosity level to warning for
              // additional information
              NDDS.ConfigLogger.get_instance().set_verbosity(
                  NDDS.LogVerbosity.NDDS_CONFIG_LOG_VERBOSITY_WARNING);
  
  
              //
              // For example, this replier is sending a reply for a nonexistent request
              //
              WriteSample<Bar> reply = replier.CreateReplySample();
              SampleIdentity_t invalidRequestId = new SampleIdentity_t();
  
  
              try
              {
                  replier.SendReply(reply, invalidRequestId);
              }
              catch (Retcode_BadParameter ex)
              {
                  // You can also catch Retcode_Error, which is more generic
                  Console.WriteLine("Exception while sending reply: " + ex);
              }
  

Configuring Request-Reply QoS profiles

If you do not specify your own quality of service parameters (in RTI::Connext::RequestReply::RequesterParams and RTI::Connext::RequestReply::ReplierParams<TReq,TRep>), a RTI::Connext::RequestReply::Requester<TReq,TRep> and RTI::Connext::RequestReply::Replier<TReq,TRep> are created using a default configuration. That configuration is equivalent to the one in the following QoS profile called "default":

<?xml version="1.0"?>
<!-- 
Description
XML QoS Profile for HelloWorld

(c) Copyright, Real-Time Innovations, 2012.  All rights reserved.
RTI grants Licensee a license to use, modify, compile, and create derivative
works of the software solely for use with RTI Connext DDS. Licensee may
redistribute copies of the software provided that all such copies are
subject to this license. The software is provided "as is", with no warranty
of any type, including any warranty for fitness for any purpose. RTI is
under no obligation to maintain or support the software. RTI shall not be
liable for any incidental or consequential damages arising out of the use
or inability to use the software.

The QoS configuration of the DDS entities in the generated example is loaded 
from this file.

This file is used only when it is in the current working directory or when the
environment variable NDDS_QOS_PROFILES is defined and points to this file.

The profile in this file inherits from the builtin QoS profile 
BuiltinQosLib::Generic.StrictReliable. That profile, along with all of the 
other built-in QoS profiles can be found in the 
BuiltinProfiles.documentationONLY.xml file located in the 
$NDDSHOME/resource/xml/ directory.

You may use any of these QoS configurations in your application simply by 
referring to them by the name shown in the 
BuiltinProfiles.documentationONLY.xml file.

Also, following the QoS Profile composition pattern you can use QoS Snippets
to easily create your final QoS Profile. For further information visit:
https://community.rti.com/best-practices/qos-profile-inheritance-and-composition-guidance

There is a QoS Snippet library that contains a collection of
QoS Snippets that set some specific features or configurations. You can find
them in the BuiltinProfiles.documentationONLY.xml file as well.

You should not edit the file BuiltinProfiles.documentationONLY.xml directly.
However, if you wish to modify any of the values in a built-in profile, the
recommendation is to create a profile of your own and inherit from the built-in
profile you wish to modify. The NDDS_QOS_PROFILES.example.xml file (contained in 
the same directory as the BuiltinProfiles.documentationONLY.xml file) shows how
to inherit from the built-in profiles. 

For more information about XML QoS Profiles see the "Configuring QoS with
XML" chapter in the RTI Connext DDS Core Libraries User's Manual.
-->

<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="file:////rti/jenkins/workspace/connextdds_htmldocs_release_connextdds_6.1.2/build/nddsgen.2.0/resource/schema/rti_dds_qos_profiles.xsd">
    <!-- QoS Library containing the QoS profile used in the generated example.

        A QoS library is a named set of QoS profiles.
    -->
    <qos_library name="HelloWorld_Library">

        <!-- QoS profile used to configure reliable communication between the DataWriter 
             and DataReader created in the example code.

             A QoS profile groups a set of related QoS.
        -->
        <qos_profile name="HelloWorld_Profile" base_name="BuiltinQosLib::Generic.StrictReliable" is_default_qos="true">
            <!-- QoS used to configure the data writer created in the example code -->                
            <datawriter_qos>
                <publication_name>
                    <name>HelloWorldDataWriter</name>
                </publication_name>
            </datawriter_qos>

            <!-- QoS used to configure the data reader created in the example code -->                
            <datareader_qos>
                <subscription_name>
                    <name>HelloWorldDataReader</name>
                </subscription_name>
            </datareader_qos>
            <domain_participant_qos>
                <!--
                The participant name, if it is set, will be displayed in the
                RTI tools, making it easier for you to tell one
                application from another when you're debugging.
                -->
                <participant_name>
                    <name>HelloWorldParticipant</name>
                    <role_name>HelloWorldParticipantRole</role_name>
                </participant_name>

            </domain_participant_qos>
        </qos_profile>

    </qos_library>
</dds>

You can use the profile called "RequesterExampleProfile", which modifies some parameters from the default. The example Creating a Requester with optional parameters shows how to create a RTI::Connext::RequestReply::Requester<TReq,TRep> using this profile.

See also

Creating a Requester with optional parameters

Configuring QoS Profiles with XML