RTI Connext C API
Version 5.3.0
|
DDS_TopicQuery and associated elements. More...
Data Structures | |
struct | DDS_TopicQuerySelection |
<<extension>> Specifies the data query that defines a DDS_TopicQuery More... | |
struct | DDS_TopicQueryData |
<<extension>> Provides information about a DDS_TopicQuery More... | |
Typedefs | |
typedef struct DDS_TopicQuerySelection | DDS_TopicQuerySelection |
<<extension>> Specifies the data query that defines a DDS_TopicQuery | |
typedef struct DDS_TopicQueryImpl | DDS_TopicQuery |
<<extension>> Allows a DDS_DataReader to query the sample cache of its matching DDS_DataWriter. | |
typedef struct DDS_TopicQueryData | DDS_TopicQueryData |
<<extension>> Provides information about a DDS_TopicQuery | |
Functions | |
DDS_Boolean | DDS_TopicQueryHelper_topic_query_data_from_service_request (struct DDS_TopicQueryData *topic_query_data, const struct DDS_ServiceRequest *service_request) |
Retrieves the DDS_TopicQueryData data contained in the specified DDS_ServiceRequest. | |
DDS_ReturnCode_t | DDS_TopicQuery_get_guid (DDS_TopicQuery *self, DDS_GUID_t *guid) |
Get the TopicQuery's GUID. | |
Variables | |
struct DDS_TopicQuerySelection | DDS_TOPIC_QUERY_SELECTION_USE_READER_CONTENT_FILTER |
Special value for creating a DDS_TopicQuery that applies the same filter as the DataReader's DDS_ContentFilteredTopic. | |
struct DDS_TopicQuerySelection | DDS_TOPIC_QUERY_SELECTION_SELECT_ALL |
Special value for creating a DDS_TopicQuery that selects all the samples in a DDS_DataWriter cache. | |
DDS_TopicQuery and associated elements.
TopicQueries allow a DDS_DataReader to query the sample cache of its matching DDS_DataWriter. A user can create a DDS_TopicQuery with the DDS_DataReader_create_topic_query API. When a DataReader creates a TopicQuery, DDS will propagate it to other DomainParticipants and their DataWriters. When a DataWriter matching with the DataReader that created the TopicQuery receives it, it will send the cached samples that pass the TopicQuery's filter.
To configure how to dispatch a TopicQuery, the DDS_DataWriterQos includes the DDS_TopicQueryDispatchQosPolicy policy. By default, a DataWriter ignores TopicQueries unless they are explicitly enabled using this policy.
The delivery of TopicQuery samples occurs in a separate RTPS channel. This allows DataReaders to receive TopicQuery samples and live samples in parallel. This is a key difference with respect to the Durability QoS policy.
Late-joining DataWriters will also discover existing TopicQueries. To delete a TopicQuery you must use DDS_DataReader_delete_topic_query.
After deleting a TopicQuery, new DataWriters won't discover it and existing DataWriters currently publishing cached samples may stop before delivering all of them.
The samples received in response to a TopicQuery are stored in the associated DataReader's cache. Any of the read/take operations can retrieve TopicQuery samples. The field DDS_SampleInfo::topic_query_guid associates each sample to its TopicQuery. If the read sample is not in response to a TopicQuery then this field will be DDS_GUID_UNKNOWN.
You can choose to read or take only TopicQuery samples, only live samples, or both. To support this ReadConditions and QueryConditions provide the DDS_DataReader_create_querycondition_w_params and DDS_DataReader_create_readcondition_w_params APIs.
Each TopicQuery is identified by a GUID that can be accessed using the DDS_TopicQuery_get_guid method.
There are a number of ways in which to gain more insight into what is happening in an application that is creating Topic Queries.
TopicQueries are communicated to publishing applications through a built-in DDS_ServiceRequest channel. The ServiceRequest channel is designed to be generic so that it can be used for many different purposes, one of which is TopicQueries.
When a DataReader creates a TopicQuery, a DDS_ServiceRequest message is sent containing the TopicQuery information. Just as there are built-in DataReaders for DDS_ParticipantBuiltinTopicData, DDS_SubscriptionBuiltinTopicData, and DDS_PublicationBuiltinTopicData, there is a fourth built-in DataReader for ServiceRequests.
The new built-in DataReader can be retrieved using the built-in subscriber and DDS_Subscriber_lookup_datareader. The topic name is DDS_SERVICE_REQUEST_TOPIC_NAME. Installing a listener with the DDS_DataReaderListener::on_data_available callback implemented will allow a publishing application to be notified whenever a TopicQuery has been received from a subscribing application.
The DDS_ServiceRequest::service_id of a DDS_ServiceRequest corresponding to a DDS_TopicQuery will be DDS_TOPIC_QUERY_SERVICE_REQUEST_ID and the DDS_ServiceRequest::instance_id will be equal to the GUID of the DDS_TopicQuery (see DDS_TopicQuery_get_guid).
The DDS_ServiceRequest::request_body is a sequence of bytes containing more information about the TopcQuery. This information can be retrieved using the DDS_TopicQueryHelper_topic_query_data_from_service_request function. The resulting DDS_TopicQueryData contains the DDS_TopicQuerySelection that the DDS_TopicQuery was created with, the GUID of the original DataReader that created the TopicQuery, and the topic name of that DataReader. Note: When TopicQueries are propagated through one or more Routing Services, the last DataReader that issued the TopicQuery will be a Routing Service DataReader. The DDS_TopicQueryData::original_related_reader_guid, however, will be that of the first DataReader to have created the TopicQuery.
It is possible that a DDS_ServiceRequest for a DDS_TopicQuery is received but is not immediately dispatched to a DataWriter. This can happen, for example, if a DataWriter was not matching with a DataReader at the time that the TopicQuery was received by the publishing application. The DDS_DataWriterListener::on_service_request_accepted callback notifies a DataWriter when a ServiceRequest has been dispatched to that DataWriter. The DDS_ServiceRequestAcceptedStatus provides information about how many ServiceRequests have been accepted by the DataWriter since the last time that the status was read. The status also includes the DDS_ServiceRequestAcceptedStatus::last_request_handle, which is the DDS_InstanceHandle_t of the last ServiceRequest that was accepted. This instance handle can be used to read samples per instance from the built-in ServiceRequest DataReader and correlate which ServiceRequests have been dispatched to which DataWriters.
Data samples that are received by a DataReader in response to a TopicQuery can be identified with two pieces of information from the corresponding DDS_SampleInfo to the sample. First, if the DDS_SampleInfo::topic_query_guid is not equal to DDS_GUID_UNKNOWN then the sample is in response to the TopicQuery with that GUID (see DDS_TopicQuery_get_guid). Second, if the sample is in response to a TopicQuery and the DDS_SampleInfo::flag DDS_INTERMEDIATE_TOPIC_QUERY_SAMPLE flag is set then this is not the last sample in response to the TopicQuery for a DataWriter identified by DDS_SampleInfo::original_publication_virtual_guid. If that flag is not set then there will be no more samples corresponding to that TopicQuery coming from the DataWriter.
typedef struct DDS_TopicQuerySelection DDS_TopicQuerySelection |
<<extension>> Specifies the data query that defines a DDS_TopicQuery
The query format is similar to the expression and parameters of a DDS_QueryCondition or a DDS_ContentFilteredTopic, as described in DDS_DomainParticipant_create_contentfilteredtopic_with_filter.
There are two special queries:
typedef struct DDS_TopicQueryImpl DDS_TopicQuery |
<<extension>> Allows a DDS_DataReader to query the sample cache of its matching DDS_DataWriter.
typedef struct DDS_TopicQueryData DDS_TopicQueryData |
<<extension>> Provides information about a DDS_TopicQuery
Contains the information about a TopicQuery that can be retrieved using DDS_TopicQueryHelper_topic_query_data_from_service_request.
DDS_Boolean DDS_TopicQueryHelper_topic_query_data_from_service_request | ( | struct DDS_TopicQueryData * | topic_query_data, |
const struct DDS_ServiceRequest * | service_request | ||
) |
Retrieves the DDS_TopicQueryData data contained in the specified DDS_ServiceRequest.
This operation will extract the content from the request body of the DDS_ServiceRequest and place it into the specified DDS_TopicQueryData object.
The specified DDS_ServiceRequest must be a valid sample associated with the service id DDS_TOPIC_QUERY_SERVICE_REQUEST_ID. Otherwise this operation will return DDS_BOOLEAN_FALSE.
This operation can be called within the context of a DDS_DataWriterListener::on_service_request_accepted to retrieve the DDS_TopicQueryData of a DDS_ServiceRequest that has been received with service id DDS_TOPIC_QUERY_SERVICE_REQUEST_ID
topic_query_data | <<inout>> A DDS_TopicQueryData object where the content from the service request is extracted. Cannot be NULL. |
service_request | <<in>> Input DDS_ServiceRequest that contains the DDS_TopicQueryData as part of its request body. Cannot be NULL. |
DDS_ReturnCode_t DDS_TopicQuery_get_guid | ( | DDS_TopicQuery * | self, |
DDS_GUID_t * | guid | ||
) |
Get the TopicQuery's GUID.
self | <<in>> Cannot be NULL. |
guid | <<out>> The GUID of the DDS_TopicQuery. Cannot be NULL. |
struct DDS_TopicQuerySelection DDS_TOPIC_QUERY_SELECTION_USE_READER_CONTENT_FILTER |
Special value for creating a DDS_TopicQuery that applies the same filter as the DataReader's DDS_ContentFilteredTopic.
If the DDS_DataReader that creates the DDS_TopicQuery uses a DDS_ContentFilteredTopic, this DDS_TopicQuerySelection value indicates that the TopicQuery should use the same filter.
Otherwise it behaves as DDS_TOPIC_QUERY_SELECTION_SELECT_ALL.
struct DDS_TopicQuerySelection DDS_TOPIC_QUERY_SELECTION_SELECT_ALL |
Special value for creating a DDS_TopicQuery that selects all the samples in a DDS_DataWriter cache.