RTI Connext Modern C++ API  Version 6.0.1
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
rti::request::Replier< RequestType, ReplyType > Class Template Reference

<<reference-type>> Allows receiving requests and sending replies More...

#include <rti/request/Replier.hpp>

Inheritance diagram for rti::request::Replier< RequestType, ReplyType >:
dds::core::Reference< detail::ReplierImpl< RequestType, ReplyType > >

Public Member Functions

 Replier (dds::domain::DomainParticipant participant, const std::string &service_name)
 Creates a Replier with the minimum set of parameters.
 
 Replier (const ReplierParams &params)
 Creates a Replier with parameters.
 
 Replier (const ReplierParams &params, Listener *the_listener)
 Creates a replier with additional parameters and a listener.
 
void send_reply (const ReplyType &reply, const rti::core::SampleIdentity &related_request_id)
 Sends a reply for a previous request.
 
void send_reply (const ReplyType &reply, const dds::sub::SampleInfo &related_request_info)
 Sends a reply.
 
void send_reply (const ReplyType &reply, rti::pub::WriteParams &params)
 Sends a reply with advanced parameters.
 
bool wait_for_requests (const dds::core::Duration &max_wait)
 Waits for requests.
 
bool wait_for_requests (int min_count, const dds::core::Duration &max_wait)
 Waits for requests.
 
dds::sub::LoanedSamples
< RequestType > 
receive_requests (const dds::core::Duration &max_wait)
 Waits for multiple requests and provides a loaned container to access them.
 
dds::sub::LoanedSamples
< RequestType > 
receive_requests (int min_count, const dds::core::Duration &max_wait)
 Waits for multiple requests and provides a loaned container to access them.
 
dds::sub::LoanedSamples
< RequestType > 
take_requests ()
 Takes all the requests.
 
dds::sub::LoanedSamples
< RequestType > 
read_requests ()
 Reads all the requests.
 
Listenerlistener () const
 Sets a ReplierListener.
 
void listener (Listener *the_listener, const dds::core::status::StatusMask &=dds::core::status::StatusMask::none())
 Sets a ReplierListener.
 
dds::sub::DataReader< RequestType > request_datareader () const
 Retrieves the underlying dds::sub::DataReader.
 
dds::pub::DataWriter< ReplyType > reply_datawriter () const
 Retrieves the underlying dds::pub::DataWriter.
 

Detailed Description

template<typename RequestType, typename ReplyType>
class rti::request::Replier< RequestType, ReplyType >

<<reference-type>> Allows receiving requests and sending replies

Note
A Replier provides all the functions of a <<reference-type>> except close() and retain().

A Replier is an entity with two associated topics: a request topic and a reply topic. It can receive requests by subscribing to the request topic and can send replies to those requests by publishing the reply topic.

Valid types for these topics are: those generated by the rtiddsgen code generator, the DDS built-in types, and dds::core::xtypes::DynamicData. See Creating a Replier.

A Replier has four main types of operations:

  • Waiting for requests to be received from the middleware
  • Getting those requests
  • Receiving requests (a convenience operation that is a combination of waiting and getting in a single operation)
  • Sending a reply for a previously received request (i.e., publishing a reply sample on the reply topic with special meta-data so that the orignal Requester can identify it)

For multi-reply scenarios in which a rti::request::Replier generates more than one reply for a request, the rti::request::Replier should mark all the intermediate replies (all but the last) using the rti::core::SampleFlag::intermediate_reply_sequence flag in rti::pub::WriteParams::flag.

Much like a Requester, a Replier has an associated dds::domain::DomainParticipant, which can be shared with other Repliers or RTI Connext routines. All the other entities required for the request-reply interaction, including a dds::pub::DataWriter for writing replies and a dds::sub::DataReader for reading requests, are automatically created when the Replier is constructed.

Quality of Service for the underlying DataWriter and DataReader can be configured (see RequesterParams::qos_profile). By default, they are created with dds::core::policy::ReliabilityKind::RELIABLE. The exact default configuration is described here: Configuring Request-Reply QoS profiles

There are several ways to use a Replier:

Template Parameters
RequestTypeThe data type for the request topic
ReplyTypeThe data type for the reply topic
See Also
rti::request::Requester
Request-Reply Examples
Basic Replier example

Constructor & Destructor Documentation

template<typename RequestType, typename ReplyType>
rti::request::Replier< RequestType, ReplyType >::Replier ( dds::domain::DomainParticipant  participant,
const std::string &  service_name 
)
inline

Creates a Replier with the minimum set of parameters.

Parameters
participantThe DomainParticipant that this Replier uses to join a domain.
service_nameThe service name. See ReplierParams::service_name
Exceptions
Oneof the Standard Exceptions
template<typename RequestType, typename ReplyType>
rti::request::Replier< RequestType, ReplyType >::Replier ( const ReplierParams params)
inlineexplicit

Creates a Replier with parameters.

Parameters
paramsAll the parameters that configure this Replier
Exceptions
Oneof the Standard Exceptions
See Also
ReplierParams
Creating a Replier
template<typename RequestType, typename ReplyType>
rti::request::Replier< RequestType, ReplyType >::Replier ( const ReplierParams params,
Listener the_listener 
)
inline

Creates a replier with additional parameters and a listener.

Parameters
paramsAll the parameters that configure this Replier
the_listenerA ReplierListener that notifies when new requests are available. Cannot be NULL.
Note
The listener must be reset with this->listener(NULL) before this object can be destroyed. Alternatively, create the Replier and then use rti::core::bind_listener() to have it automatically reset.

Member Function Documentation

template<typename RequestType, typename ReplyType>
void rti::request::Replier< RequestType, ReplyType >::send_reply ( const ReplyType &  reply,
const rti::core::SampleIdentity related_request_id 
)
inline

Sends a reply for a previous request.

The related request identity can be retrieved from an existing request sample (Sample).

Parameters
replyThe reply to be sent.
related_request_idThe identity of a previously received request
Exceptions
Oneof the Standard Exceptions
See Also
Sample::identity
rti::request::Replier::receive_requests
rti::request::Replier::take_requests
Basic Replier example
template<typename RequestType, typename ReplyType>
void rti::request::Replier< RequestType, ReplyType >::send_reply ( const ReplyType &  reply,
const dds::sub::SampleInfo related_request_info 
)
inline

Sends a reply.

This operation obtains the related_request_id from a request SampleInfo, that is, it's equivalent to send_reply(reply, related_request_info->original_publication_virtual_sample_identity())

template<typename RequestType, typename ReplyType>
void rti::request::Replier< RequestType, ReplyType >::send_reply ( const ReplyType &  reply,
rti::pub::WriteParams params 
)
inline

Sends a reply with advanced parameters.

Parameters
replyThe reply to be sent
params(in-out) The parameters to write the reply (see ).
Precondition
params.related_sample_identity() must be set with the related request SampleIdentity.

Other parameters to customize are discussed in dds::pub::DataWriter::write(const T&,rti::pub::WriteParams&). In particular, rti::pub::WriteParams::flag can be set to rti::core::SampleFlag::intermediate_reply_sequence to inform the Requester application that this reply will be followed by additional replies to the same request. The Requester can access the flag in dds::sub::SampleInfo::flag() when it receives the reply.

template<typename RequestType, typename ReplyType>
bool rti::request::Replier< RequestType, ReplyType >::wait_for_requests ( const dds::core::Duration max_wait)
inline

Waits for requests.

Equivalent to rti::request::Replier::wait_for_requests with min_count=1

See Also
rti::request::Replier::wait_for_requests
template<typename RequestType, typename ReplyType>
bool rti::request::Replier< RequestType, ReplyType >::wait_for_requests ( int  min_count,
const dds::core::Duration max_wait 
)
inline

Waits for requests.

This operation waits for min_count requests to be available. It will wait up to max_wait .

This operation is similar to rti::request::Requester::wait_for_replies(int, const dds::core::Duration&).

Parameters
min_countMinimum number of requests that need to be available for this operation to unblock.
max_waitMaximum waiting time after which this operation unblocks regardless of how many requests are available.
Returns
true if at least min_count requests were available before max_wait elapsed, or false otherwise.
See Also
rti::request::Replier::take_requests
rti::request::Requester::wait_for_replies(int, const dds::core::Duration&)
template<typename RequestType, typename ReplyType>
dds::sub::LoanedSamples<RequestType> rti::request::Replier< RequestType, ReplyType >::receive_requests ( const dds::core::Duration max_wait)
inline

Waits for multiple requests and provides a loaned container to access them.

Equivalent to using rti::request::Replier::receive_requests with min_count=1 and max_count=dds::core::LENGTH_UNLIMITED

See Also
dds::sub::LoanedSamples
rti::request::Replier::receive_requests
template<typename RequestType, typename ReplyType>
dds::sub::LoanedSamples<RequestType> rti::request::Replier< RequestType, ReplyType >::receive_requests ( int  min_count,
const dds::core::Duration max_wait 
)
inline
template<typename RequestType, typename ReplyType>
dds::sub::LoanedSamples<RequestType> rti::request::Replier< RequestType, ReplyType >::take_requests ( )
inline

Takes all the requests.

See Also
rti::request::Requester::take_replies
template<typename RequestType, typename ReplyType>
dds::sub::LoanedSamples<RequestType> rti::request::Replier< RequestType, ReplyType >::read_requests ( )
inline

Reads all the requests.

This operation is equivalent to rti::request::Replier::take_requests except the requests remain in the Replier and can be read or taken again.

template<typename RequestType, typename ReplyType>
Listener* rti::request::Replier< RequestType, ReplyType >::listener ( ) const
inline

Sets a ReplierListener.

The listener will be called when new requests are available

template<typename RequestType, typename ReplyType>
void rti::request::Replier< RequestType, ReplyType >::listener ( Listener the_listener,
const dds::core::status::StatusMask = dds::core::status::StatusMask::none() 
)
inline

Sets a ReplierListener.

The listener will be called when new requests are available.

Note
rti::core::bind_listener() is recommended instead of this listener setter. bind_listener() and bind_and_manage_listener() automatically remove the listener, which allows the Replier to be automatically destroyed.

(The second parameter is ignored)

template<typename RequestType, typename ReplyType>
dds::sub::DataReader<RequestType> rti::request::Replier< RequestType, ReplyType >::request_datareader ( ) const
inline

Retrieves the underlying dds::sub::DataReader.

See Also
rti::request::Requester::get_reply_datareader
template<typename RequestType, typename ReplyType>
dds::pub::DataWriter<ReplyType> rti::request::Replier< RequestType, ReplyType >::reply_datawriter ( ) const
inline

Retrieves the underlying dds::pub::DataWriter.

See Also
rti::request::Requester::get_request_datawriter

RTI Connext Modern C++ API Version 6.0.1 Copyright © Sat Nov 23 2019 Real-Time Innovations, Inc