RTI Connext Traditional C++ API
Version 6.1.2
|
Allows sending requests and receiving replies. More...
Public Types | |
typedef TReq | Request |
The request type. More... | |
typedef TRep | Reply |
The reply type. More... | |
typedef dds_type_traits< TReq >::DataWriter | RequestDataWriter |
The typed DataWriter for type TReq . More... | |
typedef dds_type_traits< TRep >::DataReader | ReplyDataReader |
The typed DataReader for type TRep . More... | |
typedef dds_type_traits< TReq >::TypeSupport | RequestTypeSupport |
The type support for type TReq . More... | |
typedef dds_type_traits< TRep >::TypeSupport | ReplyTypeSupport |
The type support for type TRep . More... | |
Public Member Functions | |
Requester (DDSDomainParticipant *participant, const std::string &service_name) | |
Creates a Requester with the minimum set of parameters. More... | |
Requester (const RequesterParams ¶ms) | |
Creates a Requester with parameters. More... | |
virtual | ~Requester () |
Releases the internal entities created by this object. More... | |
template<typename UReq > | |
void | send_request (const UReq &request) |
Sends a request. More... | |
template<typename UReq > | |
void | send_request (WriteSample< UReq > &request) |
Sends a request and gets back information about it that allows correlation with future replies. More... | |
template<typename UReq > | |
void | send_request (WriteSampleRef< UReq > &request) |
Sends a request and gets back information about it that allows correlation with future replies. More... | |
bool | receive_reply (Sample< TRep > &reply, const DDS_Duration_t &timeout) |
Waits for a reply and copies its contents into a Sample. More... | |
bool | receive_reply (SampleRef< TRep > reply, const DDS_Duration_t &timeout) |
Waits for a reply and copies its contents into a SampleRef. More... | |
LoanedSamples< TRep > | receive_replies (const DDS_Duration_t &max_wait) |
Waits for multiple replies and provides a loaned container to access them. More... | |
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. More... | |
bool | wait_for_replies (int min_count, const DDS_Duration_t &max_wait) |
Waits for replies to any request. More... | |
bool | wait_for_replies (const DDS_Duration_t &max_wait) |
Waits for replies to any request. More... | |
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. More... | |
bool | take_reply (Sample< TRep > &reply) |
Copies the contents of a reply into a Sample. More... | |
bool | take_reply (SampleRef< TRep > reply) |
Copies the contents of a reply into a SampleRef. More... | |
LoanedSamples< TRep > | take_replies (int max_count=DDS_LENGTH_UNLIMITED) |
Provides a loaned container to access the existing replies. More... | |
bool | take_reply (Sample< TRep > &reply, const SampleIdentity_t &related_request_id) |
Copies the contents of a reply for a specific request. More... | |
bool | take_reply (SampleRef< TRep > reply, const SampleIdentity_t &related_request_id) |
Copies the contents of a reply for a specific request. More... | |
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. More... | |
LoanedSamples< TRep > | take_replies (const SampleIdentity_t &related_request_id) |
Provides a loaned container to access the existing replies for a specific request. More... | |
bool | read_reply (Sample< TRep > &reply) |
Copies the contents of a reply into a Sample. More... | |
bool | read_reply (SampleRef< TRep > reply) |
Copies the contents of a reply into a SampleRef. More... | |
LoanedSamples< TRep > | read_replies (int max_count=DDS_LENGTH_UNLIMITED) |
Provides a loaned container to access the existing replies. More... | |
bool | read_reply (Sample< TRep > &reply, const SampleIdentity_t &related_request_id) |
Copies the contents of a reply for a specific request. More... | |
bool | read_reply (SampleRef< TRep > reply, const SampleIdentity_t &related_request_id) |
Copies the contents of a reply for a specific request. More... | |
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. More... | |
LoanedSamples< TRep > | read_replies (const SampleIdentity_t &related_request_id) |
Provides a loaned container to access the existing replies for a specific request. More... | |
RequestDataWriter * | get_request_datawriter () |
Retrieves the underlying DDSDataWriter. More... | |
ReplyDataReader * | get_reply_datareader () |
Retrieves the underlying DDSDataReader. More... | |
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:
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:
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
TReq | The data type for the request topic |
TRep | The data type for the reply topic |
typedef TReq connext::Requester< TReq, TRep >::Request |
The request type.
typedef TRep connext::Requester< TReq, TRep >::Reply |
The reply type.
typedef dds_type_traits<TReq>::DataWriter connext::Requester< TReq, TRep >::RequestDataWriter |
The typed DataWriter for type TReq
.
typedef dds_type_traits<TRep>::DataReader connext::Requester< TReq, TRep >::ReplyDataReader |
The typed DataReader for type TRep
.
typedef dds_type_traits<TReq>::TypeSupport connext::Requester< TReq, TRep >::RequestTypeSupport |
The type support for type TReq
.
typedef dds_type_traits<TRep>::TypeSupport connext::Requester< TReq, TRep >::ReplyTypeSupport |
The type support for type TRep
.
connext::Requester< TReq, TRep >::Requester | ( | DDSDomainParticipant * | participant, |
const std::string & | service_name | ||
) |
Creates a Requester with the minimum set of parameters.
participant | The DomainParticipant this requester uses to join a DDS domain |
service_name | The service name. See connext::RequesterParams::service_name |
One | of the RTI Connext Exceptions |
|
explicit |
Creates a Requester with parameters.
params | All the parameters that configure this requester. See connext::RequesterParams for the list of mandatory parameters. |
One | of the RTI Connext Exceptions |
|
virtual |
Releases the internal entities created by this object.
Among other internal resources, it deletes the underlying DataReader and DataWriter.
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>&).
request | The request to be sent |
One | of the RTI Connext Exceptions |
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.
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. |
One | of the RTI Connext Exceptions; connext::TimeoutException may be reported in the same conditions as in FooDataWriter::write. |
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
|
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>&).
|
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>).
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
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).
One | of the RTI Connext Exceptions |
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.
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. |
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
.
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.
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 |
One | of the RTI Connext Exceptions |
|
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).
reply | The sample where the reply data and the related SampleInfo are copied |
reply
remain unchanged, except DDS_SampleInfo::valid_data becomes false. One | of the RTI Connext Exceptions |
|
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
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
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 |
One | of the RTI Connext Exceptions |
Referenced by connext::Requester< TReq, TRep >::take_replies().
|
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.
reply | The sample where a reply is copied into |
related_request_id | The identity of a request previously sent by this Requester |
reply
remain unchanged, except DDS_SampleInfo::valid_data becomes false.
|
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
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.
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 |
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
References DDS_LENGTH_UNLIMITED, and connext::Requester< TReq, TRep >::take_replies().
|
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.
|
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
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.
Referenced by connext::Requester< TReq, TRep >::read_replies().
|
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.
|
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
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.
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, and connext::Requester< TReq, TRep >::read_replies().
|
inline |
Retrieves the underlying DDSDataWriter.
Accessing the request DataWriter may be useful for a number of advanced use cases, such as:
|
inline |
Retrieves the underlying DDSDataReader.
Accessing the reply DataReader may be useful for a number of advanced use cases, such as: