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.

RequestDataWriter *	get_request_datawriter ()
	Retrieves the underlying DDSDataWriter.

ReplyDataReader *	get_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 DDS_DynamicData.

For example:

using namespace connext;
Requester<Foo, Bar> requester(...);
Requester<DDS::DynamicData, Bar> requester(...);
Requester<Foo, DDS::Octets> 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 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 DDS_INTERMEDIATE_REPLY_SEQUENCE_SAMPLE is set in DDS_SampleInfo::flag after receiving each reply. This indicates it is NOT the last reply.

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 DDS_RELIABLE_RELIABILITY_QOS. The exact default configuration is described here: Configuring Request-Reply QoS profiles

Template Parameters

TReq	The data type for the request topic
TRep	The 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

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

Exceptions

One	of the RTI Connext Exceptions

template<typename TReq , typename TRep >

connext::Requester< TReq, TRep >::Requester ( const RequesterParams & params )

explicit

Creates a Requester with parameters.

Parameters

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

Exceptions

One	of 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

request The request to be sent

Exceptions

One	of 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 successfully, connext::WriteSample contains a valid identity that can be used for correlation with future replies.

Exceptions

One	of 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

Waits for a reply and copies its contents into a Sample.

This operation is equivalent to using wait_for_replies(int, const Duration_t&) and take_reply(Sample<TRep>&).

MT Safety:: Same restrictions as wait_for_replies(int, const Duration_t&)

See Also: connext::Sample; wait_for_replies(int, const Duration_t&); take_reply(Sample<TRep>&); Basic Requester example

template<typename TReq , typename TRep >

bool connext::Requester< TReq, TRep >::receive_reply	(	SampleRef< TRep >	reply,
		const DDS_Duration_t &	timeout
	)

inline

Waits for a reply and copies its contents into a SampleRef.

This operation is equivalent to using wait_for_replies(int, const Duration_t&) and take_reply(SampleRef<TRep>).

MT Safety:: Same restrictions as wait_for_replies(int, const Duration_t&)

See Also: connext::SampleRef; wait_for_replies(int, const Duration_t&); take_reply(SampleRef<TRep>); Basic Requester example using SampleRef

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

One	of 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_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 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_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 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

reply The 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

One	of 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

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_count The 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

One	of 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

reply	The sample where a reply is copied into
related_request_id	The 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_count	The maximum number of samples that are taken at a time. The special value DDS_LENGTH_UNLIMITED may be used.
related_request_id	The 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&)

References DDS_LENGTH_UNLIMITED.

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.

References DDS_LENGTH_UNLIMITED.

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

Public Types

Public Member Functions

Detailed Description

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

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

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