RTI Connext C++ API  Version 5.1.0
connext::Requester< TReq, TRep > Class Template Reference

Allows sending requests and receiving replies. More...

Public Types

typedef TReq Request
 The request type.
 
typedef TRep Reply
 The reply type.
 
typedef dds_type_traits< TReq >
::DataWriter 
RequestDataWriter
 The typed DataWriter for type TReq.
 
typedef dds_type_traits< TRep >
::DataReader 
ReplyDataReader
 The typed DataReader for type TRep.
 
typedef dds_type_traits< TReq >
::TypeSupport 
RequestTypeSupport
 The type support for type TReq.
 
typedef dds_type_traits< TRep >
::TypeSupport 
ReplyTypeSupport
 The type support for type TRep.
 

Public Member Functions

 Requester (DDSDomainParticipant *participant, const std::string &service_name)
 Creates a Requester with the minimum set of parameters.
 
 Requester (const RequesterParams &params)
 Creates a Requester with parameters.
 
virtual ~Requester ()
 Releases the internal entities created by this object.
 
template<typename UReq >
void send_request (const UReq &request)
 Sends a request.
 
template<typename UReq >
void send_request (WriteSample< UReq > &request)
 Sends a request and gets back information about it that allows correlation with future replies.
 
template<typename UReq >
void send_request (WriteSampleRef< UReq > &request)
 Sends a request and gets back information about it that allows correlation with future replies.
 
bool receive_reply (Sample< TRep > &reply, const DDS_Duration_t &timeout)
 Waits for a reply and copies its contents into a Sample.
 
bool receive_reply (SampleRef< TRep > reply, const DDS_Duration_t &timeout)
 Waits for a reply and copies its contents into a SampleRef.
 
LoanedSamples< TRep > receive_replies (const DDS_Duration_t &max_wait)
 Waits for multiple replies and provides a loaned container to access them.
 
LoanedSamples< TRep > receive_replies (int min_count, int max_count, const DDS_Duration_t &max_wait)
 Waits for multiple replies and provides a loaned container to access them.
 
bool wait_for_replies (int min_count, const DDS_Duration_t &max_wait)
 Waits for replies to any request.
 
bool wait_for_replies (const DDS_Duration_t &max_wait)
 Waits for replies to any request.
 
bool wait_for_replies (int min_count, const DDS_Duration_t &max_wait, const SampleIdentity_t &related_request_id)
 Waits for replies to a specific request.
 
bool take_reply (Sample< TRep > &reply)
 Copies the contents of a reply into a Sample.
 
bool take_reply (SampleRef< TRep > reply)
 Copies the contents of a reply into a SampleRef.
 
LoanedSamples< TRep > take_replies (int max_count=DDS_LENGTH_UNLIMITED)
 Provides a loaned container to access the existing replies.
 
bool take_reply (Sample< TRep > &reply, const SampleIdentity_t &related_request_id)
 Copies the contents of a reply for a specific request.
 
bool take_reply (SampleRef< TRep > reply, const SampleIdentity_t &related_request_id)
 Copies the contents of a reply for a specific request.
 
LoanedSamples< TRep > take_replies (int max_count, const SampleIdentity_t &related_request_id)
 Provides a loaned container to access the existing replies for a specific request.
 
LoanedSamples< TRep > take_replies (const SampleIdentity_t &related_request_id)
 Provides a loaned container to access the existing replies for a specific request.
 
bool read_reply (Sample< TRep > &reply)
 Copies the contents of a reply into a Sample.
 
bool read_reply (SampleRef< TRep > reply)
 Copies the contents of a reply into a SampleRef.
 
LoanedSamples< TRep > read_replies (int max_count=DDS_LENGTH_UNLIMITED)
 Provides a loaned container to access the existing replies.
 
bool read_reply (Sample< TRep > &reply, const SampleIdentity_t &related_request_id)
 Copies the contents of a reply for a specific request.
 
bool read_reply (SampleRef< TRep > reply, const SampleIdentity_t &related_request_id)
 Copies the contents of a reply for a specific request.
 
LoanedSamples< TRep > read_replies (int max_count, const SampleIdentity_t &related_request_id)
 Provides a loaned container to access the existing replies for a specific request.
 
LoanedSamples< TRep > read_replies (const SampleIdentity_t &related_request_id)
 Provides a loaned container to access the existing replies for a specific request.
 
RequestDataWriterget_request_datawriter ()
 Retrieves the underlying DDSDataWriter.
 
ReplyDataReaderget_reply_datareader ()
 Retrieves the underlying DDSDataReader.
 

Detailed Description

template<typename TReq, typename TRep>
class connext::Requester< TReq, TRep >

Allows sending requests and receiving replies.

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

Valid types for these topics (TReq and TRep) are: those generated by the rtiddsgen code generator, the DDS built-in types, and DynamicData.

For example:

using namespace connext;
Requester<Foo, Bar> requester(...);

A Replier and a Requester communicate when they use the same topics for requests and replies (see connext::RequesterParams::service_name) on the same domain.

A Requester can send requests and receive replies. It does that using the following operations:

  • Sending requests (i.e. publishing request samples on the request topic)
  • Waiting for replies to be received by the middleware (for any request or for a specific request)
  • Getting those replies from the middleware. There are two ways to do this: take (the data samples are removed from the middleware), read (the data samples remain in the middleware and can be read or taken again).
  • A convenience operation, receive (which is a combination of wait and take).

In all cases, the middleware guarantees that a requester only receives reply samples that are associated with that requests that it sends.

A requester has an associated DDSDomainParticipant, which can be shared with other requesters or RTI Connext routines. All the other RTI Connext entities required for the request-reply interaction, including a DDSDataWriter for writing requests and a DDSDataReader for reading replies, are automatically created when the requester is constructed.

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

Template Parameters
TReqThe data type for the request topic
TRepThe data type for the reply topic
See Also
connext::Replier
Request-Reply Examples
Basic Requester example

Member Typedef Documentation

template<typename TReq, typename TRep>
typedef TReq connext::Requester< TReq, TRep >::Request

The request type.

template<typename TReq, typename TRep>
typedef TRep connext::Requester< TReq, TRep >::Reply

The reply type.

template<typename TReq, typename TRep>
typedef dds_type_traits<TReq>::DataWriter connext::Requester< TReq, TRep >::RequestDataWriter

The typed DataWriter for type TReq.

template<typename TReq, typename TRep>
typedef dds_type_traits<TRep>::DataReader connext::Requester< TReq, TRep >::ReplyDataReader

The typed DataReader for type TRep.

template<typename TReq, typename TRep>
typedef dds_type_traits<TReq>::TypeSupport connext::Requester< TReq, TRep >::RequestTypeSupport

The type support for type TReq.

template<typename TReq, typename TRep>
typedef dds_type_traits<TRep>::TypeSupport connext::Requester< TReq, TRep >::ReplyTypeSupport

The type support for type TRep.

Constructor & Destructor Documentation

template<typename TReq , typename TRep >
connext::Requester< TReq, TRep >::Requester ( DDSDomainParticipant participant,
const std::string &  service_name 
)

Creates a Requester with the minimum set of parameters.

Parameters
participantThe DomainParticipant this requester uses to join a DDS domain
service_nameThe service name. See connext::RequesterParams::service_name
Exceptions
Oneof the RTI Connext Exceptions
template<typename TReq , typename TRep >
connext::Requester< TReq, TRep >::Requester ( const RequesterParams params)
explicit

Creates a Requester with parameters.

Parameters
paramsAll the parameters that configure this requester. See connext::RequesterParams for the list of mandatory parameters.
Exceptions
Oneof the RTI Connext Exceptions
See Also
connext::RequesterParams
Requester Creation
template<typename TReq , typename TRep >
connext::Requester< TReq, TRep >::~Requester ( )
virtual

Releases the internal entities created by this object.

Among other internal resources, it deletes the underlying DataReader and DataWriter.

See Also
DDSSubscriber::delete_datareader
DDSPublisher::delete_datawriter

Member Function Documentation

template<typename TReq , typename TRep >
template<typename UReq >
void connext::Requester< TReq, TRep >::send_request ( const UReq &  request)

Sends a request.

If a future reply needs to be correlated to exactly this request, use connext::Requester::send_request(WriteSample<UReq>&).

Parameters
requestThe request to be sent
Exceptions
Oneof the RTI Connext Exceptions
MT Safety:
SAFE
See Also
send_request(WriteSample<UReq>&)
template<typename TReq , typename TRep >
template<typename UReq >
void connext::Requester< TReq, TRep >::send_request ( WriteSample< UReq > &  request)

Sends a request and gets back information about it that allows correlation with future replies.

After calling this operation, the sample contains a valid identity that can be used for correlation with future replies.

See example code in Correlating requests and replies.

Parameters
request<<inout>> Contains the request and optional write parameters. When this call ends succesfully, connext::WriteSample contains a valid identity that can be used for correlation with future replies.
Exceptions
Oneof the RTI Connext Exceptions ; connext::TimeoutException may be reported in the same conditions as in FooDataWriter::write.
MT Safety:
SAFE
See Also
connext::WriteSample::identity()
wait_for_replies(int, const Duration_t&, const SampleIdentity_t&)
take_replies(int, const SampleIdentity_t&)
Correlating requests and replies
template<typename TReq , typename TRep >
template<typename UReq >
void connext::Requester< TReq, TRep >::send_request ( WriteSampleRef< UReq > &  request)

Sends a request and gets back information about it that allows correlation with future replies.

This operation is equivalent to connext::Requester::send_request(WriteSample<UReq>&) except it uses a WriteSampleRef.

A WriteSampleRef needs to be initialized with references to existing data and info objects before it can be used. See an example here: Basic Requester example using SampleRef

See Also
connext::Requester::send_request(WriteSample<UReq>&)
Basic Requester example using SampleRef
template<typename TReq , typename TRep >
bool connext::Requester< TReq, TRep >::receive_reply ( Sample< TRep > &  reply,
const DDS_Duration_t timeout 
)
inline
template<typename TReq , typename TRep >
bool connext::Requester< TReq, TRep >::receive_reply ( SampleRef< TRep >  reply,
const DDS_Duration_t timeout 
)
inline
template<typename TReq , typename TRep >
LoanedSamples< TRep > connext::Requester< TReq, TRep >::receive_replies ( const DDS_Duration_t max_wait)

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

This operation is equivalent to using receive_replies(int,int,const Duration_t&) with min_count=1 and max_count=DDS_LENGTH_UNLIMITED

MT Safety:
See wait_for_replies(int, const Duration_t&)
See Also
connext::LoanedSamples
receive_replies(int,int,const Duration_t&)
template<typename TReq , typename TRep >
LoanedSamples< TRep > connext::Requester< TReq, TRep >::receive_replies ( int  min_count,
int  max_count,
const DDS_Duration_t max_wait 
)

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

This operation is equivalent to using wait_for_replies(int, const Duration_t&) and take_replies(int).

MT Safety:
See wait_for_replies(int, const Duration_t&)
Exceptions
Oneof the RTI Connext Exceptions
See Also
connext::LoanedSamples
wait_for_replies(int, const Duration_t&)
take_replies(int)
template<typename TReq , typename TRep >
bool connext::Requester< TReq, TRep >::wait_for_replies ( int  min_count,
const DDS_Duration_t max_wait 
)

Waits for replies to any request.

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

If this operation is called several times but the available replies are not taken (with take_replies(int)), this operation may return immediately and will not wait for new replies. New replies may replace existing ones if they are not taken, depending on the DDS_HistoryQosPolicy used to configure this Requester.

Parameters
min_countMinimum number of replies that need to be available for this operation to unblock.
max_waitMaximum waiting time after which this operation unblocks, regardless of how many replies are available.
Returns
true if at least min_count replies were available before max_wait elapsed, or false otherwise.
MT Safety:
Concurrent calls to this operation on the same object are not allowed. However, waiting for replies for specific requests in parallel is supported (see wait_for_replies(int, const Duration_t&, const SampleIdentity_t&)).
See Also
take_replies(int)
template<typename TReq , typename TRep >
bool connext::Requester< TReq, TRep >::wait_for_replies ( const DDS_Duration_t max_wait)

Waits for replies to any request.

This operation is equivalent to using wait_for_replies(int, const Duration_t&) with min_count=1.

See Also
wait_for_replies(int, const Duration_t&)
template<typename TReq , typename TRep >
bool connext::Requester< TReq, TRep >::wait_for_replies ( int  min_count,
const DDS_Duration_t max_wait,
const SampleIdentity_t related_request_id 
)

Waits for replies to a specific request.

This operation is analogous to wait_for_replies(int, const Duration_t&) except this operation waits for replies for a specific request.

Parameters
min_countMinimum number of replies for the related request that need to be available for this operation to unblock.
max_waitMaximum wait time after which this operation unblocks, regardless of how many replies are available.
related_request_idThe identity of a request previously sent by this Requester
Returns
true if at least min_count replies for the related request were available before max_wait elapsed, or false otherwise.
Exceptions
Oneof the RTI Connext Exceptions
MT Safety:
SAFE
See Also
wait_for_replies(int, const Duration_t&)
template<typename TReq , typename TRep >
bool connext::Requester< TReq, TRep >::take_reply ( Sample< TRep > &  reply)
inline

Copies the contents of a reply into a Sample.

Takes a reply sample from the Requester and makes a copy.

This operation may be used after a call to wait_for_replies(int, const Duration_t&).

To avoid copies, you can use take_replies(int).

Parameters
replyThe sample where the reply data and the related SampleInfo are copied
Returns
true if there was a reply to get. If this operation returns false, the contents of reply remain unchanged, except DDS_SampleInfo::valid_data becomes false.
Exceptions
Oneof the RTI Connext Exceptions
MT Safety:
SAFE
See Also
connext::Sample
wait_for_replies(int, const Duration_t&)
template<typename TReq , typename TRep >
bool connext::Requester< TReq, TRep >::take_reply ( SampleRef< TRep >  reply)
inline

Copies the contents of a reply into a SampleRef.

This operation is analogous to connext::Requester::take_reply(Sample<TRep>&) except it uses a SampleRef instance.

A SampleRef needs to be initialized with references to existing data and info objects before it can be used. See an example here: Basic Requester example using SampleRef

MT Safety:
SAFE
See Also
connext::SampleRef
take_reply(Sample<TRep>&)
Basic Requester example using SampleRef
template<typename TReq , typename TRep >
LoanedSamples< TRep > connext::Requester< TReq, TRep >::take_replies ( int  max_count = DDS_LENGTH_UNLIMITED)

Provides a loaned container to access the existing replies.

Takes all the existing replies up to max_count and provides a loaned container to access them.

This operation does not make a copy of the data.

The loan is returned with connext::LoanedSamples::return_loan or in the destructor

This operation may be used after a call to wait_for_replies(int, const Duration_t&)

See an example here: Taking loaned samples

Parameters
max_countThe maximum number of samples that are taken at a time. The special value DDS_LENGTH_UNLIMITED may be used. This value will read up to the limit specified by DDS_DataReaderResourceLimitsQosPolicy::max_samples_per_read
Returns
A container with up to max_count elements. May be empty if there were no replies to get.
Exceptions
Oneof the RTI Connext Exceptions
MT Safety:
SAFE
See Also
connext::Sample
connext::LoanedSamples
connext::LoanedSamples::return_loan
wait_for_replies(int, const Duration_t&)
FooDataReader::take (for a more detailed description on how QoS and other parameters affect the underlying DataReader)
Taking loaned samples
Taking samples by copy
template<typename TReq , typename TRep >
bool connext::Requester< TReq, TRep >::take_reply ( Sample< TRep > &  reply,
const SampleIdentity_t related_request_id 
)
inline

Copies the contents of a reply for a specific request.

This operation is analogous to take_reply(Sample<TRep>&) except the reply corresponds to a specific request.

Parameters
replyThe sample where a reply is copied into
related_request_idThe identity of a request previously sent by this Requester
Returns
true if there was a reply to get. If this operation returns false, the contents of reply remain unchanged, except DDS_SampleInfo::valid_data becomes false.
MT Safety:
SAFE
See Also
connext::Sample
take_reply(Sample<TRep>&)
send_request(WriteSample<UReq>&)
Correlating requests and replies
template<typename TReq , typename TRep >
bool connext::Requester< TReq, TRep >::take_reply ( SampleRef< TRep >  reply,
const SampleIdentity_t related_request_id 
)
inline

Copies the contents of a reply for a specific request.

This operation is analogous to connext::Requester::take_reply(Sample<TRep>&, const SampleIdentity_t&) except it uses a SampleRef instance.

A SampleRef needs to be initialized with references to existing data and info objects before it can be used. See an example here: Basic Requester example using SampleRef

MT Safety:
SAFE
See Also
connext::SampleRef
take_reply(SampleRef<TRep>)
take_reply(Sample<TRep>&, const SampleIdentity_t&)
Basic Requester example using SampleRef
Correlating requests and replies
template<typename TReq , typename TRep >
LoanedSamples< TRep > connext::Requester< TReq, TRep >::take_replies ( int  max_count,
const SampleIdentity_t related_request_id 
)

Provides a loaned container to access the existing replies for a specific request.

This operation is analogous to take_replies(int) except the replies this operation provides correspond to a specific request.

Parameters
max_countThe maximum number of samples that are taken at a time. The special value DDS_LENGTH_UNLIMITED may be used.
related_request_idThe identity of a request previously sent by this Requester
MT Safety:
SAFE
See Also
take_replies(int)
connext::LoanedSamples
Taking samples by copy
Correlating requests and replies
template<typename TReq , typename TRep >
LoanedSamples< TRep > connext::Requester< TReq, TRep >::take_replies ( const SampleIdentity_t related_request_id)

Provides a loaned container to access the existing replies for a specific request.

Equivalent to using take_replies(int, const SampleIdentity_t&) with max_count=DDS_LENGTH_UNLIMITED

MT Safety:
SAFE
See Also
connext::LoanedSamples
take_replies(int, const SampleIdentity_t&)
template<typename TReq , typename TRep >
bool connext::Requester< TReq, TRep >::read_reply ( Sample< TRep > &  reply)
inline

Copies the contents of a reply into a Sample.

This operation is equivalent to connext::Requester::take_reply(Sample<TRep>&) except the reply remains in the Requester and can be read or taken again.

template<typename TReq , typename TRep >
bool connext::Requester< TReq, TRep >::read_reply ( SampleRef< TRep >  reply)
inline

Copies the contents of a reply into a SampleRef.

This operation is analogous to connext::Requester::read_reply(Sample<TRep>&) except it uses a SampleRef instance.

A SampleRef needs to be initialized with references to existing data and info objects before it can be used. See an example here: Basic Requester example using SampleRef

MT Safety:
SAFE
See Also
connext::SampleRef
read_reply(Sample<TRep>&)
Basic Requester example using SampleRef
template<typename TReq , typename TRep >
LoanedSamples< TRep > connext::Requester< TReq, TRep >::read_replies ( int  max_count = DDS_LENGTH_UNLIMITED)

Provides a loaned container to access the existing replies.

This operation is equivalent to connext::Requester::take_replies(int) except the replies remain in the Requester and can be read or taken again.

template<typename TReq , typename TRep >
bool connext::Requester< TReq, TRep >::read_reply ( Sample< TRep > &  reply,
const SampleIdentity_t related_request_id 
)
inline

Copies the contents of a reply for a specific request.

This operation is equivalent to connext::Requester::take_reply(Sample<TRep>&, const SampleIdentity_t&) except the reply remains in the Requester and can be read or taken again.

template<typename TReq , typename TRep >
bool connext::Requester< TReq, TRep >::read_reply ( SampleRef< TRep >  reply,
const SampleIdentity_t related_request_id 
)
inline

Copies the contents of a reply for a specific request.

This operation is analogous to connext::Requester::read_reply(Sample<TRep>&, const SampleIdentity_t&) except it uses a SampleRef instance.

A SampleRef needs to be initialized with references to existing data and info objects before it can be used. See an example here: Basic Requester example using SampleRef

MT Safety:
SAFE
See Also
connext::SampleRef
read_reply(SampleRef<TRep>)
read_reply(Sample<TRep>&, const SampleIdentity_t&)
Basic Requester example using SampleRef
Correlating requests and replies
template<typename TReq , typename TRep >
LoanedSamples< TRep > connext::Requester< TReq, TRep >::read_replies ( int  max_count,
const SampleIdentity_t related_request_id 
)

Provides a loaned container to access the existing replies for a specific request.

This operation is equivalent to connext::Requester::take_replies(int, const SampleIdentity_t&) except the replies remain in the Requester and can be read or taken again.

template<typename TReq , typename TRep >
LoanedSamples< TRep > connext::Requester< TReq, TRep >::read_replies ( const SampleIdentity_t related_request_id)

Provides a loaned container to access the existing replies for a specific request.

This operation is equivalent to connext::Requester::take_replies(const SampleIdentity_t&) except the replies remain in the Requester and can be read or taken again.

template<typename TReq , typename TRep >
Requester< TReq, TRep >::RequestDataWriter * connext::Requester< TReq, TRep >::get_request_datawriter ( )
inline

Retrieves the underlying DDSDataWriter.

Accessing the request DataWriter may be useful for a number of advanced use cases, such as:

  • Finding matching subscriptions (e.g., Repliers)
  • Setting a DataWriter listener
  • Getting DataWriter protocol or cache statuses
MT Safety:
SAFE
See Also
DDSDataWriter
FooDataWriter
DDSDataWriter::get_matched_subscriptions
DDSDataWriter::get_matched_subscription_data
DDSDataWriter::set_listener
DDSDataWriter::get_datawriter_protocol_status
template<typename TReq , typename TRep >
Requester< TReq, TRep >::ReplyDataReader * connext::Requester< TReq, TRep >::get_reply_datareader ( )
inline

Retrieves the underlying DDSDataReader.

Accessing the reply DataReader may be useful for a number of advanced use cases, such as:

  • Finding matching publications (e.g., Repliers)
  • Setting a DataReader listener
  • Getting DataReader protocol or cache statuses
MT Safety:
SAFE
See Also
DDSDataReader
FooDataReader
DDSDataReader::get_matched_publications
DDSDataReader::get_matched_publication_data
DDSDataReader::set_listener
DDSDataReader::get_datareader_protocol_status

RTI Connext C++ API Version 5.1.0 Copyright © Mon Feb 3 2014 Real-Time Innovations, Inc