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

Enumerations
enum	DDS_TopicQuerySelectionKind { DDS_TOPIC_QUERY_SELECTION_KIND_HISTORY_SNAPSHOT, DDS_TOPIC_QUERY_SELECTION_KIND_CONTINUOUS }
	Kinds of TopicQuerySelection. More...

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.

Detailed Description

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_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.

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 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.

The on_service_request_accepted DataWriter Listener Callback

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.

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_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 Documentation

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:

See Also: Queries and Filters Syntax

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.

See Also: DDS_TopicQueryHelper_topic_query_data_from_service_request

Enumeration Type Documentation

enum DDS_TopicQuerySelectionKind

Kinds of TopicQuerySelection.

See Also: DDS_TopicQuerySelection

Enumerator:

DDS_TOPIC_QUERY_SELECTION_KIND_HISTORY_SNAPSHOT

Indicates that the DDS_TopicQuery may only select samples that were in the DataWriter cache upon reception.

[default]

DDS_TOPIC_QUERY_SELECTION_KIND_CONTINUOUS

Indicates that the DDS_TopicQuery may continue selecting samples published after its reception.

The subscribing application must explicitly delete the TopicQuery (see DDS_DataReader_delete_topic_query) to signal the DataWriters to stop publishing samples for it.

Function Documentation

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

Parameters

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.

Returns: DDS_BOOLEAN_TRUE on success.

DDS_ReturnCode_t DDS_TopicQuery_get_guid	(	DDS_TopicQuery *	self,
		DDS_GUID_t *	guid
	)

Get the TopicQuery's GUID.

Parameters

self	<<in>> Cannot be NULL.
guid	<<out>> The GUID of the DDS_TopicQuery. Cannot be NULL.

Returns: One of the Standard Return Codes

Variable Documentation

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.

Data Structures

Typedefs

Enumerations

Functions

Variables