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

• SimpleReplier example

• Basic Replier example

• Taking loaned samples

• Taking samples by copy

Error handling

• Error handling example

Requester Creation

• Setting up a participant

• Creating a Requester

      using namespace connext;
  
      // Note: error checking omitted for simplicity
  
      // Create a DomainParticipant
      DDS::DomainParticipant * participant =
          DDS::DomainParticipantFactory::get_instance()->create_participant(
              domain_id, DDS::PARTICIPANT_QOS_DEFAULT,
              NULL, DDS::STATUS_MASK_NONE);
  
      // Create a Requester (if creation fails, the constructor throws)
      Requester<Foo, Bar> * requester =
          new Requester<Foo, Bar>(participant, "TestService");
  

Creating a Requester with optional parameters

• Setting up a participant

• Creating a Requester with additional parameters

      using namespace connext;
  
      // Note: error checking omitted for simplicity
  
      // Create a DomainParticipant
      DDS::DomainParticipant * participant =
          DDS::DomainParticipantFactory::get_instance()->create_participant(
              domain_id, DDS::PARTICIPANT_QOS_DEFAULT,
              NULL, DDS::STATUS_MASK_NONE);
  
      // Create a Requester with a QoS profile (located for example in
      // USER_QOS_PROFILES.xml, in the current working directory)
      RequesterParams requester_params(participant);
      requester_params.service_name("TestService");
      requester_params.qos_profile(
          "RequestReplyExampleProfiles", "RequesterExampleProfile");
  
      Requester<Foo, Bar> * requester = new Requester<Foo, Bar>(requester_params);
  

  See Also

  Requester Creation

  Configuring Request-Reply QoS profiles

Basic Requester example

• Requester Creation
• Creating a Requester with optional parameters

• Basic Requester example

      using namespace connext;
  
      // Send request
      WriteSample<Foo> request;
      strcpy(request.data().message, "A Request");
  
      requester->send_request(request);
  
      // Create a reply Sample
      Sample<Bar> reply;
  
      // Receive reply (wait for it and get the sample)
      bool received = requester->receive_reply(reply, MAX_WAIT);
  
      if (received) {
          if(reply.info().valid_data) {
              std::cout << "Received reply: " << reply.data().message << std::endl;
          } else {
              std::cout << "Received invalid reply" << std::endl;
          }
      } else {
          std::cout << "Reply not received" << std::endl;
      }
  

• Basic Requester example using the String built-in type

  
      using namespace connext;
  
      // Create a Requester (this time we create it on the stack)
      // The template parameter std::string maps to the String DDS built-in type
      Requester<std::string, std::string> requester(participant, "TestServiceString");
  
      // Send a request
      requester.send_request("A string request");
  
      // Receive reply
      LoanedSamples<std::string> replies = requester.receive_replies(MAX_WAIT);
  
      for (LoanedSamples<std::string>::iterator it = replies.begin();
           it != replies.end();
           ++it) {
          if (it->info().valid_data) {
              std::cout << "Received string reply: " << it->data() << std::endl;
          }
      }
  
      // When replies go out of scope, the loan is automatically returned
  

  See Also

  Basic Replier example

  SimpleReplier example

Taking loaned samples

• Requester Creation

• Get iterator to loaned replies (no copies)

  
      using namespace connext;
  
      // Get loaned samples
      // Unlike receive_replies(), take_replies() doesn't block and returns an
      // empty collection if there are no replies at that moment.
      // (before that we can call requester->wait_for_replies)
      LoanedSamples<Bar> replies = requester->take_replies();
  
      // Iterate through the container of loaned samples.
      // If there were no replies, the container is empty
      for (LoanedSamples<Bar>::const_iterator it = replies.begin();
          it != replies.end();
          ++it) {
  
          if (it->info().valid_data) {
              std::cout << "Received reply: " << it->data().message << std::endl;
          }
      }
  
      // When replies go out of scope, the loan is automatically returned
  

  See Also

  Basic Requester example

  Basic Replier example

  Taking samples by copy

Taking samples by copy

• Requester Creation

• Get copies of the replies:

  
      using namespace connext;
  
      // Get loaned samples
      LoanedSamples<Bar> replies = requester->take_replies();
  
      // Copy the contents using the STL-compliant iterator in LoanedSamples
      std::list<Sample<Bar> > my_list;
      std::copy(replies.begin(), replies.end(), std::back_inserter(my_list));
  
      // We can copy to a container of Bar rather than Sample<Bar>,
      // thanks to the implicit conversion from Sample<Bar> to Bar.
      // If our application works with instances, we may have received
      // invalid data (e.g. disposed instance). We can iterate through valid
      // samples only using an iterator adapter.
      std::vector<Bar> my_vector;
      std::copy(
          make_valid_sample_iterator(replies.begin()),
          make_valid_sample_iterator(replies.end()),
          std::back_inserter(my_vector));
  
      // When replies go out of scope, the loan is automatically returned
  

  See Also

  Basic Replier example

  Taking loaned samples

Correlating requests and replies

• Requester Creation

• Example 1) Waiting for a reply to a specific request

  
      using namespace connext;
  
      // Create requests
      WriteSample<Foo> request1, request2;
      strcpy(request1.data().message, "Request 1");
      strcpy(request2.data().message, "Request 2");
  
      // Send requests using WriteSample
      requester->send_request(request1);
      requester->send_request(request2);
  
      // Wait for a reply to the second request
      Sample<Bar> reply;
      bool received = requester->wait_for_replies(
          1, MAX_WAIT, request2.identity());
  
      if (!received) {
          std::cout << "Did not receive reply for request 2" << std::endl;
          return;
      }
  
      // Take that reply
      requester->take_reply(reply, request2.identity());
  
      // This postcondition should always be true
      if (reply.related_identity() != request2.identity()) {
          throw std::runtime_error("postcondition failed");
      }
  
      if (reply.info().valid_data) {
          std::cout << "Received reply for request 2: "
                    << reply.data().message << std::endl;
      }
  
      // Wait for a reply to the first request
      received = requester->wait_for_replies(1, MAX_WAIT, request1.identity());
  
      if (!received) {
          std::cout << "Did not receive reply for request 1" << std::endl;
          return;
      }
  
      // Take that reply
      requester->take_reply(reply, request1.identity());
  
      // This postcondition should always be true
      if (reply.related_identity() != request1.identity()) {
          throw std::runtime_error("postcondition failed");
      }
  
      if (reply.info().valid_data) {
          std::cout << "Received reply for request 1: "
                    << reply.data().message << std::endl;
      }
  

• Example 2) Correlating a reply after receiving it

  
      using namespace connext;
  
      // Create requests
      WriteSample<Foo> request1, request2;
      strcpy(request1.data().message, "Request 1");
      strcpy(request2.data().message, "Request 2");
  
      // Send requests using WriteSample
      requester->send_request(request1);
      requester->send_request(request2);
  
      // Wait for two replies. In this case we don't mind the
      // reception order
      bool received = requester->wait_for_replies(2, MAX_WAIT);
      if (!received) {
          std::cout << "Replies not received" << std::endl;
          return;
      }
  
      LoanedSamples<Bar>::iterator it;
  
      // Get all the replies
      LoanedSamples<Bar> replies = requester->take_replies();
  
      // Find the reply for request 1.
      //
      // We search using the STL find_if algorithm. The search range is all
      // the elements in the replies container (from beginning to end).
      // We use a predicate included in the Connext namespace that evaluates to
      // true when a Sample's related_identity equals the identity that
      // is passed to the constructor (request1's, in this case)
      it = std::find_if(replies.begin(), replies.end(),
                        IsReplyRelatedPredicate<Bar>(request1.identity()));
  
      if (it != replies.end()) {
          std::cout << "Received reply for request 1: "
                    << it->data().message << std::endl;
      }
  
      // Find the reply for request 2
      it = std::find_if(replies.begin(), replies.end(),
                        IsReplyRelatedPredicate<Bar>(request2.identity()));
  
      if (it != replies.end()) {
          std::cout << "Received reply for request 2: "
                    << it->data().message << std::endl;
      }
  
      // When replies go out of scope, the loan is automatically returned
  

  See Also

  Basic Requester example

  Basic Replier example

Basic Requester example using SampleRef

This example is similar to Basic Requester example except it uses a SampleRef instance instead of a Sample instance.

• Assuming the variables you want to use already exist:

      Foo request_data;
      DDS::WriteParams_t request_params;
  
      Bar reply_data;
      DDS::SampleInfo reply_info;
  
      // ...
  

• You can use WriteSampleRef and SampleRef:

      using namespace connext;
  
      // Create a request WriteSampleRef
      WriteSampleRef<Foo> request;
      request.set_data(request_data);
      request.set_info(request_params);
  
      // Send request
      requester->send_request(request);
  
      // Create a reply SampleRef
      SampleRef<Bar> reply;
      reply.set_data(reply_data);
      reply.set_info(reply_info);
  
      // Receive reply
      bool received = requester->receive_reply(reply, MAX_WAIT);
  
      if (received) {
          if(reply_info.valid_data) {
              std::cout << "Received reply: " << reply_data.message << std::endl;
          } else {
              std::cout << "Received invalid reply" << std::endl;
          }
      } else {
          std::cout << "Reply not received" << std::endl;
      }
  

  See Also

  connext::SampleRef

  Basic Requester example

Creating a Replier

• Setting up a participant

• Create a Replier

      using namespace connext;
  
      // Note: error checking omitted for simplicity
  
      // Create a DomainParticipant
      DDS::DomainParticipant * participant =
          DDS::DomainParticipantFactory::get_instance()->create_participant(
              domain_id, DDS::PARTICIPANT_QOS_DEFAULT,
              NULL, DDS::STATUS_MASK_NONE);
  
      // Create a Replier (if creation fails, the constructor throws exception)
      Replier<Foo, Bar> * replier =
          new Replier<Foo, Bar>(participant, "TestService");
  

Basic Replier example

• Creating a Replier

• Basic Replier example

  
      using namespace connext;
  
      Sample<Foo> request;
  
      // Receive one request
      bool received = replier->receive_request(request, MAX_WAIT);
  
      if (!received) {
          std::cout << "Requests not received" << std::endl;
          return false;
      }
  
      // A WriteSample automatically initializes and finalizes
      // the data using the TypeSupport (in this case BarTypeSupport)
      WriteSample<Bar> reply;
  
      if (request.info().valid_data) {
          sprintf(reply.data().message, "Reply for %s", request.data().message);
  
          // Send a reply for that request
          replier->send_reply(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 : public SimpleReplierListener<Foo, Bar>
  {
  public:
      Bar * on_request_available(SampleRef<Foo> request)
      {
          if (!request.info().valid_data) {
              // In this example we don't reply to invalid data samples.
              // In other cases, it could make sense to reply
              // to a disposed instance, for example.
              return NULL;
          }
  
          sprintf(_reply.data().message, "Simple reply for %s",
                  request.data().message);
  
          return &_reply.data();
      }
  
      void return_loan(Bar * reply)
      {
          // nothing to do
      }
  
  private:
      // By using a WriteSample (instead of just Bar), the sample is
      // automatically initialized and released.
      WriteSample<Bar> _reply;
  };

• And create a SimpleReplier with the listener

  
      using namespace connext;
  
      // Note: error checking omitted for simplicity
  
      MySimpleReplierListener * listener = new MySimpleReplierListener();
  
      SimpleReplier<Foo, Bar> * replier = new SimpleReplier<Foo, Bar>(
          participant, "TestService", *listener);
  
      // After creation the SimpleReplier is already active and may call
      // the listener
  

• This next example shows how to implement a listener for a SimpleReplier using the std::string type

  class MyStringSimpleReplierListener :
      public SimpleReplierListener<std::string, std::string>
  {
  public:
      // Note that the actual received type is const char*,
      // because internally, the middleware uses char*
      std::string * on_request_available(SampleRef<const char*> request)
      {
          if (!request.info().valid_data) {
              return NULL;
          }
  
          _reply = std::string("Simple string reply for ") + request.data();
          return &_reply;
      }
  
      void return_loan(std::string * reply)
      {
          // nothing to do
      }
  
  private:
      std::string _reply;
  };

  See Also

  Basic Requester example

Error handling example

• Catching an exception from the request-reply API

      using namespace connext;
  
      // 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
      NDDSConfigLogger::get_instance()->set_verbosity(
          NDDS_CONFIG_LOG_VERBOSITY_WARNING);
  
      //
      // For example, this replier is sending a reply for a nonexistent request
      //
      WriteSample<Bar> reply;
      DDS::SampleIdentity_t invalid_request_id;
  
      try {
          replier->send_reply(reply, invalid_request_id);
      } catch (const BadParameterException& ex) {
          std::cout << "Exception while sending reply: "
                    << ex.what() << std::endl;
      }
  
      // Exceptions inherit from std::runtime_error or std::logic_error,
      // so you can have a more general catch statement:
      //
      // This piece of code produces the same result as the previous one:
      //
      try {
          replier->send_reply(reply, invalid_request_id);
      } catch (const std::exception& ex) {
          std::cout << "Exception while sending request: "
                    << ex.what() << std::endl;
      }
  

Configuring Request-Reply QoS profiles

If you do not specify your own QoS parameters (in connext::RequesterParams and connext::ReplierParams), a connext::Requester and connext::Replier are created using a default configuration. That configuration is equivalent to the one in the following QoS profile called "default":

<?xml version="1.0"?>

<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="../../../resource/schema/rti_dds_qos_profiles.xsd"
    version="5.3.1">

    <qos_library name="RequestReplyExampleProfiles">
    
        <!-- Default QoS:
             
             This profile contains the QoS that Requesters and Repliers 
             would use by default. We can use it as a base profile to inherit
             from and override some parameters 
         -->
        <qos_profile name="default">
            <datawriter_qos>
            
                <!-- Strict reliable -->
                <reliability>
                    <kind>RELIABLE_RELIABILITY_QOS</kind>
                    <max_blocking_time>
                        <sec>10</sec>
                        <nanosec>0</nanosec>
                    </max_blocking_time>
                </reliability>
                
                <history>
                    <kind>KEEP_ALL_HISTORY_QOS</kind>
                </history>
                
                <!-- These are typical protocol parameters for a reliable
                     DataWriter -->
                <protocol>
                    <rtps_reliable_writer>
                        <max_heartbeat_retries>
                            LENGTH_UNLIMITED
                        </max_heartbeat_retries>
                        <heartbeats_per_max_samples>
                            2
                        </heartbeats_per_max_samples>
                        <heartbeat_period>
                            <sec>0</sec>
                            <nanosec>100000000</nanosec> <!--100ms -->
                        </heartbeat_period>
                        <fast_heartbeat_period>
                            <sec>0</sec>
                            <nanosec>10000000</nanosec> <!--10ms -->
                        </fast_heartbeat_period>
                        <late_joiner_heartbeat_period>
                            <sec>0</sec>
                            <nanosec>10000000</nanosec> <!--10ms -->
                        </late_joiner_heartbeat_period>
                        <max_nack_response_delay>
                            <sec>0</sec>
                            <nanosec>0</nanosec>
                        </max_nack_response_delay>
                        <min_nack_response_delay>
                            <sec>0</sec>
                            <nanosec>0</nanosec>
                        </min_nack_response_delay>
                        <max_send_window_size>32</max_send_window_size>
                        <min_send_window_size>32</min_send_window_size>
                    </rtps_reliable_writer>
                </protocol>
                
                <writer_resource_limits>
                    <!-- This setting enables efficient communication
                         between a replier and an arbitrary number of requesters 
                     -->
                    <max_remote_reader_filters>
                        LENGTH_UNLIMITED
                    </max_remote_reader_filters>
                </writer_resource_limits>
            </datawriter_qos>
            
            <datareader_qos>
                <!-- Strict reliable -->
                <reliability>
                    <kind>RELIABLE_RELIABILITY_QOS</kind>
                    <max_blocking_time>
                        <sec>10</sec>
                        <nanosec>0</nanosec>
                    </max_blocking_time>
                </reliability>
                
                <history>
                    <kind>KEEP_ALL_HISTORY_QOS</kind>
                </history>
                
                <!-- These are typical protocol parameters for a reliable
                     DataReader -->
                <protocol>
                    <rtps_reliable_reader>
                        <max_heartbeat_response_delay>
                            <sec>0</sec>
                            <nanosec>0</nanosec>
                        </max_heartbeat_response_delay>
                        <min_heartbeat_response_delay>
                            <sec>0</sec>
                            <nanosec>0</nanosec>
                        </min_heartbeat_response_delay>
                    </rtps_reliable_reader>
                </protocol>
                
            </datareader_qos>
            
        </qos_profile>
    
        <!-- This is the profile used by the Requester. 
             It inherits from "default", defined above, 
             and overrides some QoS -->
        <qos_profile name="RequesterExampleProfile" 
                     base_name="default">

            <!-- QoS for the data writer that sends requests -->
            <datawriter_qos>
                <durability>
                    <kind>TRANSIENT_LOCAL_DURABILITY_QOS</kind>
                </durability>
            </datawriter_qos>

            <!-- QoS for the data reader that receives replies -->
            <datareader_qos>
                <durability>
                    <kind>VOLATILE_DURABILITY_QOS</kind>
                </durability>
            </datareader_qos>
        </qos_profile>

        <!-- This is the profile used by the Replier. 
             It inherits from "default", defined above, 
             and overrides some QoS -->
        <qos_profile name="ReplierExampleProfile"
                     base_name="default">
        
            <!-- QoS for the data writer that sends replies -->
            <datawriter_qos>
                <durability>
                    <kind>VOLATILE_DURABILITY_QOS</kind>
                </durability>
            </datawriter_qos>

            <!-- QoS for the data reader that receives requests -->
            <datareader_qos>
                <durability>
                    <kind>TRANSIENT_LOCAL_DURABILITY_QOS</kind>
                </durability>
            </datareader_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 connext::Requester using this profile.

See Also

Creating a Requester with optional parameters

Configuring QoS Profiles with XML