|
RTI Connext .NET API (legacy)
Version 6.1.2
|
DDS::TopicQuery and associated elements. More...
Classes | |
| class | DDS::TopicQuery |
| <<extension>> Allows a DDS::DataReader to query the sample cache of its matching DDS::DataWriter. More... | |
| class | DDS::TopicQuerySelection |
| <<extension>> Specifies the data query that defines a DDS::TopicQuery More... | |
| class | DDS::TopicQueryData |
| <<extension>> Provides information about a DDS::TopicQuery More... | |
| class | DDS::TopicQueryHelper |
| Helpers to provide utility operations related to DDS::TopicQuery. More... | |
Enumerations | |
| enum | DDS::TopicQuerySelectionKind : UINT32 { DDS::TopicQuerySelectionKind::HISTORY_SNAPSHOT, DDS::TopicQuerySelectionKind::CONTINUOUS } |
| Kinds of TopicQuerySelection. More... | |
Properties | |
| static TopicQuerySelection^ | DDS::DataReader::TOPIC_QUERY_SELECTION_USE_READER_CONTENT_FILTER [get] |
| Special value for creating a DDS::TopicQuery that applies the same filter as the DataReader's DDS::ContentFilteredTopic. More... | |
| static TopicQuerySelection^ | DDS::DataReader::TOPIC_QUERY_SELECTION_SELECT_ALL [get] |
| Special value for creating a DDS::TopicQuery that selects all the samples in a DDS::DataWriter cache. More... | |
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.
By default, a TopicQuery queries the samples that were in the DataWriter cache at the time the DataWriter receives the TopicQuery. However a TopicQuery can be created in a "continuous" mode. A DataWriter will continue delivering samples that pass a continuous TopicQuery filter until the DataReader application explicitly deletes it.
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_t::GUID_UNKNOWN. Note that the same data may be received several times, depending on how many TopicQueries the DataReader creates and their TopicQuerySelection.
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::ServiceRequestTypeSupport::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::ServiceRequest::TOPIC_QUERY_SERVICE_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_t::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 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.
|
strong |
Kinds of TopicQuerySelection.
| Enumerator | |
|---|---|
| HISTORY_SNAPSHOT | Indicates that the DDS::TopicQuery may only select samples that were in the DataWriter cache upon reception.
|
| CONTINUOUS | Indicates that the DDS::TopicQuery may continue selecting samples published after its reception.
|
|
staticget |
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::DataReader::TOPIC_QUERY_SELECTION_SELECT_ALL.
|
staticget |
Special value for creating a DDS::TopicQuery that selects all the samples in a DDS::DataWriter cache.