Topic Queries

rti::sub::TopicQuery and associated elements. More...

Classes
class	rti::sub::TopicQuerySelection
	<<extension>> <<value-type>> Specifies the data query that defines a TopicQuery. More...
class	rti::sub::TopicQueryData
	<<extension>> <<value-type>> Provides information about a TopicQuery More...
class	rti::sub::TopicQuery
	<<extension>> <<reference-type>> Allows a dds::sub::DataReader to query the sample cache of its matching dds::pub::DataWriters. More...

Detailed Description

rti::sub::TopicQuery and associated elements.

TopicQueries allow a dds::sub::DataReader to query the sample cache of its matching dds::pub::DataWriter. When the application 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::pub::qos::DataWriterQos includes the rti::core::policy::TopicQueryDispatch 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.

After deleting a TopicQuery, new DataWriters won't discover it and existing DataWriters currently publishing cached samples may stop before delivering all of them. See rti::sub::TopicQuery::close().

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::sub::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 rti::core::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::sub::DataReader::create_querycondition_w_params and dds::sub::DataReader::create_readcondition_w_params APIs.

Each TopicQuery is identified by a GUID that can be accessed using the rti::sub::TopicQuery::guid method.

Debugging Topic Queries

There are a number of ways in which to gain more insight into what is happening in an application that is creating Topic Queries.

The Built-in ServiceRequest DataReader

TopicQueries are communicated to publishing applications through a built-in rti::topic::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 rti::topic::ServiceRequest message is sent containing the TopicQuery information. Just as there are built-in DataReaders for dds::topic::ParticipantBuiltinTopicData, dds::topic::SubscriptionBuiltinTopicData, and dds::topic::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::sub::Subscriber::lookup_datareader. The topic name is rti::topic::service_request_topic_name(). Installing a listener with the dds::sub::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 rti::topic::ServiceRequest::service_id of a rti::topic::ServiceRequest corresponding to a rti::sub::TopicQuery will be rti::core::ServiceRequestId_def::TOPIC_QUERY and the rti::topic::ServiceRequest::instance_id will be equal to the GUID of the rti::sub::TopicQuery (see rti::sub::TopicQuery::guid).

The rti::topic::ServiceRequest::request_body is a sequence of bytes containing more information about the TopcQuery. This information can be retrieved using the rti::sub::create_topic_query_data_from_service_request() function. The resulting rti::sub::TopicQueryData contains the rti::sub::TopicQuerySelection that the rti::sub::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 rti::sub::TopicQueryData::original_related_reader_guid, however, will be that of the first DataReader to have created the TopicQuery.

The on_service_request_accepted DataWriter Listener Callback

It is possible that a rti::topic::ServiceRequest for a rti::sub::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::pub::DataWriterListener::on_service_request_accepted callback notifies a DataWriter when a ServiceRequest has been dispatched to that DataWriter. The dds::core::status::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::core::status::ServiceRequestAcceptedStatus::last_request_handle, which is the dds::core::InstanceHandle 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.

Reading TopicQuery Samples

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::sub::SampleInfo to the sample. First, if the dds::sub::SampleInfo::topic_query_guid is not equal to rti::core::Guid::unknown() then the sample is in response to the TopicQuery with that GUID (see rti::sub::TopicQuery::guid). Second, if the sample is in response to a TopicQuery and the dds::sub::SampleInfo::flag SampleFlagBits::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::sub::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.