RTI Connext Modern C++ API  Version 5.2.0
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
dds::topic::ContentFilteredTopic< T > Class Template Reference

<<reference-type>> Specialization of TopicDescription that allows for content-based subscriptions. More...

#include <dds/topic/ContentFilteredTopic.hpp>

Inheritance diagram for dds::topic::ContentFilteredTopic< T >:
dds::topic::TopicDescription< T > dds::core::Entity

Public Member Functions

 ContentFilteredTopic (const Topic< T > &topic, const std::string &name, const dds::topic::Filter &filter)
 Creates a ContentFilteredTopic to perform content-based subscriptions.
 
std::string filter_expression () const
 Gets the filter expression.
 
const dds::core::StringSeq filter_parameters () const
 Gets the filter expression parameters.
 
template<typename FwdIterator >
void filter_parameters (const FwdIterator &begin, const FwdIterator &end)
 Modifies the filter parameters.
 
const dds::topic::Topic< T > & topic () const
 Gets the related topic.
 
- Public Member Functions inherited from dds::topic::TopicDescription< T >
const std::string & name () const
 Gets the topic name.
 
const std::string & type_name () const
 Gets the type name.
 
const
dds::domain::DomainParticipant
participant () const
 Gets the related dds::domain::DomainParticipant.
 
- Public Member Functions inherited from dds::core::Entity
void enable ()
 Enables this entity (if it was created disabled)
 
const dds::core::status::StatusMask status_changes ()
 Retrieves the list of communication statuses that are triggered.
 
const dds::core::InstanceHandle instance_handle () const
 Get the instance handle that represents this entity.
 
void close ()
 Forces the destruction of this entity.
 
void retain ()
 Disables the automatic destruction of this entity.
 

Related Functions

(Note that these are not member functions.)

template<typename BinIterator >
uint32_t find_registered_content_filters (const dds::domain::DomainParticipant &participant, BinIterator begin)
 Lookup the names of all of the custom content filters registered to a dds::domain::DomainParticipant.
 

Detailed Description

template<typename T>
class dds::topic::ContentFilteredTopic< T >

<<reference-type>> Specialization of TopicDescription that allows for content-based subscriptions.

It describes a more sophisticated subscription that indicates a dds::sub::DataReader does not want to necessarily see all values of each instance published under the dds::topic::Topic. Rather, it wants to see only the values whose contents satisfy certain criteria. This class therefore can be used to request content-based subscriptions.

The selection of the content is done using the filter_expression with parameters expression_parameters.

  • The filter_expression attribute is a string that specifies the criteria to select the data samples of interest. It is similar to the WHERE part of an SQL clause.
  • The expression_parameters attribute is a sequence of strings that give values to the 'parameters' (i.e. "%n" tokens) in the filter_expression. The number of supplied parameters must fit with the requested values in the filter_expression (i.e. the number of n tokens).

Queries and Filters Syntax describes the syntax of filter_expression and expression_parameters.

Template Parameters
TThe topic-type
See Also
Filtering with ContentFilteredTopic

Constructor & Destructor Documentation

template<typename T>
dds::topic::ContentFilteredTopic< T >::ContentFilteredTopic ( const Topic< T > &  topic,
const std::string &  name,
const dds::topic::Filter filter 
)
inline

Creates a ContentFilteredTopic to perform content-based subscriptions.

The ContentFilteredTopic only relates to samples published under that Topic, filtered according to their content. The filtering is done by means of evaluating a logical expression that involves the values of some of the data-fields in the sample. The logical expression derived from the Filter arguments.

Queries and Filters Syntax describes the syntax of filter_expression and expression_parameters.

Precondition
The application is not allowed to create two ContentFilteredTopic objects with the same topic name attached to the same DomainParticipant. If the application attempts this, this function will fail and throw dds::core::Error.

By default this function will create a content filter using the built-in SQL filter which implements a superset of the DDS specification. This filter requires that all IDL types have been compiled with DynamicType (also known as TypeCode). If this precondition is not met, this operation return throws dds::core::Error. Do not use rtiddsgen's -notypecode option if you want to use the built-in SQL filter.

To use a different filter, set Filter::name().

Parameters
topicThe Topic to be filtered
nameName for the new content filtered topic, must not exceed 255 characters.
filterThe filter to apply, which includes the filter name (by default SQL), the filter expression and the expression parameters.

Member Function Documentation

template<typename T>
std::string dds::topic::ContentFilteredTopic< T >::filter_expression ( ) const
inline

Gets the filter expression.

template<typename T>
const dds::core::StringSeq dds::topic::ContentFilteredTopic< T >::filter_parameters ( ) const
inline

Gets the filter expression parameters.

template<typename T>
template<typename FwdIterator >
void dds::topic::ContentFilteredTopic< T >::filter_parameters ( const FwdIterator &  begin,
const FwdIterator &  end 
)
inline

Modifies the filter parameters.

Template Parameters
FwdIteratorA forward iterator whose value type is std::string (or convertible to std::string)
Parameters
beginThe beginning of the range
endThe end of the range (can't contain more than 100 elements)
template<typename T>
const dds::topic::Topic<T>& dds::topic::ContentFilteredTopic< T >::topic ( ) const
inline

Gets the related topic.

Friends And Related Function Documentation

template<typename BinIterator >
uint32_t find_registered_content_filters ( const dds::domain::DomainParticipant participant,
BinIterator  begin 
)
related

Lookup the names of all of the custom content filters registered to a dds::domain::DomainParticipant.

The names of the RTI Connext built-in content filters will not be returned as part of the list.

Template Parameters
BinIteratorA back-inserting iterator whose value type is std::string (or convertible to)
Parameters
participantThe dds::domain::DomainParticipant that the content filters are registered with
beginA back-inserting iterator to the position in the destination container to insert the the names of the found content filters into
Returns
The number of found content filters

RTI Connext Modern C++ API Version 5.2.0 Copyright © Sun Jun 21 2015 Real-Time Innovations, Inc