RTI Connext C API Version 6.1.1

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:

Set up

Requester: sending requests and receiving replies

Replier: receiving requests and sending replies

The examples in this section require the following header files:

#include "connext_c/connext_c_requester.h"
#include "connext_c/connext_c_replier.h"
#include "connext_c/connext_c_simple_replier.h"

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

Requester example

Creating a Requester
Creating a Requester with optional parameters
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
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
Requester example

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
Requester example

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");
}

Replier example

Creating a Replier
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
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"
A FooBarSimpleReplier wraps a FooBarReplier, which has to be defined as well. If you haven't already, instantiate the declaration and definition of FooBarReplier as described in Creating a Replier (you can do this in the same .h and .c files you just used for FooBarSimpleReplier).
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
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/schema/rti_dds_qos_profiles.xsd">
    <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