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.

FooBarRequester *	FooBarRequester_create (DDS_DomainParticipant participant, const char service_name)
	Creates a Requester with the minimum set of parameters.

FooBarRequester *	FooBarRequester_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.

FooDataWriter *	FooBarRequester_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

TReq	The request type name
TRep	The reply type name
TRequester	The type name for the typed requester and the prefix for all the operations.

See Also: Creating a Requester

Typedef Documentation

typedef struct RTI_Connext_RequesterParams RTI_Connext_RequesterParams

Contains the parameters for creating a FooBarRequester.

The following parameters are required to create a Requester:

A DDS_DomainParticipant (RTI_Connext_RequesterParams::participant), and
Either a service name (RTI_Connext_RequesterParams::service_name)
Or custom topic names (RTI_Connext_RequesterParams::request_topic_name and RTI_Connext_RequesterParams::reply_topic_name)

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

See Also: Creating a Requester with optional parameters

typedef struct FooBarRequester FooBarRequester

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. 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 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 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 DDS_RELIABLE_RELIABILITY_QOS. 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_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.

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_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.; 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

participant	The DomainParticipant this requester uses to join a DDS domain
service_name	The 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

params All 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.
request	The 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_seq	The data sequence
sample_info_seq	The associated sample info sequence
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

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

self	<<in>> Cannot be NULL.
reply	The sample where a reply is copied into
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.
related_request_id	The 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.

Parameters

self	<<in>> Cannot be NULL.
reply_seq	The data sequence
sample_info_seq	The associated sample info sequence
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: 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.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation