DDS::rpc::Requester< TReq, TRep > Class Template Reference

A Requester sends requests and receives replies. More...

Inheritance diagram for DDS::rpc::Requester< TReq, TRep >:

Public Member Functions
	Requester ()
	Default constructor. More...
	Requester (const RequesterParams &params)
	Constructor that accepts RequesterParams for configuration.
virtual	~Requester ()
	Destructor.
void	send_request (WriteSample< TReq > &request)
	Transmits a request to any matched instances of this service This method accepts a parameter of WriteSample<TReq> &.
void	send_request (WriteSampleRef< TReq > &wsref)
	Transmits a request to any matched instances of this service This method accepts a parameter of WriteSampleRef<TReq> ^&&.
bool	receive_reply (Sample< TRep > &reply, const DDS::Duration_t &timeout)
	Attempts to access a received reply. More...
bool	receive_reply (SampleRef< TRep > reply, const DDS::Duration_t &timeout)
	Attempts to access a received reply. More...
bool	receive_reply (Sample< TRep > &reply, const DDS::SampleIdentity_t &relatedRequestId)
	Attempts to access a received reply. More...
bool	receive_reply (SampleRef< TRep > reply, const DDS::SampleIdentity_t &relatedRequestId)
	Attempts to access a received reply. More...
LoanedSamples< TRep >	receive_replies (const DDS::Duration_t &max_wait)
	Attempts to access multiple received replies. More...
LoanedSamples< TRep >	receive_replies (uint32_t min_count, uint32_t max_count, const DDS::Duration_t &max_wait)
	Attempts to access at least 'min_count' replies. More...
bool	wait_for_replies (uint32_t min_count, const DDS::Duration_t &max_wait)
	Blocks until at least 'min_count' replies are available. More...
bool	wait_for_replies (const DDS::Duration_t &max_wait)
	Blocks until a reply is available. More...
bool	wait_for_replies (uint32_t min_count, const DDS::Duration_t &max_wait, const DDS::SampleIdentity_t &related_request_id)
	Blocks until at least 'min_count' replies to 'related_request_id' are available. More...
bool	take_reply (Sample< TRep > &reply)
	Attempts to access a received reply. More...
bool	take_reply (SampleRef< TRep > reply)
	Attempts to access a received reply. More...
bool	take_reply (Sample< TRep > &reply, const DDS::SampleIdentity_t &related_request_id)
	Attempts to access a received reply. More...
bool	take_reply (SampleRef< TRep > reply, const DDS::SampleIdentity_t &related_request_id)
	Attempts to access a received reply. More...
LoanedSamples< TRep >	take_replies (uint32_t max_count)
	Attempts to access up to 'max_count' replies. More...
LoanedSamples< TRep >	take_replies (uint32_t max_count, const DDS::SampleIdentity_t &related_request_id)
	Attempts to access up to 'max_count' replies that match the 'related_request_id'. More...
LoanedSamples< TRep >	take_replies (const DDS::SampleIdentity_t &related_request_id)
	Attempts to access any replies that match the 'related_request_id'. More...
bool	read_reply (Sample< TRep > &reply)
	Attempts to access the next available reply. More...
bool	read_reply (SampleRef< TRep > reply)
	Attempts to access the next available reply. More...
bool	read_reply (Sample< TRep > &reply, const DDS::SampleIdentity_t &related_request_id)
	Attempts to access the next available reply that matches 'related_reqeust_id'. More...
bool	read_reply (SampleRef< TRep > reply, const DDS::SampleIdentity_t &related_request_id)
	Attempts to access the next available reply that matches 'related_reqeust_id'. More...
LoanedSamples< TRep >	read_replies (uint32_t max_count)
	Attempts to access up to 'max_count' replies. More...
LoanedSamples< TRep >	read_replies (uint32_t max_count, const DDS::SampleIdentity_t &related_request_id)
	Attempts to access up to 'max_count' replies that match 'related_request_id'. More...
LoanedSamples< TRep >	read_replies (const DDS::SampleIdentity_t &related_request_id)
	Attempts to access all available replies that match 'related_request_id'. More...
bool	receive_nondata_samples (bool enable)
	Toggle whether non-data samples are presented to the application. More...
RequesterParams	get_requester_params () const
	Obtain the parameters used to configure this Reqeuster.
RequestDataWriter	get_request_datawriter () const
	Obtain access to the underlying DataWriter used for sending Requests.
ReplyDataReader	get_reply_datareader () const
	Obtain access to the underlying DataReader used for receiving Replies.
Public Member Functions inherited from DDS::rpc::ServiceProxy
void	bind (const std::string &instance_name)
	Bind the ServiceProxy to service(s) with the provided 'instance_name'. More...
void	unbind ()
	Undo any previous 'bind()' operation. More...
bool	is_bound () const
	Indicates if the ServiceProxy is currently bound to a particular instance_name.
std::string	get_bound_instance_name () const
	Provides the instance_name to which the ServiceProxy is currently bound.
std::vector< std::string >	get_discoverd_service_instances () const
	Access a list of instance_names that have been discovered by the ServiceProxy. More...
std::vector< std::string >	get_discovered_service_instances () const
	Access a list of instance_names that have been discovered by the ServiceProxy. More...
uint32_t	get_discovered_service_count () const
	Access the number of service instances that have been discovered by the ServiceProxy. More...
void	wait_for_service ()
	Block until any service is discovered.
ReturnCode_t	wait_for_service (const DDS::Duration_t &maxWait)
	Block up to 'maxWait' until any service is discovered. More...
void	wait_for_service (std::string instanceName)
	Wait for a service with matching 'instanceName' to be discovered.
ReturnCode_t	wait_for_service (const DDS::Duration_t &maxWait, std::string instanceName)
	Block up to 'maxWait' until a service matching 'instanceNmae' is discovered. More...
void	wait_for_services (uint32_t count)
	Block until at least 'count' services have been discovered.
ReturnCode_t	wait_for_services (const DDS::Duration_t &maxWait, uint32_t count)
	Block until at least 'count' services have been discovered or 'maxWait' time elapses. More...
void	wait_for_services (const std::vector< std::string > &instanceNames)
	Block until discovering a service for each of the listed 'instanceNames'.
ReturnCode_t	wait_for_services (const DDS::Duration_t &maxWait, const std::vector< std::string > &instanceNames)
	Block until discovering a service for each of the listed 'instanceNames', or 'maxWait' elapses. More...
Public Member Functions inherited from DDS::rpc::RPCEntity
void	close ()
	Release the underlying resources including any DDS entities. More...
bool	is_null () const
	Indicates if the entity has been 'closed'. More...

Detailed Description

template<typename TReq, typename TRep>
class DDS::rpc::Requester< TReq, TRep >

A Requester sends requests and receives replies.

An instance of a Requester is configured at the time of construction using RequesterParams, which is a container of configuration parameters, such as domain participant, QoS, listeners and more.

Requester is inherently asynchronous as sending a request and receiving its corresponding reply (or replies) are separated. Requester allows listener-based, polling-based, and future-based reception of replies.

SimpleRequesterListener and RequesterListener interfaces enable callback-based notification when a reply is available. On the other hand, Requester provides functions to allow polling reception of replies.

Future-based notification of replies is analogous to callback-based notification, however, no request-reply correlation is necessary because every future represents a reply to a unique request.

A requester reference may be bound to a specific service instance. Requests sent through a bound requester reference shall be sent to the bound service instance only.

Constructor & Destructor Documentation

template<typename TReq , typename TRep >

DDS::rpc::Requester< TReq, TRep >::Requester

(

)

Default constructor.

Without any configuration, the Requester will construct DDS Entities as required in domain '0'.

Member Function Documentation

template<typename TReq , typename TRep >

LoanedSamples<TRep> DDS::rpc::Requester< TReq, TRep >::read_replies

(

uint32_t

max_count

)

Attempts to access up to 'max_count' replies.

The available replies (up to 'max_count') are returned in a LoanedSamples<TRep> object. This routine will not block.

template<typename TReq , typename TRep >

LoanedSamples<TRep> DDS::rpc::Requester< TReq, TRep >::read_replies	(	uint32_t	max_count,
		const DDS::SampleIdentity_t &	related_request_id
	)

Attempts to access up to 'max_count' replies that match 'related_request_id'.

The available matching replies (up to 'max_count') are returned in a LoanedSamples<TRep> object. This routine will not block.

template<typename TReq , typename TRep >

LoanedSamples<TRep> DDS::rpc::Requester< TReq, TRep >::read_replies

(

const DDS::SampleIdentity_t &

related_request_id

)

Attempts to access all available replies that match 'related_request_id'.

The available matching replies are returned in a LoanedSamples<TRep> object. This routine will not block.

template<typename TReq , typename TRep >

bool DDS::rpc::Requester< TReq, TRep >::read_reply ( Sample< TRep > &  reply )

inline

Attempts to access the next available reply.

This routine will block until a reply is available. This routines copies the reply data into the provided Sample<TRep> 'reply'.

template<typename TReq , typename TRep >

bool DDS::rpc::Requester< TReq, TRep >::read_reply ( SampleRef< TRep >  reply )

inline

Attempts to access the next available reply.

This routine will block until a reply is available.

template<typename TReq , typename TRep >

bool DDS::rpc::Requester< TReq, TRep >::read_reply ( Sample< TRep > &  reply, const DDS::SampleIdentity_t &  related_request_id  )

inline

Attempts to access the next available reply that matches 'related_reqeust_id'.

This routine will block until a matching reply is available.

template<typename TReq , typename TRep >

bool DDS::rpc::Requester< TReq, TRep >::read_reply ( SampleRef< TRep >  reply, const DDS::SampleIdentity_t &  related_request_id  )

inline

Attempts to access the next available reply that matches 'related_reqeust_id'.

This routine will block until a matching reply is available.

template<typename TReq , typename TRep >

bool DDS::rpc::Requester< TReq, TRep >::receive_nondata_samples

(

bool

enable

)

Toggle whether non-data samples are presented to the application.

Note

This is of little utility, as the only non-data samples are unregister, dispose, and not-alive indications which are uncommon with an un-keyed datatype.

template<typename TReq , typename TRep >

LoanedSamples<TRep> DDS::rpc::Requester< TReq, TRep >::receive_replies

(

const DDS::Duration_t &

max_wait

)

Attempts to access multiple received replies.

This method will access all available replies and return them in a LoanedSamples<TRep> object. If no replies are currently available, the routine will block for up to 'max_wait'.

Return values

bool	indicating if replies were found (true) or not (false).

template<typename TReq , typename TRep >

LoanedSamples<TRep> DDS::rpc::Requester< TReq, TRep >::receive_replies	(	uint32_t	min_count,
		uint32_t	max_count,
		const DDS::Duration_t &	max_wait
	)

Attempts to access at least 'min_count' replies.

This method will access all available replies up to 'max_count' and return them in a LoanedSamples<TRep> object. If at least 'min_count' replies are currently not available, the routine will block for up to 'max_wait'.

Return values

bool	indicating if replies were found (true) or not (false).

template<typename TReq , typename TRep >

bool DDS::rpc::Requester< TReq, TRep >::receive_reply	(	Sample< TRep > &	reply,
		const DDS::Duration_t &	timeout
	)

Attempts to access a received reply.

This method accepts a parameter of Sample<TRep> & and a 'timeout'. The call will block until a reply is found, or the timeout period elapses.

Return values

bool	indicating if a reply was found (true) or not (false).

template<typename TReq , typename TRep >

bool DDS::rpc::Requester< TReq, TRep >::receive_reply	(	SampleRef< TRep >	reply,
		const DDS::Duration_t &	timeout
	)

Attempts to access a received reply.

This method accepts a parameter of SampleRef<TRep> & and a 'timeout'. The call will block until a reply is found, or the timeout period elapses.

Return values

bool	indicating if a reply was found (true) or not (false).

template<typename TReq , typename TRep >

bool DDS::rpc::Requester< TReq, TRep >::receive_reply	(	Sample< TRep > &	reply,
		const DDS::SampleIdentity_t &	relatedRequestId
	)

Attempts to access a received reply.

This method accepts a parameter of Sample<TRep> & and a SampleIdentity_t. The call will block until a specific reply is found that matches the identity provided the 'relatedRequestId' parameter.

Return values

bool	indicating if a reply was found (true) or not (false).

template<typename TReq , typename TRep >

bool DDS::rpc::Requester< TReq, TRep >::receive_reply	(	SampleRef< TRep >	reply,
		const DDS::SampleIdentity_t &	relatedRequestId
	)

Attempts to access a received reply.

This method accepts a parameter of SampleRef<TRep> & and a SampleIdentity_t. The call will block until a specific reply is found that matches the identity provided the 'relatedRequestId' parameter.

Return values

bool	indicating if a reply was found (true) or not (false).

template<typename TReq , typename TRep >

LoanedSamples<TRep> DDS::rpc::Requester< TReq, TRep >::take_replies

(

uint32_t

max_count

)

Attempts to access up to 'max_count' replies.

This method will access all available replies up to 'max_count' and return them in a LoanedSamples<TRep> object. This routine will not block.

template<typename TReq , typename TRep >

LoanedSamples<TRep> DDS::rpc::Requester< TReq, TRep >::take_replies	(	uint32_t	max_count,
		const DDS::SampleIdentity_t &	related_request_id
	)

Attempts to access up to 'max_count' replies that match the 'related_request_id'.

This method will access all available replies up to 'max_count' and return them in a LoanedSamples<TRep> object. This routine will not block.

template<typename TReq , typename TRep >

LoanedSamples<TRep> DDS::rpc::Requester< TReq, TRep >::take_replies

(

const DDS::SampleIdentity_t &

related_request_id

)

Attempts to access any replies that match the 'related_request_id'.

This method will access all available matching replies and return them in a LoanedSamples<TRep> object. This routine will not block.

template<typename TReq , typename TRep >

bool DDS::rpc::Requester< TReq, TRep >::take_reply

(

Sample< TRep > &

reply

)

Attempts to access a received reply.

This method accepts a parameter of Sample<TRep> & . The call will not block.

Return values

bool	indicating if a reply was found (true) or not (false).

template<typename TReq , typename TRep >

bool DDS::rpc::Requester< TReq, TRep >::take_reply

(

SampleRef< TRep >

reply

)

Attempts to access a received reply.

This method accepts a parameter of SampleRef<TRep> & . The call will not block.

Return values

bool	indicating if a reply was found (true) or not (false).

template<typename TReq , typename TRep >

bool DDS::rpc::Requester< TReq, TRep >::take_reply	(	Sample< TRep > &	reply,
		const DDS::SampleIdentity_t &	related_request_id
	)

Attempts to access a received reply.

This method accepts a parameter of Sample<TRep> & . The call will not block.

Return values

bool	indicating if a reply was found (true) or not (false).

template<typename TReq , typename TRep >

bool DDS::rpc::Requester< TReq, TRep >::take_reply	(	SampleRef< TRep >	reply,
		const DDS::SampleIdentity_t &	related_request_id
	)

Attempts to access a received reply.

This method accepts a parameter of SampleRef<TRep> & . The call will not block.

Return values

bool	indicating if a reply was found (true) or not (false).

template<typename TReq , typename TRep >

bool DDS::rpc::Requester< TReq, TRep >::wait_for_replies	(	uint32_t	min_count,
		const DDS::Duration_t &	max_wait
	)

Blocks until at least 'min_count' replies are available.

If at least 'min_count' replies are currently not available, the routine will block for up to 'max_wait'.

Return values

bool	indicating if replies were found (true) or not (false).

template<typename TReq , typename TRep >

bool DDS::rpc::Requester< TReq, TRep >::wait_for_replies

(

const DDS::Duration_t &

max_wait

)

Blocks until a reply is available.

If no replies are currently available, the routine will block for up to 'max_wait'.

Return values

bool	indicating if replies were found (true) or not (false).

template<typename TReq , typename TRep >

bool DDS::rpc::Requester< TReq, TRep >::wait_for_replies	(	uint32_t	min_count,
		const DDS::Duration_t &	max_wait,
		const DDS::SampleIdentity_t &	related_request_id
	)

Blocks until at least 'min_count' replies to 'related_request_id' are available.

If at least 'min_count' matching replies are currently not available, the routine will block for up to 'max_wait'.

Not Yet Supported:

Currently, this routine will return if at least 'min_count' replies are available – it ignores 'related_request'.

Return values

bool	indicating if replies were found (true) or not (false).