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

#include <dds/topic/ContentFilteredTopic.hpp>

Inheritance diagram for dds::topic::ContentFilteredTopic< T >:

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

T	The 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_topic	The Topic to be filtered
the_name	Name for the new content filtered topic, must not exceed 255 characters.
filter	The 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

FwdIterator A forward iterator whose value type is std::string (or convertible to std::string)

Parameters

begin	The beginning of the range
end	The 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_filter Contains 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

One	of 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

One	of the Standard Exceptions

Friends And Related Function Documentation

template<typename BinIterator >

uint32_t find_registered_content_filters	(	const dds::domain::DomainParticipant &	participant,
		BinIterator	begin
	)

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

Template Parameters

BinIterator A back-inserting iterator whose value type is std::string (or convertible to)

Parameters

participant	The dds::domain::DomainParticipant that the content filters are registered with
begin	A 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

Public Member Functions

Related Functions

Detailed Description

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

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

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