FooBarReplier, FooBarSimpleReplier and associated elements More...

Data Structures
struct	RTI_Connext_ReplierListener
	Called when a FooBarReplier has new available requests. More...

struct	RTI_Connext_SimpleReplierListener
	The listener called by a SimpleReplier. More...

struct	RTI_Connext_Replier
	The type-independent version of a Replier. More...

struct	RTI_Connext_ReplierParams
	Contains the parameters for creating a FooBarReplier. More...

struct	FooBarReplier
	Allows receiving requests and sending replies. More...

struct	RTI_Connext_SimpleReplierParams
	Contains the parameters for creating a FooBarSimpleReplier. More...

struct	FooBarSimpleReplier
	A callback-based replier. More...

Macros
#define	RTI_Connext_ReplierListener_INITIALIZER {NULL, NULL}
	Intializes an RTI_Connext_ReplierListener.

#define	RTI_Connext_ReplierParams_INITIALIZER
	Initializes a RTI_Connext_ReplierParams instance.

#define	RTI_CONNEXT_REPLIER_DECL(TReq, TRep, TReplier)
	Instantiates the declaration of a typed replier and its operations.

#define	RTI_Connext_RequesterParams_INITIALIZER
	Initializes a RTI_Connext_RequesterParams instance.

#define	RTI_Connext_SimpleReplierParams_INITIALIZER
	Initializes a RTI_Connext_SimpleReplierParams instance.

#define	RTI_CONNEXT_SIMPLEREPLIER_DECL(TReq, TRep, TSimpleReplier)
	Instantiates the declaration of a typed SimpleReplier and its operations.

Typedefs
typedef void(*	RTI_Connext_ReplierListener_OnRequestAvailableCallback )(struct RTI_Connext_ReplierListener self, RTI_Connext_Replier replier)
	The type of RTI_Connext_ReplierListener::on_request_available.

typedef void (	RTI_Connext_SimpleReplierListener_OnRequestAvailableCallback )(RTI_Connext_SimpleReplierListener self, const void request, const struct DDS_SampleInfo *info)
	The type of RTI_Connext_SimpleReplierListener::on_request_available.

typedef void(*	RTI_Connext_SimpleReplierListener_OnReturnLoanCallback )(RTI_Connext_SimpleReplierListener self, void reply)
	The type of RTI_Connext_SimpleReplierListener::return_loan.

typedef struct RTI_Connext_ReplierParams	RTI_Connext_ReplierParams
	Contains the parameters for creating a FooBarReplier.

typedef struct FooBarReplier	FooBarReplier
	Allows receiving requests and sending replies.

typedef struct RTI_Connext_SimpleReplierParams	RTI_Connext_SimpleReplierParams
	Contains the parameters for creating a FooBarSimpleReplier.

typedef struct FooBarSimpleReplier	FooBarSimpleReplier
	A callback-based replier.

Functions
DDS_ReturnCode_t	RTI_Connext_Replier_delete (RTI_Connext_Replier *self)
	Releases the internal entities created by this Replier.

DDS_ReturnCode_t	RTI_Connext_Replier_wait_for_requests (RTI_Connext_Replier self, int min_count, const struct DDS_Duration_t max_wait)
	Waits for requests.

FooBarReplier *	FooBarReplier_create (DDS_DomainParticipant participant, char service_name)
	Creates a Replier with the minimum set of parameters.

FooBarReplier *	FooBarReplier_create_w_params (const RTI_Connext_ReplierParams *params)
	Creates a Replier with parameters.

DDS_ReturnCode_t	FooBarReplier_receive_request (FooBarReplier self, Foo request, struct DDS_SampleInfo sample_info, const struct DDS_Duration_t max_wait)
	Waits for a request and copies its contents into a Sample.

DDS_ReturnCode_t	FooBarReplier_receive_requests (FooBarReplier self, struct FooSeq received_data, struct DDS_SampleInfoSeq info_seq, DDS_Long min_reply_count, DDS_Long max_reply_count, const struct DDS_Duration_t max_wait)
	Waits for multiple requests and provides a loaned sequence to access them.

DDS_ReturnCode_t	FooBarReplier_take_request (FooBarReplier self, Foo request, struct DDS_SampleInfo *sample_info)
	Copies the contents of a request into a Sample.

DDS_ReturnCode_t	FooBarReplier_take_requests (FooBarReplier self, struct FooSeq request_seq, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_count)
	Provides a loaned sequence to access the existing requests.

DDS_ReturnCode_t	FooBarReplier_read_request (FooBarReplier self, Foo request, struct DDS_SampleInfo *sample_info)
	Copies the contents of a request into a Sample.

DDS_ReturnCode_t	FooBarReplier_read_requests (FooBarReplier self, struct FooSeq request_seq, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_count)
	Provides a loaned sequence to access the existing requests.

DDS_ReturnCode_t	FooBarReplier_send_reply (FooBarReplier self, Bar reply, const struct DDS_SampleIdentity_t *related_request_id)
	Sends a reply for a previous request.

FooDataReader *	FooBarReplier_get_request_datareader (FooBarReplier *self)
	Retrieves the underlying DDS_DataReader.

BarDataWriter *	FooBarReplier_get_reply_datawriter (FooBarReplier *self)
	Retrieves the underlying DDS_DataWriter.

DDS_ReturnCode_t	FooBarReplier_return_loan (FooBarReplier self, struct FooSeq replies, struct DDS_SampleInfoSeq *info_seq)
	Returns samples previously received from the middleware.

FooBarSimpleReplier *	FooBarSimpleReplier_create (DDS_DomainParticipant participant, char service_name, RTI_Connext_SimpleReplierListener *listener)
	Creates a new SimpleReplier.

FooBarSimpleReplier *	FooBarSimpleReplier_create_w_params (RTI_Connext_SimpleReplierParams *params)
	Creates a new SimpleReplier.

DDS_ReturnCode_t	FooBarSimpleReplier_delete (FooBarSimpleReplier *self)
	Releases the resources created by this SimpleReplier.

Variables
RTI_Connext_ReplierListener_OnRequestAvailableCallback	RTI_Connext_ReplierListener::on_request_available
	User callback.

RTI_Connext_SimpleReplierListener_OnRequestAvailableCallback	RTI_Connext_SimpleReplierListener::on_request_available
	User callback that receives a request and provides a reply.

RTI_Connext_SimpleReplierListener_OnReturnLoanCallback	RTI_Connext_SimpleReplierListener::return_loan
	Returns a previously generated reply to the user.

Detailed Description

FooBarReplier, FooBarSimpleReplier and associated elements

Macro Definition Documentation

#define RTI_Connext_ReplierListener_INITIALIZER {NULL, NULL}

Intializes an RTI_Connext_ReplierListener.

#define RTI_Connext_ReplierParams_INITIALIZER

Initializes a RTI_Connext_ReplierParams instance.

#define RTI_CONNEXT_REPLIER_DECL	(	TReq,
		TRep,
		TReplier
	)

Instantiates the declaration of a typed replier and its operations.

Parameters

TReq	The request type name
TRep	The reply type name
TReplier	The type name for the typed replier and the prefix for all the operations.

See Also: Creating a Replier

#define RTI_Connext_RequesterParams_INITIALIZER

Initializes a RTI_Connext_RequesterParams instance.

#define RTI_Connext_SimpleReplierParams_INITIALIZER

Initializes a RTI_Connext_SimpleReplierParams instance.

#define RTI_CONNEXT_SIMPLEREPLIER_DECL	(	TReq,
		TRep,
		TSimpleReplier
	)

Instantiates the declaration of a typed SimpleReplier and its operations.

Parameters

TReq	The request type name
TRep	The reply type name
TSimpleReplier	The type name for the typed SimpleReplier and the prefix for all the operations.

See Also: SimpleReplier example

Typedef Documentation

typedef void(* RTI_Connext_ReplierListener_OnRequestAvailableCallback)(struct RTI_Connext_ReplierListener *self, RTI_Connext_Replier *replier)

The type of RTI_Connext_ReplierListener::on_request_available.

typedef void*(* RTI_Connext_SimpleReplierListener_OnRequestAvailableCallback)(RTI_Connext_SimpleReplierListener *self, const void *request, const struct DDS_SampleInfo *info)

The type of RTI_Connext_SimpleReplierListener::on_request_available.

typedef void(* RTI_Connext_SimpleReplierListener_OnReturnLoanCallback)(RTI_Connext_SimpleReplierListener *self, void *reply)

The type of RTI_Connext_SimpleReplierListener::return_loan.

typedef struct RTI_Connext_ReplierParams RTI_Connext_ReplierParams

Contains the parameters for creating a FooBarReplier.

See Also: RTI_Connext_RequesterParams

typedef struct FooBarReplier FooBarReplier

Allows receiving requests and sending replies.

A Replier is an entity with two associated topics: a request topic and a reply topic. It can receive requests by subscribing to the request topic and can send replies to those requests by publishing 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 Replier for two types, a request type TReq=Foo and a reply type TRep=Bar, your application needs to instantiate the data structure FooBarReplier and the specific operations that can publish and subscribe to those types. In this documentation we refer to the type-dependent operations as FooBarReplier_ (for example, FooBarReplier_take_requests). Some operations are type-independent and their names always begin with RTI_Connext_Replier_ (for example, RTI_Connext_Replier_wait_for_requests). See Creating a Replier.

A Replier has four main types of operations:

Waiting for requests to be received from the middleware
Getting those requests
Receiving requests (a convenience operation that is a combination of waiting and getting in a single operation)
Sending a reply for a previously received request (i.e., publishing a reply sample on the reply topic with special meta-data so that the orignal Requester can identify it)

For multi-reply scenarios in which a FooBarReplier generates more than one reply for a request, the FooBarReplier should mark all the intermediate replies (all but the last) using the DDS_INTERMEDIATE_REPLY_SEQUENCE_SAMPLE flag in DDS_WriteParams_t::flag.

Much like a Requester, a Replier has an associated DDS_DomainParticipant, which can be shared with other Repliers or RTI Connext routines. All the other entities required for the request-reply interaction, including a DDS_DataWriter for writing replies and a DDS_DataReader for reading requests, are automatically created when the Replier 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

There are several ways to use a Replier:

A thread receives requests and then dispatches them. If the computation of a reply is a simple operation, consider using a FooBarSimpleReplier instead of a Replier.
Polling without waiting, using FooBarReplier_take_requests directly.
Using a RTI_Connext_ReplierListener to get notified and get the requests within the callback.

See Also: FooBarRequester; Request-Reply Examples; Basic Replier example

typedef struct RTI_Connext_SimpleReplierParams RTI_Connext_SimpleReplierParams

Contains the parameters for creating a FooBarSimpleReplier.

The parameters for a SimpleReplier are identical to those of the Replier, except for the SimpleReplierListener, which is required and has a different user callback.

See Also: RTI_Connext_ReplierParams

typedef struct FooBarSimpleReplier FooBarSimpleReplier

A callback-based replier.

A SimpleReplier is based on a RTI_Connext_SimpleReplierListener that users provide. Requests are passed to the callback, which returns a reply. The reply is directed only to the Requester that sent the request.

SimpleRepliers are useful for simple use cases where a single reply for a request can be generated quickly, for example, looking up a table.

When more than one reply for a request can be generated or the processing is complex or needs to happen asynchronously, use a FooBarReplier instead.

See Also: FooBarReplier; RTI_Connext_SimpleReplierListener; SimpleReplier example

Function Documentation

DDS_ReturnCode_t RTI_Connext_Replier_delete ( RTI_Connext_Replier * self )

Releases the internal entities created by this Replier.

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

See Also: DDS_Subscriber_delete_datareader; DDS_Publisher_delete_datawriter

DDS_ReturnCode_t RTI_Connext_Replier_wait_for_requests	(	RTI_Connext_Replier *	self,
		int	min_count,
		const struct DDS_Duration_t *	max_wait
	)

Waits for requests.

This operation waits for min_count requests to be available. It will wait up to max_wait .

This operation is similar to RTI_Connext_Requester_wait_for_replies.

Parameters

self	<<in>> Cannot be NULL.
min_count	Minimum number of requests that need to be available for this operation to unblock.
max_wait	Maximum waiting time after which this operation unblocks regardless of how many requests are available.

Returns: true if at least min_count requests were available before max_wait elapsed, or false otherwise.

See Also: FooBarReplier_take_requests; RTI_Connext_Requester_wait_for_replies

FooBarReplier* FooBarReplier_create	(	DDS_DomainParticipant *	participant,
		char *	service_name
	)

Creates a Replier with the minimum set of parameters.

Parameters

participant	The DomainParticipant that this Replier uses to join a domain.
service_name	The service name. See RTI_Connext_ReplierParams::service_name

Returns: One of the Standard Return Codes

FooBarReplier* FooBarReplier_create_w_params ( const RTI_Connext_ReplierParams * params )

Creates a Replier with parameters.

Parameters

params All the parameters that configure this Replier

Returns: One of the Standard Return Codes

See Also: RTI_Connext_ReplierParams; Creating a Replier

DDS_ReturnCode_t FooBarReplier_receive_request	(	FooBarReplier *	self,
		Foo *	request,
		struct DDS_SampleInfo *	sample_info,
		const struct DDS_Duration_t *	max_wait
	)

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

Equivalent to using RTI_Connext_Replier_wait_for_requests and FooBarReplier_take_request

See Also: RTI_Connext_Replier_wait_for_requests; FooBarReplier_take_request; Basic Replier example

DDS_ReturnCode_t FooBarReplier_receive_requests	(	FooBarReplier *	self,
		struct FooSeq *	received_data,
		struct DDS_SampleInfoSeq *	info_seq,
		DDS_Long	min_reply_count,
		DDS_Long	max_reply_count,
		const struct DDS_Duration_t *	max_wait
	)

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

Equivalent to using RTI_Connext_Replier_wait_for_requests and FooBarReplier_take_requests

See Also: RTI_Connext_Replier_wait_for_requests; FooBarReplier_take_requests

DDS_ReturnCode_t FooBarReplier_take_request	(	FooBarReplier *	self,
		Foo *	request,
		struct DDS_SampleInfo *	sample_info
	)

Copies the contents of a request into a Sample.

See Also: FooBarRequester_take_reply

DDS_ReturnCode_t FooBarReplier_take_requests	(	FooBarReplier *	self,
		struct FooSeq *	request_seq,
		struct DDS_SampleInfoSeq *	info_seq,
		DDS_Long	max_count
	)

Provides a loaned sequence to access the existing requests.

See Also: FooBarRequester_take_replies

DDS_ReturnCode_t FooBarReplier_read_request	(	FooBarReplier *	self,
		Foo *	request,
		struct DDS_SampleInfo *	sample_info
	)

Copies the contents of a request into a Sample.

This operation is equivalent to FooBarReplier_take_request except the request remains in the Replier and can be read or taken again.

DDS_ReturnCode_t FooBarReplier_read_requests	(	FooBarReplier *	self,
		struct FooSeq *	request_seq,
		struct DDS_SampleInfoSeq *	info_seq,
		DDS_Long	max_count
	)

Provides a loaned sequence to access the existing requests.

This operation is equivalent to FooBarReplier_take_requests except the requests remain in the Replier and can be read or taken again.

DDS_ReturnCode_t FooBarReplier_send_reply	(	FooBarReplier *	self,
		Bar *	reply,
		const struct DDS_SampleIdentity_t *	related_request_id
	)

Sends a reply for a previous request.

The related request identity can be retrieved from the sample info (DDS_SampleInfo_get_sample_identity)

Parameters

self	<<in>> Cannot be NULL.
reply	The reply to be sent.
related_request_id	The identity of a previously received request

Returns: One of the Standard Return Codes

See Also: FooBarReplier_receive_request; FooBarReplier_receive_requests; FooBarReplier_take_request; FooBarReplier_take_requests; Basic Replier example

FooDataReader* FooBarReplier_get_request_datareader ( FooBarReplier * self )

Retrieves the underlying DDS_DataReader.

See Also: FooBarRequester_get_reply_datareader

BarDataWriter* FooBarReplier_get_reply_datawriter ( FooBarReplier * self )

Retrieves the underlying DDS_DataWriter.

See Also: FooBarRequester_get_request_datawriter

DDS_ReturnCode_t FooBarReplier_return_loan	(	FooBarReplier *	self,
		struct FooSeq *	replies,
		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.

FooBarSimpleReplier* FooBarSimpleReplier_create	(	DDS_DomainParticipant *	participant,
		char *	service_name,
		RTI_Connext_SimpleReplierListener *	listener
	)

Creates a new SimpleReplier.

See Also: RTI_Connext_SimpleReplierParams; RTI_Connext_SimpleReplierListener

FooBarSimpleReplier* FooBarSimpleReplier_create_w_params ( RTI_Connext_SimpleReplierParams * params )

Creates a new SimpleReplier.

See Also: RTI_Connext_SimpleReplierParams; RTI_Connext_SimpleReplierListener

DDS_ReturnCode_t FooBarSimpleReplier_delete ( FooBarSimpleReplier * self )

Releases the resources created by this SimpleReplier.

See Also: RTI_Connext_Replier_delete

Variable Documentation

RTI_Connext_ReplierListener_OnRequestAvailableCallback RTI_Connext_ReplierListener::on_request_available

User callback.

See Also: DDS_DataReaderListener::on_data_available

RTI_Connext_SimpleReplierListener_OnRequestAvailableCallback RTI_Connext_SimpleReplierListener::on_request_available

User callback that receives a request and provides a reply.

This operation gets called when a request is available and expects a reply that is automatically sent. Immediately after that, RTI_Connext_SimpleReplierListener::return_loan is called.

Parameters

request The received request

Returns: A reply for that request

RTI_Connext_SimpleReplierListener_OnReturnLoanCallback RTI_Connext_SimpleReplierListener::return_loan

Returns a previously generated reply to the user.

This operation is always called right after sending the reply created by RTI_Connext_SimpleReplierListener::on_request_available. It can be used to release any resources from the reply creation. If there are no resources to release, the implementation body can be empty.

Parameters

reply The reply previously provided in RTI_Connext_SimpleReplierListener::on_request_available

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation

Variable Documentation