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

#include <rti/request/Requester.hpp>

Inherits dds::core::Reference< DELEGATE >.

Public Member Functions
	Requester (const RequesterParams &params)
	Creates a Requester with parameters.

	Requester (dds::domain::DomainParticipant participant, const std::string &service_name)
	Creates a Requester with the minimum set of parameters.

rti::core::SampleIdentity	send_request (const RequestType &request)
	Sends a request.

void	send_request (const RequestType &request, rti::pub::WriteParams &params)
	Sends a request with advanced parameters.

dds::sub::LoanedSamples < ReplyType >	receive_replies (const dds::core::Duration &max_wait)
	Waits for multiple replies and provides a loaned container to access them.

dds::sub::LoanedSamples < ReplyType >	receive_replies (int min_count, const dds::core::Duration &max_wait)
	Waits for multiple replies and provides a loaned container to access them.

dds::sub::LoanedSamples < ReplyType >	take_replies ()
	Takes all the replies.

dds::sub::LoanedSamples < ReplyType >	take_replies (const rti::core::SampleIdentity &related_request_id)
	Takes the replies for a specific requests.

dds::sub::LoanedSamples < ReplyType >	read_replies ()
	Reads all the replies.

dds::sub::LoanedSamples < ReplyType >	read_replies (const rti::core::SampleIdentity &related_request_id)
	Reads the replies for a specific request.

bool	wait_for_replies (const dds::core::Duration &max_wait)
	Waits for replies to any request.

bool	wait_for_replies (int min_count, const dds::core::Duration &max_wait)
	Waits for replies to any request.

bool	wait_for_replies (int min_count, const dds::core::Duration &max_wait, const rti::core::SampleIdentity &related_request_id)
	Waits for replies to a specific request.

dds::pub::DataWriter< RequestType >	request_datawriter () const
	Retrieves the underlying dds::pub::DataWriter.

dds::sub::DataReader< ReplyType >	reply_datareader () const
	Retrieves the underlying dds::sub::DataReader.

Public Member Functions inherited from dds::core::Reference< DELEGATE >
	Reference (dds::core::null_type &)

	Reference (const Reference &ref)

template<typename D >
	Reference (const Reference< D > &ref)

	~Reference ()

template<typename R >
bool	operator== (const R &ref) const

template<typename R >
bool	operator!= (const R &ref) const

Reference &	operator= (const null_type)

bool	is_nil () const

bool	operator== (const null_type) const

bool	operator!= (const null_type) const

const DELEGATE_REF_T &	delegate () const OMG_NOEXCEPT

DELEGATE_REF_T &	delegate () OMG_NOEXCEPT

DELEGATE *	operator-> () OMG_NOEXCEPT

const DELEGATE *	operator-> () const OMG_NOEXCEPT

Detailed Description

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

<<reference-type>> 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 are: those generated by the rtiddsgen code generator, the DDS built-in types, and dds::core::xtypes::DynamicData.

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

A Requester can send requests and receive one or multiple 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 those requests that it sends.

For multi-reply scenarios, in which a Requester receives multiple replies from a Replier for a given request, the Requester can check if a reply is the last reply of a sequence of replies. To do so, see if the bit rti::core::SampleFlag::intermediate_reply_sequence is set in dds::sub::SampleInfo::flag after receiving each reply. This indicates it is NOT the last reply.

A requester has an associated dds::domain::DomainParticipant, 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 dds::pub::DataWriter for writing requests and a dds::sub::DataReader for reading replies, are automatically created when the requester 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

Template Parameters

RequestType	The data type for the request topic
ReplyType	The data type for the reply topic

See Also: rti::request::Replier; Request-Reply Examples; Basic Requester example

Constructor & Destructor Documentation

template<typename RequestType, typename ReplyType>

rti::request::Requester< RequestType, ReplyType >::Requester ( const RequesterParams & params )

inlineexplicit

Creates a Requester with parameters.

Parameters

params All the parameters that configure this requester. See RequesterParams for the list of mandatory parameters.

Exceptions

One	of the Standard Exceptions

See Also: RequesterParams; Requester Creation

template<typename RequestType, typename ReplyType>

rti::request::Requester< RequestType, ReplyType >::Requester	(	dds::domain::DomainParticipant	participant,
		const std::string &	service_name
	)

inline

Creates a Requester with the minimum set of parameters.

Parameters

participant	The DomainParticipant this requester uses to join a DDS domain
service_name	The service name. See RequesterParams::service_name

Exceptions

One	of the Standard Exceptions

Member Function Documentation

template<typename RequestType, typename ReplyType>

rti::core::SampleIdentity rti::request::Requester< RequestType, ReplyType >::send_request ( const RequestType & request )

inline

Sends a request.

Parameters

request The request to be sent

Returns: The identity of the request, which can be used to correlate it with a future reply (see rti::request::Requester::wait_for_replies(int, const dds::core::Duration&, const rti::core::SampleIdentity&))

template<typename RequestType, typename ReplyType>

void rti::request::Requester< RequestType, ReplyType >::send_request	(	const RequestType &	request,
		rti::pub::WriteParams &	params
	)

inline

Sends a request with advanced parameters.

Parameters

request	The request to be sent
params	(in-out) The parameters to write the request (see dds::pub::DataWriter::write(const T&,rti::pub::WriteParams&))

This function allows setting the request identity in params.identity(), among other advanced parameters. If the identity is not set, RTI Connext automatically assigns it, and to obtain it params.replace_automatic_values() needs to be set to true. Then, after this function ends, params.identity() will contain the request identity. If no additional parameters need to be set, use the simpler send_request(const RequestType&), which directly returns the automatically assigned identity.

template<typename RequestType, typename ReplyType>

dds::sub::LoanedSamples<ReplyType> rti::request::Requester< RequestType, ReplyType >::receive_replies ( const dds::core::Duration & max_wait )

inline

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

This operation is equivalent to using rti::request::Requester::receive_replies with min_count=1 and max_count=dds::core::LENGTH_UNLIMITED

MT Safety:: See rti::request::Requester::wait_for_replies(int, const dds::core::Duration&)

See Also: dds::sub::LoanedSamples; rti::request::Requester::receive_replies

template<typename RequestType, typename ReplyType>

dds::sub::LoanedSamples<ReplyType> rti::request::Requester< RequestType, ReplyType >::receive_replies	(	int	min_count,
		const dds::core::Duration &	max_wait
	)

inline

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

This operation is equivalent to using rti::request::Requester::wait_for_replies(int, const dds::core::Duration&) and rti::request::Requester::take_replies.

MT Safety:: See rti::request::Requester::wait_for_replies(int, const dds::core::Duration&)

Exceptions

One	of the Standard Exceptions

See Also: dds::sub::LoanedSamples; rti::request::Requester::wait_for_replies(int, const dds::core::Duration&); rti::request::Requester::take_replies

template<typename RequestType, typename ReplyType>

dds::sub::LoanedSamples<ReplyType> rti::request::Requester< RequestType, ReplyType >::take_replies ( )

inline

Takes all the 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. It is similar to dds::sub::DataReader::take.

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

This operation may be used after a call to rti::request::Requester::wait_for_replies(int, const dds::core::Duration&)

The maximum number of samples that are taken at a time. The special value dds::core::LENGTH_UNLIMITED may be used. This value will read up to the limit specified by rti::core::policy::DataReaderResourceLimits::max_samples_per_read

Returns: A container with up to max_count elements. May be empty if there were no replies to get.

Exceptions

One	of the Standard Exceptions

MT Safety:: SAFE

See Also: dds::sub::LoanedSamples; dds::sub::LoanedSamples::return_loan; rti::request::Requester::wait_for_replies(int, const dds::core::Duration&); dds::sub::DataReader::take (for a more detailed description on how QoS and other parameters affect the underlying DataReader)

template<typename RequestType, typename ReplyType>

dds::sub::LoanedSamples<ReplyType> rti::request::Requester< RequestType, ReplyType >::take_replies ( const rti::core::SampleIdentity & related_request_id )

inline

Takes the replies for a specific requests.

This operation is operation is analogous to take_replies() but it only returns those replies associated with a specific request.

Parameters

related_request_id Identifies a request previously sent by this Requester's send_request().

template<typename RequestType, typename ReplyType>

dds::sub::LoanedSamples<ReplyType> rti::request::Requester< RequestType, ReplyType >::read_replies ( )

inline

Reads all the replies.

This operation is equivalent to rti::request::Requester::take_replies except the replies remain in the Requester and can be read or taken again.

template<typename RequestType, typename ReplyType>

dds::sub::LoanedSamples<ReplyType> rti::request::Requester< RequestType, ReplyType >::read_replies ( const rti::core::SampleIdentity & related_request_id )

inline

Reads the replies for a specific request.

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

template<typename RequestType, typename ReplyType>

bool rti::request::Requester< RequestType, ReplyType >::wait_for_replies ( const dds::core::Duration & max_wait )

inline

Waits for replies to any request.

This operation is equivalent to using rti::request::Requester::wait_for_replies(int, const dds::core::Duration&) with min_count=1.

See Also: rti::request::Requester::wait_for_replies(int, const dds::core::Duration&)

template<typename RequestType, typename ReplyType>

bool rti::request::Requester< RequestType, ReplyType >::wait_for_replies	(	int	min_count,
		const dds::core::Duration &	max_wait
	)

inline

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 rti::request::Requester::take_replies), 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::core::policy::History used to configure this Requester.

Parameters

min_count	Minimum number of replies that need to be available for this operation to unblock.
max_wait	Maximum waiting time after which this operation unblocks, regardless of how many replies are available.

Returns: true if at least minCount replies were available before maxWait 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 rti::request::Requester::wait_for_replies(int, const dds::core::Duration&, const rti::core::SampleIdentity&)).

See Also: rti::request::Requester::take_replies

template<typename RequestType, typename ReplyType>

bool rti::request::Requester< RequestType, ReplyType >::wait_for_replies	(	int	min_count,
		const dds::core::Duration &	max_wait,
		const rti::core::SampleIdentity &	related_request_id
	)

inline

Waits for replies to a specific request.

This operation is analogous to rti::request::Requester::wait_for_replies(int, const dds::core::Duration&) except this operation waits for replies for a specific request.

Parameters

min_count	Minimum number of replies for the related request that need to be available for this operation to unblock.
max_wait	Maximum wait time after which this operation unblocks, regardless of how many replies are available.
related_request_id	The 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

One	of the Standard Exceptions

MT Safety:: SAFE

See Also: rti::request::Requester::wait_for_replies(int, const dds::core::Duration&)

template<typename RequestType, typename ReplyType>

dds::pub::DataWriter<RequestType> rti::request::Requester< RequestType, ReplyType >::request_datawriter ( ) const

inline

Retrieves the underlying dds::pub::DataWriter.

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: dds::pub::DataWriter; dds::pub::DataWriter; dds::pub::matched_subscriptions(); dds::pub::matched_subscription_data(); dds::pub::DataWriter::listener(DataWriterListener<T>* l, const dds::core::status::StatusMask& mask); dds::pub::DataWriter::datawriter_protocol_status()

template<typename RequestType, typename ReplyType>

dds::sub::DataReader<ReplyType> rti::request::Requester< RequestType, ReplyType >::reply_datareader ( ) const

inline

Retrieves the underlying dds::sub::DataReader.

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: dds::sub::DataReader; dds::sub::DataReader; dds::sub::matched_publications; dds::sub::DataReader::matched_publication_data; dds::sub::DataReader::listener(Listener* the_listener,const dds::core::status::StatusMask& event_mask); dds::sub::DataReader::datareader_protocol_status

Public Member Functions

Detailed Description

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

Constructor & Destructor Documentation

Member Function Documentation

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