RTI Connext Modern C++ API  Version 6.0.1
 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 > &the_topic, const std::string &the_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.
 
void filter (const dds::topic::Filter &the_filter)
 <<extension>> Modifies the filter
 
void append_to_expression_parameter (int32_t index, const std::string &val)
 <<extension>> Appends a term to a parameter
 
void remove_from_expression_parameter (int32_t index, const std::string &val)
 <<extension>> Removes a term from a parameter
 
- 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
Creating Custom Content Filters

Constructor & Destructor Documentation

template<typename T>
dds::topic::ContentFilteredTopic< T >::ContentFilteredTopic ( const Topic< T > &  the_topic,
const std::string &  the_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
the_topicThe Topic to be filtered
the_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.

template<typename T>
void filter ( const dds::topic::Filter the_filter)

<<extension>> Modifies the filter

Parameters
the_filterContains the new filter expression and parameters. The filter name is immutable: if filter->name() is different it will be ignored.

Changes the filter_expression and expression_parameters associated with the dds::topic::ContentFilteredTopic.

Length of sequence cannot be greater than 100.

Returns
One of the Standard Exceptions.
template<typename T>
void append_to_expression_parameter ( int32_t  index,
const std::string &  val 
)

<<extension>> Appends a term to a parameter

Appends the input string to the end of the specified parameter string, separated by a comma. If the original parameter string is enclosed in quotation marks (''), the resultant string will also be enclosed in quotation marks.

This method can be used in expression parameters associated with MATCH operators in order to add a pattern to the match pattern list. For example, if the filter expression parameter value is:

'IBM'

Then append_to_expression_parameter(0, "MSFT") would generate the new value:

'IBM,MSFT'

Parameters
index<<in>> The index of the parameter string to be modified. The first index is index 0. When using the rti::topic::stringmatch_filter_name filter, index must be 0.
val<<in>> The string term to be appended to the parameter string.
Exceptions
Oneof the Standard Exceptions
template<typename T>
void remove_from_expression_parameter ( int32_t  index,
const std::string &  val 
)

<<extension>> Removes a term from a parameter

Removes the input string from the specified parameter string. To be found and removed, the input string must exist as a complete term, bounded by comma separators or the strong boundary. If the original parameter string is enclosed in quotation marks (''), the resultant string will also be enclosed in quotation marks. If the removed term was the last entry in the string, the result will be a string of empty quotation marks.

This method can be used in expression parameters associated with MATCH operators in order to remove a pattern from the match pattern list. For example, if the filter expression paremeter value is:

'IBM,MSFT'

Then remove_from_expression_parameter(0, "IBM") would generate the expression:

'MSFT'

Parameters
index<<in>> The index of the parameter string to be modified. The first index is index 0. When using the rti::topic::stringmatch_filter_name filter, index must be 0.
val<<in>> The string term to be removed from the parameter string.
Exceptions
Oneof the Standard Exceptions

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 6.0.1 Copyright © Sat Nov 23 2019 Real-Time Innovations, Inc