RTI Connext C API  Version 5.1.0
Requester

FooBarRequester and associated elements More...

Data Structures

struct  RTI_Connext_Requester
 The type-independent version of a Requester. More...
 
struct  RTI_Connext_RequesterParams
 Contains the parameters for creating a FooBarRequester. More...
 
struct  FooBarRequester
 Allows sending requests and receiving replies. More...
 

Macros

#define RTI_CONNEXT_REQUESTER_DECL(TReq, TRep, TRequester)
 Instantiates the declaration of a typed requester and its operations.
 

Typedefs

typedef struct
RTI_Connext_RequesterParams 
RTI_Connext_RequesterParams
 Contains the parameters for creating a FooBarRequester.
 
typedef struct FooBarRequester FooBarRequester
 Allows sending requests and receiving replies.
 

Functions

DDS_ReturnCode_t RTI_Connext_Requester_delete (RTI_Connext_Requester *self)
 Releases the internal entities created by this object.
 
DDS_ReturnCode_t RTI_Connext_Requester_wait_for_replies (RTI_Connext_Requester *self, DDS_Long min_count, const struct DDS_Duration_t *max_wait)
 Waits for replies to any request.
 
DDS_ReturnCode_t RTI_Connext_Requester_wait_for_replies_for_related_request (RTI_Connext_Requester *self, DDS_Long min_count, const struct DDS_Duration_t *max_wait, const struct DDS_SampleIdentity_t *related_request_id)
 Waits for replies to a specific request.
 
FooBarRequesterFooBarRequester_create (DDS_DomainParticipant *participant, const char *service_name)
 Creates a Requester with the minimum set of parameters.
 
FooBarRequesterFooBarRequester_create_w_params (const RTI_Connext_RequesterParams *params)
 Creates a Requester with parameters.
 
DDS_ReturnCode_t FooBarRequester_send_request (FooBarRequester *self, const Foo *request)
 Sends a request.
 
DDS_ReturnCode_t FooBarRequester_send_request_w_params (FooBarRequester *self, const Foo *request, struct DDS_WriteParams_t *request_info)
 Sends a request and gets back information about it that allows correlation with future replies.
 
DDS_ReturnCode_t FooBarRequester_receive_reply (FooBarRequester *self, Bar *reply, struct DDS_SampleInfo *sample_info, const struct DDS_Duration_t *max_wait)
 Waits for a reply and copies its contents into a Sample.
 
DDS_ReturnCode_t FooBarRequester_receive_replies (FooBarRequester *self, struct BarSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long min_count, DDS_Long max_count, const struct DDS_Duration_t *max_wait)
 Waits for multiple replies and provides a loaned sequence to access them.
 
DDS_ReturnCode_t FooBarRequester_take_reply (FooBarRequester *self, Bar *reply, struct DDS_SampleInfo *sample_info)
 Copies the contents of a reply into a Sample.
 
DDS_ReturnCode_t FooBarRequester_take_replies (FooBarRequester *self, struct BarSeq *reply_seq, struct DDS_SampleInfoSeq *sample_info_seq, DDS_Long max_count)
 Provides a loaned sequence to access the existing replies.
 
DDS_ReturnCode_t FooBarRequester_take_reply_for_related_request (FooBarRequester *self, Bar *reply, struct DDS_SampleInfo *sample_info, const struct DDS_SampleIdentity_t *related_request_id)
 Copies the contents of a reply for a specific request.
 
DDS_ReturnCode_t FooBarRequester_take_replies_for_related_request (FooBarRequester *self, struct BarSeq *reply_seq, struct DDS_SampleInfoSeq *sample_info_seq, DDS_Long max_count, const struct DDS_SampleIdentity_t *related_request_id)
 Provides a loaned sequence to access the existing replies for a specific request.
 
DDS_ReturnCode_t FooBarRequester_read_reply (FooBarRequester *self, Bar *reply, struct DDS_SampleInfo *sample_info)
 Copies the contents of a reply into a Sample.
 
DDS_ReturnCode_t FooBarRequester_read_replies (FooBarRequester *self, struct BarSeq *reply_seq, struct DDS_SampleInfoSeq *sample_info_seq, DDS_Long max_count)
 Provides a loaned sequence to access the existing replies.
 
DDS_ReturnCode_t FooBarRequester_read_reply_for_related_request (FooBarRequester *self, Bar *reply, struct DDS_SampleInfo *sample_info, const struct DDS_SampleIdentity_t *related_request_id)
 Copies the contents of a reply for a specific request.
 
DDS_ReturnCode_t FooBarRequester_read_replies_for_related_request (FooBarRequester *self, struct BarSeq *reply_seq, struct DDS_SampleInfoSeq *sample_info_seq, DDS_Long max_count, const struct DDS_SampleIdentity_t *related_request_id)
 Provides a loaned sequence to access the existing replies for a specific request.
 
FooDataWriterFooBarRequester_get_request_datawriter (FooBarRequester *self)
 Retrieves the underlying DDS_DataWriter.
 
BarDataReader * FooBarRequester_get_reply_datareader (FooBarRequester *self)
 Retrieves the underlying DDS_DataReader.
 
DDS_ReturnCode_t FooBarRequester_return_loan (FooBarRequester *self, struct BarSeq *received_data, struct DDS_SampleInfoSeq *info_seq)
 Returns samples previously received from the middleware.
 

Detailed Description

FooBarRequester and associated elements

Macro Definition Documentation

#define RTI_CONNEXT_REQUESTER_DECL (   TReq,
  TRep,
  TRequester 
)

Instantiates the declaration of a typed requester and its operations.

Parameters
TReqThe request type name
TRepThe reply type name
TRequesterThe type name for the typed requester and the prefix for all the operations.
See Also
Creating a Requester

Typedef Documentation

Contains the parameters for creating a FooBarRequester.

The following parameters are required to create a Requester:

The rest of the parameters that can be set in a RequesterParams object are optional.

See Also
Creating a Requester with optional parameters

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. Note: At this moment, in the C version of this API, only rtiddsgen-generated types are supported.

To create a Requester for two types, a request type TReq=Foo and a reply type TRep=Bar, your application needs to instantiate the data structure FooBarRequester and the specific operations that can publish and subscribe to those types. In this documentation we refer to the type-dependent operations as FooBarRequester_ (for example, FooBarRequester_take_replies). Some operations are type-independent and their name always begins with RTI_Connext_Requester_ (for example, RTI_Connext_Requester_wait_for_replies).

See Creating a Requester to see how to instantiate a FooBarRequester.

A Replier and a Requester communicate when they use the same topics for requests and replies (see RTI_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 DDS_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_DataWriter for writing requests and a DDS_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 RTI_Connext_RequesterParams::qos_profile_name). By default, they are created with reliable quality of service. The exact default configuration is described here: Configuring Request-Reply QoS profiles

See Also
FooBarReplier
Request-Reply Examples
Basic Requester example

Function Documentation

DDS_ReturnCode_t RTI_Connext_Requester_delete ( RTI_Connext_Requester self)

Releases the internal entities created by this object.

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

Parameters
self<<in>> Cannot be NULL.
See Also
DDS_Subscriber_delete_datareader
DDS_Publisher_delete_datawriter
DDS_ReturnCode_t RTI_Connext_Requester_wait_for_replies ( RTI_Connext_Requester self,
DDS_Long  min_count,
const struct 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 FooBarRequester_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_HistoryQosPolicy used to configure this Requester.

Parameters
self<<in>> Cannot be NULL.
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.

If at least min_count replies were available before max_wait elapsed, it returns DDS_RETCODE_OK, otherwise it returns DDS_RETCODE_TIMEOUT. Another Standard Return Codes may be returned in case of error.

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_Connext_Requester_wait_for_replies_for_related_request).
See Also
FooBarRequester_take_replies
DDS_ReturnCode_t RTI_Connext_Requester_wait_for_replies_for_related_request ( RTI_Connext_Requester self,
DDS_Long  min_count,
const struct DDS_Duration_t max_wait,
const struct DDS_SampleIdentity_t related_request_id 
)

Waits for replies to a specific request.

This operation is analogous to RTI_Connext_Requester_wait_for_replies except this operation waits for replies for a specific request.

Parameters
self<<in>> Cannot be NULL.
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.
One of the Standard Return Codes
MT Safety:
SAFE
See Also
RTI_Connext_Requester_wait_for_replies
FooBarRequester* FooBarRequester_create ( DDS_DomainParticipant participant,
const char *  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 RTI_Connext_RequesterParams::service_name
Returns
One of the Standard Return Codes
FooBarRequester* FooBarRequester_create_w_params ( const RTI_Connext_RequesterParams params)

Creates a Requester with parameters.

Parameters
paramsAll the parameters that configure this requester. See RTI_Connext_RequesterParams for the list of mandatory parameters.
Returns
One of the Standard Return Codes
See Also
RTI_Connext_RequesterParams
Creating a Requester
DDS_ReturnCode_t FooBarRequester_send_request ( FooBarRequester self,
const Foo request 
)

Sends a request.

If a future reply needs to be correlated to exactly this request, use FooBarRequester_send_request_w_params.

Parameters
self<<in>> Cannot be NULL.
requestThe request to be sent
Returns
One of the Standard Return Codes
MT Safety:
SAFE
See Also
FooBarRequester_send_request_w_params
DDS_ReturnCode_t FooBarRequester_send_request_w_params ( FooBarRequester self,
const Foo request,
struct DDS_WriteParams_t request_info 
)

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
self<<in>> Cannot be NULL.
request<<inout>> The request data
request_info<<inout>> Optional write parameters. When this call ends succesfully, DDS_WriteParams_t::identity contains a valid identity that can be used for correlation with future replies.
Returns
One of the Standard Return Codes ; DDS_RETCODE_TIMEOUT may be reported in the same conditions as in FooDataWriter_write.
MT Safety:
SAFE
See Also
DDS_WriteParams_t::identity
RTI_Connext_Requester_wait_for_replies_for_related_request
FooBarRequester_take_replies_for_related_request
Correlating requests and replies
DDS_ReturnCode_t FooBarRequester_receive_reply ( FooBarRequester self,
Bar *  reply,
struct DDS_SampleInfo sample_info,
const struct DDS_Duration_t max_wait 
)

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

This operation is equivalent to using RTI_Connext_Requester_wait_for_replies and FooBarRequester_take_reply.

MT Safety:
Same restrictions as RTI_Connext_Requester_wait_for_replies
See Also
RTI_Connext_Requester_wait_for_replies
FooBarRequester_take_reply
Basic Requester example
DDS_ReturnCode_t FooBarRequester_receive_replies ( FooBarRequester self,
struct BarSeq *  received_data,
struct DDS_SampleInfoSeq info_seq,
DDS_Long  min_count,
DDS_Long  max_count,
const struct DDS_Duration_t max_wait 
)

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

This operation is equivalent to using RTI_Connext_Requester_wait_for_replies and FooBarRequester_take_replies.

MT Safety:
See RTI_Connext_Requester_wait_for_replies
Returns
One of the Standard Return Codes
See Also
RTI_Connext_Requester_wait_for_replies
FooBarRequester_take_replies
DDS_ReturnCode_t FooBarRequester_take_reply ( FooBarRequester self,
Bar *  reply,
struct DDS_SampleInfo sample_info 
)

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 RTI_Connext_Requester_wait_for_replies.

To avoid copies, you can use FooBarRequester_take_replies.

Parameters
self<<in>> Cannot be NULL.
reply<<inout>> user data type-specific Foo object where the next received reply sample will be returned. The received_data must have been fully allocated. Otherwise, this operation may fail.
sample_info<<inout>> a DDS_SampleInfo object where the info associated to the received reply will be returned. Must be a valid non-NULL DDS_SampleInfo. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
Returns
One of the Standard Return Codes , DDS_RETCODE_NO_DATA
MT Safety:
SAFE
See Also
RTI_Connext_Requester_wait_for_replies
DDS_ReturnCode_t FooBarRequester_take_replies ( FooBarRequester self,
struct BarSeq *  reply_seq,
struct DDS_SampleInfoSeq sample_info_seq,
DDS_Long  max_count 
)

Provides a loaned sequence to access the existing replies.

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

This operation does not make a copy of the data. It is similar to FooDataReader_take.

The loan is returned with FooBarRequester_return_loan

This operation may be used after a call to RTI_Connext_Requester_wait_for_replies

See an example here: Taking loaned samples

Parameters
self<<in>> Cannot be NULL.
reply_seqThe data sequence
sample_info_seqThe associated sample info sequence
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

with up to elements. May be empty if there were no replies to get.

Returns
One of the Standard Return Codes , DDS_RETCODE_NO_DATA
MT Safety:
SAFE
See Also
RTI_Connext_Requester_wait_for_replies
FooDataReader_take (for a more detailed description on how QoS and other parameters affect the underlying DataReader)
DDS_ReturnCode_t FooBarRequester_take_reply_for_related_request ( FooBarRequester self,
Bar *  reply,
struct DDS_SampleInfo sample_info,
const struct DDS_SampleIdentity_t related_request_id 
)

Copies the contents of a reply for a specific request.

This operation is analogous to FooBarRequester_take_reply except the reply corresponds to a specific request.

Parameters
related_request_idThe identity of a request previously sent by this Requester
MT Safety:
SAFE
See Also
FooBarRequester_take_reply
FooBarRequester_send_request_w_params
Correlating requests and replies
DDS_ReturnCode_t FooBarRequester_take_replies_for_related_request ( FooBarRequester self,
struct BarSeq *  reply_seq,
struct DDS_SampleInfoSeq sample_info_seq,
DDS_Long  max_count,
const struct DDS_SampleIdentity_t related_request_id 
)

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

This operation is analogous to FooBarRequester_take_replies except the replies this operation provides correspond to a specific request.

The maximum number of samples that are taken at a time. The special value DDS_LENGTH_UNLIMITED may be used.

Parameters
related_request_idThe identity of a request previously sent by this Requester
MT Safety:
SAFE
See Also
FooBarRequester_take_replies
Correlating requests and replies
DDS_ReturnCode_t FooBarRequester_read_reply ( FooBarRequester self,
Bar *  reply,
struct DDS_SampleInfo sample_info 
)

Copies the contents of a reply into a Sample.

This operation is equivalent to FooBarRequester_take_reply except the reply remains in the Requester and can be read or taken again.

DDS_ReturnCode_t FooBarRequester_read_replies ( FooBarRequester self,
struct BarSeq *  reply_seq,
struct DDS_SampleInfoSeq sample_info_seq,
DDS_Long  max_count 
)

Provides a loaned sequence to access the existing replies.

This operation is equivalent to FooBarRequester_take_replies except the replies remain in the Requester and can be read or taken again.

DDS_ReturnCode_t FooBarRequester_read_reply_for_related_request ( FooBarRequester self,
Bar *  reply,
struct DDS_SampleInfo sample_info,
const struct DDS_SampleIdentity_t related_request_id 
)

Copies the contents of a reply for a specific request.

This operation is equivalent to FooBarRequester_take_reply_for_related_request except the reply remains in the Requester and can be read or taken again.

DDS_ReturnCode_t FooBarRequester_read_replies_for_related_request ( FooBarRequester self,
struct BarSeq *  reply_seq,
struct DDS_SampleInfoSeq sample_info_seq,
DDS_Long  max_count,
const struct DDS_SampleIdentity_t related_request_id 
)

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

This operation is equivalent to FooBarRequester_take_replies_for_related_request except the replies remain in the Requester and can be read or taken again.

FooDataWriter* FooBarRequester_get_request_datawriter ( FooBarRequester self)

Retrieves the underlying DDS_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_DataWriter
FooDataWriter
DDS_DataWriter_get_matched_subscriptions
DDS_DataWriter_get_matched_subscription_data
DDS_DataWriter_set_listener
DDS_DataWriter_get_datawriter_protocol_status
BarDataReader* FooBarRequester_get_reply_datareader ( FooBarRequester self)

Retrieves the underlying DDS_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_DataReader
FooDataReader
DDS_DataReader_get_matched_publications
DDS_DataReader_get_matched_publication_data
DDS_DataReader_set_listener
DDS_DataReader_get_datareader_protocol_status
DDS_ReturnCode_t FooBarRequester_return_loan ( FooBarRequester self,
struct BarSeq *  received_data,
struct DDS_SampleInfoSeq info_seq 
)

Returns samples previously received from the middleware.

This operation needs to be called at some point after:

See Also
FooDataReader_return_loan, for more information on how the middleware loans data to the application.

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