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

• Correlation between requests and replies

Replier: receiving requests and sending replies

• SimpleReplier example

• Basic Replier example

• Taking loaned samples

Creating a Requester

• Setting up a participant

• Instantiate the declaration of a FooBarRequester, a requester that sends requests of type Foo and receives replies of type Bar (for example, in FooBarRequester.h)

  /* Instantiate the FooBarRequester structure and declare its functions, for
   * example in a file named FooBarRequester.h
   *
   * The request type is Foo
   * The reply type is Bar
   * The name of the requester struct and prefix for the operations is FooBarRequester
   *
   */
  RTI_CONNEXT_REQUESTER_DECL(Foo, Bar, FooBarRequester)

• Instantiate the implementation of a FooBarRequester (for example, in FooBarRequester.c)

  /* Instantiate the implementation of the FooBarRequester functions,
   * for example in a file named FooBarRequester.c.
   *
   *
   */
  #define TReq Foo
  #define TRep Bar
  #define TRequester FooBarRequester
  #include "connext_c/generic/connext_c_requestreply_TReqTRepRequester.gen"

• Create a Requester

  
      DDS_DomainParticipant * participant;
      FooBarRequester * requester;
  
      /* Create a DomainParticipant */
      participant = DDS_DomainParticipantFactory_create_participant(
              DDS_DomainParticipantFactory_get_instance(),
              domain_id, &DDS_PARTICIPANT_QOS_DEFAULT,
              NULL, DDS_STATUS_MASK_NONE);
  
      if (participant == NULL) {
          printf("Error creating participant\n");
      }
  
      /* Create a Requester */
      requester = FooBarRequester_create(participant, "TestService");
  
      if (requester == NULL) {
          printf("Error creating requester\n");
      }
  

Creating a Requester with optional parameters

• Setting up a participant

• Creating a Requester with optional parameters

  
      DDS_DomainParticipant * participant;
      FooBarRequester * requester;
      struct RTI_Connext_RequesterParams params =
          RTI_Connext_RequesterParams_INITIALIZER;
  
      /* Create a DomainParticipant */
      participant = DDS_DomainParticipantFactory_create_participant(
              DDS_DomainParticipantFactory_get_instance(),
              domain_id, &DDS_PARTICIPANT_QOS_DEFAULT,
              NULL, DDS_STATUS_MASK_NONE);
  
      if (participant == NULL) {
          printf("Error creating participant\n");
      }
  
      /* Set the parameters */
  
      /* The participant is always required */
      params.participant = participant;
      /* The service name is required, or alternatively
         params.request_topic_name and params.reply_topic_name can be used */
      params.service_name = (char *) "TestService";
      /* Create a Requester with a QoS profile (located for example in
         USER_QOS_PROFILES.xml, in the current working directory) */
      params.qos_library_name = (char *) "RequestReplyExampleProfiles";
      params.qos_profile_name = (char *) "RequesterExampleProfile";
  
      /* Create a Requester */
      requester = FooBarRequester_create_w_params(&params);
  
      if (requester == NULL) {
          printf("Error creating requester\n");
      }
  

  See Also

  Creating a Requester

  Configuring Request-Reply QoS profiles

Basic Requester example

• Creating a Requester
• Creating a Requester with optional parameters

• Basic Requester example

      DDS_ReturnCode_t retcode;
  
      Foo * request;
      Bar * reply;
      struct DDS_SampleInfo info;
  
      /* Note: error checking omitted for simplicity */
  
      /* Send request */
      request = FooTypeSupport_create_data();
      strcpy(request->message, "A Request");
  
      retcode = FooBarRequester_send_request(requester, request);
  
      /* Receive reply (wait for it and get the sample) */
      reply = BarTypeSupport_create_data();
  
      retcode = FooBarRequester_receive_reply(requester, reply, &info, &MAX_WAIT);
  
      if (retcode == DDS_RETCODE_OK) {
          if(info.valid_data) {
              printf("Received reply: %s\n", reply->message);
          } else {
              printf("Received invalid reply\n");
          }
      } else if (retcode == DDS_RETCODE_TIMEOUT || retcode == DDS_RETCODE_NO_DATA){
          printf("Reply not received\n");
      } else {
          printf("Error receiving reply\n");
      }
  
      /* Delete the samples */
      FooTypeSupport_delete_data(request);
      BarTypeSupport_delete_data(reply);
  

  See Also

  Basic Replier example

  SimpleReplier example

Taking loaned samples

• Creating a Requester

• Get iterator to loaned replies (no copies)

      int i;
      DDS_ReturnCode_t retcode;
  
      struct BarSeq replies = DDS_SEQUENCE_INITIALIZER;
      struct DDS_SampleInfoSeq infos = DDS_SEQUENCE_INITIALIZER;
  
      /* 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)
      */
      retcode = FooBarRequester_take_replies(
          requester, &replies, &infos, DDS_LENGTH_UNLIMITED);
  
      if (retcode == DDS_RETCODE_NO_DATA) {
          printf("No replies are available\n");
          return;
      } else if (retcode != DDS_RETCODE_OK) {
          printf("Error getting replies\n");
          return;
      }
  
      for (i = 0; i < BarSeq_get_length(&replies); i++) {
          Bar * reply = BarSeq_get_reference(&replies, i);
          struct DDS_SampleInfo * info = DDS_SampleInfoSeq_get_reference(&infos, i);
  
          if (info->valid_data) {
              printf("Received reply: %s\n", reply->message);
          }
      }
  
      /* Return the loan */
      FooBarRequester_return_loan(requester, &replies, &infos);
  

  See Also

  Basic Requester example

  Basic Replier example

Correlating requests and replies

• Creating a Requester

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

  
      DDS_ReturnCode_t retcode;
  
      Foo * request;
      struct DDS_WriteParams_t request_info1 = DDS_WRITEPARAMS_DEFAULT;
      struct DDS_WriteParams_t request_info2 = DDS_WRITEPARAMS_DEFAULT;
  
      Bar * reply;
      struct DDS_SampleInfo reply_info;
      struct DDS_SampleIdentity_t related_sample_id;
  
      /* Note: error checking omitted for simplicity */
  
      request = FooTypeSupport_create_data();
  
      /* Send first request */
      strcpy(request->message, "Request 1");
      FooBarRequester_send_request_w_params(requester, request, &request_info1);
  
      /* Send second request */
      strcpy(request->message, "Request 2");
      FooBarRequester_send_request_w_params(requester, request, &request_info2);
  
      /* Wait for one reply to the second request */
      retcode = RTI_Connext_Requester_wait_for_replies_for_related_request(
          (RTI_Connext_Requester *) requester, 1, &MAX_WAIT,
          &request_info2.identity);
  
      if (retcode != DDS_RETCODE_OK) {
          printf("Did not receive reply for request 2\n");
          return;
      }
  
      /* Take that reply */
      reply = BarTypeSupport_create_data();
      retcode = FooBarRequester_take_reply_for_related_request(
          requester, reply, &reply_info, &request_info2.identity);
  
      /* This postcondition should always be true */
      DDS_SampleInfo_get_related_sample_identity(&reply_info, &related_sample_id);
      if (!DDS_SampleIdentity_equals(&related_sample_id, &request_info2.identity)) {
          printf("postcondition failed\n");
      }
  
      if (reply_info.valid_data) {
          printf("Received reply for request 2: %s\n", reply->message);
      }
  
      /* Wait for one reply to the second request */
      retcode = RTI_Connext_Requester_wait_for_replies_for_related_request(
          (RTI_Connext_Requester *) requester, 1, &MAX_WAIT,
          &request_info1.identity);
  
      if (retcode != DDS_RETCODE_OK) {
          printf("Did not receive reply for request 1\n");
          return;
      }
  
      /* Take that reply */
      retcode = FooBarRequester_take_reply_for_related_request(
          requester, reply, &reply_info, &request_info1.identity);
  
      /* This postcondition should always be true */
      DDS_SampleInfo_get_related_sample_identity(&reply_info, &related_sample_id);
      if (!DDS_SampleIdentity_equals(&related_sample_id, &request_info1.identity)) {
          printf("postcondition failed\n");
      }
  
      if (reply_info.valid_data) {
          printf("Received reply for request 1: %s\n", reply->message);
      }
  
      FooTypeSupport_delete_data(request);
      BarTypeSupport_delete_data(reply);
  

• Example 2) Correlate reply after receiving it

      int i;
      DDS_ReturnCode_t retcode;
  
      Foo * request;
      struct DDS_WriteParams_t request_info1 = DDS_WRITEPARAMS_DEFAULT;
      struct DDS_WriteParams_t request_info2 = DDS_WRITEPARAMS_DEFAULT;
  
      struct BarSeq replies = DDS_SEQUENCE_INITIALIZER;
      struct DDS_SampleInfoSeq infos = DDS_SEQUENCE_INITIALIZER;
      struct DDS_SampleIdentity_t related_sample_id;
  
      /* Note: error checking omitted for simplicity */
  
      request = FooTypeSupport_create_data();
  
      /* Send first request */
      strcpy(request->message, "Request 1");
      FooBarRequester_send_request_w_params(requester, request, &request_info1);
  
      /* Send second request */
      strcpy(request->message, "Request 2");
      FooBarRequester_send_request_w_params(requester, request, &request_info2);
  
      /* Wait for two replies. In this case we don't mind the reception order */
      retcode = RTI_Connext_Requester_wait_for_replies(
          (RTI_Connext_Requester *) requester, 2, &MAX_WAIT);
  
      if (retcode != DDS_RETCODE_OK) {
          printf("Replies not received\n");
          return;
      }
  
      retcode = FooBarRequester_take_replies(
          requester, &replies, &infos, DDS_LENGTH_UNLIMITED);
  
      for (i = 0; i < BarSeq_get_length(&replies); i++) {
          Bar * reply = BarSeq_get_reference(&replies, i);
          struct DDS_SampleInfo * info = DDS_SampleInfoSeq_get_reference(&infos, i);
          DDS_SampleInfo_get_related_sample_identity(info, &related_sample_id);
  
          if (DDS_SampleIdentity_equals(&related_sample_id, &request_info1.identity)) {
              printf("Received reply for request 1: %s\n", reply->message);
          } else if (DDS_SampleIdentity_equals(&related_sample_id, &request_info2.identity)) {
              printf("Received reply for request 2: %s\n", reply->message);
          } else {
              /* Should not happen */
              printf("Received unexpected reply\n");
          }
      }
  
      /* Return the loan */
      FooBarRequester_return_loan(requester, &replies, &infos);
  
      FooTypeSupport_delete_data(request);
  

  See Also

  Basic Requester example

  Basic Replier example

Creating a Replier

• Setting up a participant

• Instantiate the declaration of a FooBarReplier, a replier that receives requests of type Foo and sends replies of type Bar (for example, in FooBarReplier.h)

  /* Instantiate the FooBarReplier structure and declare its functions, for
   * example in a file named FooBarReplier.h
   *
   * The request type is Foo
   * The reply type is Bar
   * The name of the replier struct and prefix for the operations is FooBarReplier
   */
  RTI_CONNEXT_REPLIER_DECL(Foo, Bar, FooBarReplier)

• Instantiate the implementation of a FooBarReplier (for example, in FooBarReplier.c)

  /* Instantiate the implementation of the FooBarReplier functions,
   * for example in a file named FooBarReplier.c.
   *
   *
   */
  #define TReq Foo
  #define TRep Bar
  #define TReplier FooBarReplier
  #include "connext_c/generic/connext_c_requestreply_TReqTRepReplier.gen"

• Create a Replier

  
      DDS_DomainParticipant * participant;
      FooBarReplier * replier;
  
      /* Create a DomainParticipant */
      participant = DDS_DomainParticipantFactory_create_participant(
              DDS_DomainParticipantFactory_get_instance(),
              domain_id, &DDS_PARTICIPANT_QOS_DEFAULT,
              NULL, DDS_STATUS_MASK_NONE);
  
      if (participant == NULL) {
          printf("Error creating participant\n");
      }
  
      /* Create a Replier */
      replier = FooBarReplier_create(participant, "TestService");
  
      if (replier == NULL) {
          printf("Error creating replier\n");
      }
  

Basic Replier example

• Creating a Replier

• Basic Replier example

      DDS_ReturnCode_t retcode;
  
      Foo * request;
      Bar * reply;
      struct DDS_SampleInfo request_info;
      struct DDS_SampleIdentity_t request_id;
  
      /* Note: error checking omitted for simplicity */
  
      /* Receive one request */
      request = FooTypeSupport_create_data();
  
      retcode = FooBarReplier_receive_request(
          replier, request, &request_info, &MAX_WAIT);
  
      if (retcode != DDS_RETCODE_OK) {
          printf("Request not received\n");
          FooTypeSupport_delete_data(request);
          return 0;
      }
  
      if (request_info.valid_data) {
          reply = BarTypeSupport_create_data();
          sprintf(reply->message, "Reply for %s", request->message);
  
          /* Send a reply for that request */
          DDS_SampleInfo_get_sample_identity(&request_info, &request_id);
          retcode = FooBarReplier_send_reply(replier, reply, &request_id);
  
          /* Note: a replier can send more than one reply for the same request */
  
          BarTypeSupport_delete_data(reply);
      }
  
      FooTypeSupport_delete_data(request);
  

  See Also

  Basic Requester example

SimpleReplier example

• Instantiate the declaration of a FooBarSimpleReplier, a replier that receives requests of type Foo and sends replies of type Bar (for example, in FooBarSimpleReplier.h)

  /* Instantiate the FooBarSimpleReplier structure and declare its functions, for
   * example in a file named FooBarSimpleReplier.h
   *
   * The request type is Foo
   * The reply type is Bar
   * The name of the simple replier struct and prefix for the operations is
   * FooBarSimpleReplier
   *
   */
  RTI_CONNEXT_SIMPLEREPLIER_DECL(Foo, Bar, FooBarSimpleReplier)

• Instantiate the implementation of a FooBarSimpleReplier (for example, in FooBarSimpleReplier.c)

  /* Instantiate the implementation of the FooBarSimpleReplier functions,
   * for example in a file named FooBarSimpleReplier.c.
   *
   *
   */
  #define TReq Foo
  #define TRep Bar
  #define TSimpleReplier FooBarSimpleReplier
  #include "connext_c/generic/connext_c_requestreply_TReqTRepSimpleReplier.gen"

• Implement a listener

  void * MySimpleReplierListener_on_request_available(
      RTI_Connext_SimpleReplierListener * listener,
      const void * request_untyped, const struct DDS_SampleInfo * info)
  {
      Bar * reply;
      Foo * request = (Foo *) request_untyped;
  
      if (!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;
      }
  
      reply = BarTypeSupport_create_data();
      sprintf(reply->message, "Simple reply for %s", request->message);
  
      return (void *) reply;
  }
  
  void MySimpleReplierListener_on_return_loan(
      RTI_Connext_SimpleReplierListener * listener,
      void * reply)
  {
      /* Delete the data we created on request available
       *
       * Note: we can store a single reply sample in listener->user_data
       *       and reuse it to avoid reserving and deleting memory on every call
       *       to on_request_available/on_return_loan
       */
      BarTypeSupport_delete_data(reply);
  }

• And create a SimpleReplier with the listener:

  
      RTI_Connext_SimpleReplierListener listener;
      FooBarSimpleReplier * replier;
  
      /* Note: error checking omitted for simplicity */
  
      listener.on_request_available = MySimpleReplierListener_on_request_available;
      listener.return_loan = MySimpleReplierListener_on_return_loan;
  
      replier = FooBarSimpleReplier_create(participant, "TestService", &listener);
  
      /* After creation the SimpleReplier is already active and may call
         the listener */
  

  See Also

  Basic Requester example

Configuring Request-Reply QoS profiles

If you do not specify your own quality of service parameters (in RTI_Connext_RequesterParams and RTI_Connext_ReplierParams), a FooBarRequester and FooBarReplier 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/qos_profiles_5.0.0/schema/rti_dds_qos_profiles.xsd"
    version="5.0.0">

    <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 FooBarRequester using this profile.

See Also

Creating a Requester with optional parameters

Configuring QoS Profiles with XML