RTI Connext C API Version 7.3.0
|
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. More... | |
#define | RTI_Connext_ReplierParams_INITIALIZER |
Initializes a RTI_Connext_ReplierParams instance. More... | |
#define | RTI_CONNEXT_REPLIER_DECL(TReq, TRep, TReplier) |
Instantiates the declaration of a typed replier and its operations. More... | |
#define | RTI_Connext_RequesterParams_INITIALIZER |
Initializes a RTI_Connext_RequesterParams instance. More... | |
#define | RTI_Connext_SimpleReplierParams_INITIALIZER |
Initializes a RTI_Connext_SimpleReplierParams instance. More... | |
#define | RTI_CONNEXT_SIMPLEREPLIER_DECL(TReq, TRep, TSimpleReplier) |
Instantiates the declaration of a typed SimpleReplier and its operations. More... | |
Functions | |
DDS_ReturnCode_t | RTI_Connext_Replier_delete (RTI_Connext_Replier *self) |
Releases the internal entities created by this Replier. More... | |
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. More... | |
FooBarReplier * | FooBarReplier_create (DDS_DomainParticipant *participant, char *service_name) |
Creates a Replier with the minimum set of parameters. More... | |
FooBarReplier * | FooBarReplier_create_w_params (const RTI_Connext_ReplierParams *params) |
Creates a Replier with parameters. More... | |
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. More... | |
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. More... | |
DDS_ReturnCode_t | FooBarReplier_take_request (FooBarReplier *self, Foo *request, struct DDS_SampleInfo *sample_info) |
Copies the contents of a request into a Sample. More... | |
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. More... | |
DDS_ReturnCode_t | FooBarReplier_read_request (FooBarReplier *self, Foo *request, struct DDS_SampleInfo *sample_info) |
Copies the contents of a request into a Sample. More... | |
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. More... | |
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. More... | |
FooDataReader * | FooBarReplier_get_request_datareader (FooBarReplier *self) |
Retrieves the underlying DDS_DataReader. More... | |
BarDataWriter * | FooBarReplier_get_reply_datawriter (FooBarReplier *self) |
Retrieves the underlying DDS_DataWriter. More... | |
DDS_ReturnCode_t | FooBarReplier_return_loan (FooBarReplier *self, struct FooSeq *replies, struct DDS_SampleInfoSeq *info_seq) |
Returns samples previously received from the middleware. More... | |
FooBarSimpleReplier * | FooBarSimpleReplier_create (DDS_DomainParticipant *participant, char *service_name, RTI_Connext_SimpleReplierListener *listener) |
Creates a new SimpleReplier. More... | |
FooBarSimpleReplier * | FooBarSimpleReplier_create_w_params (RTI_Connext_SimpleReplierParams *params) |
Creates a new SimpleReplier. More... | |
DDS_ReturnCode_t | FooBarSimpleReplier_delete (FooBarSimpleReplier *self) |
Releases the resources created by this SimpleReplier. More... | |
Variables | |
RTI_Connext_ReplierListener_OnRequestAvailableCallback | RTI_Connext_ReplierListener::on_request_available |
User callback. More... | |
RTI_Connext_SimpleReplierListener_OnRequestAvailableCallback | RTI_Connext_SimpleReplierListener::on_request_available |
User callback that receives a request and provides a reply. More... | |
RTI_Connext_SimpleReplierListener_OnReturnLoanCallback | RTI_Connext_SimpleReplierListener::return_loan |
Returns a previously generated reply to the user. More... | |
FooBarReplier, FooBarSimpleReplier and associated elements
#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.
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. |
#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.
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. |
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) |
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.
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 rtiddsgen, 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:
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:
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.
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.
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.
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.
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. |
FooBarReplier * FooBarReplier_create | ( | DDS_DomainParticipant * | participant, |
char * | service_name | ||
) |
Creates a Replier with the minimum set of parameters.
participant | The DomainParticipant that this Replier uses to join a domain. |
service_name | The service name. See RTI_Connext_ReplierParams::service_name |
FooBarReplier * FooBarReplier_create_w_params | ( | const RTI_Connext_ReplierParams * | params | ) |
Creates a Replier with parameters.
params | All the parameters that configure this 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
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
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.
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)
self | <<in>> Cannot be NULL. |
reply | The reply to be sent. |
related_request_id | The identity of a previously received 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.
This operation needs to be called at some point after:
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.
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.
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.
request | The received 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.
reply | The reply previously provided in RTI_Connext_SimpleReplierListener::on_request_available |