Creating ContentFilteredTopics

To create a ContentFilteredTopic that uses the default SQL filter, use the DomainParticipant’s create_contentfilteredtopic() operation:

DDS_ContentFilteredTopic *create_contentfilteredtopic(
	const char * name,
	 const DDS_Topic * related_topic,
	 const char * filter_expression,
	 const DDS_StringSeq & expression_parameters)

Or, to use a custom filter or the builtin STRINGMATCH filter (see STRINGMATCH Filter Expression Notation), use the create_contentfilteredtopic_with_filter() variation:

DDS_ContentFilteredTopic *create_contentfilteredtopic_with_filter(
	const char * name,
	DDSTopic * related_topic,
	const char *  filter_expression,
	const DDS_StringSeq & expression_parameters,
	const char * filter_name = DDS_SQLFILTER_NAME) 

Where:

name	Name of the ContentFilteredTopic. Note that it is legal for a ContentFilteredTopic to have the same name as a Topic in the same DomainParticipant, but a ContentFilteredTopic cannot have the same name as another ContentFilteredTopic in the same DomainParticipant. This parameter cannot be NULL.
related_topic	The related Topic to be filtered. The related topic must be in the same DomainParticipant as the ContentFilteredTopic. This parameter cannot be NULL. The same related topic can be used in many different ContentFilteredTopics.
filter_expression	A logical expression on the contents on the Topic. If the expression evaluates to TRUE, a DDS sample is received; otherwise it is discarded. This parameter cannot be NULL. The notation for this expression depends on the filter that you are using (specified by the filter_name parameter). See SQL Filter Expression Notation and STRINGMATCH Filter Expression Notation. The filter_expression can be changed with set_expression() (Setting an Expression’s Filter and Parameters).
expression_parameters	A string sequence of filter expression parameters. Each parameter corresponds to a positional argument in the filter expression: element 0 corresponds to positional argument 0, element 1 to positional argument 1, and so forth. The expression_parameters can be changed with set_expression_parameters() or set_expression() (Setting an Expression’s Filter and Parameters), append_to_expression_parameter() (Appending a String to an Expression Parameter) and remove_from_expression_parameter() (Removing a String from an Expression Parameter).
filter_name	Name of the content filter to use for filtering. The filter must have been previously registered with the DomainParticipant (see Registering a Custom Filter). There are two builtin filters, DDS_SQLFILTER_NAME1 In the Java and C# APIs, you can access the names of the builtin filters by using DomainParticipant.SQLFILTER_NAME and DomainParticipant.STRINGMATCHFILTER_NAME. (the default filter) and DDS_STRINGMATCHFILTER_NAME—these are automatically registered. To use the STRINGMATCH filter, call create_contentfilteredtopic_with_filter() with "DDS_STRINGMATCHFILTER_NAME" as the filter_name. STRINGMATCH filter expressions have the syntax: <field name> MATCH <string pattern> (see STRINGMATCH Filter Expression Notation). 2 In the Java and C# APIs, you can access the names of the builtin filters by using DomainParticipant.SQLFILTER_NAME and DomainParticipant.STRINGMATCHFILTER_NAME.

If you run RTI Code Generator with -notypecode, you must use the "with_filter" version with a custom filter instead—do not use the builtin SQL filter or the STRINGMATCH filter with the -notypecode option because they require type codes.

To summarize:

• To use the builtin default SQL filter:
  • Do not use -notypecode when running RTI Code Generator
  • Call create_contentfilteredtopic()
  • See SQL Filter Expression Notation
• To use the builtin STRINGMATCH filter:
  • Do not use -notypecode when running RTI Code Generator
  • Call create_contentfilteredtopic_with_filter(), setting the filter_name to DDS_STRINGMATCHFILTER_NAME
  • See STRINGMATCH Filter Expression Notation
• To use a custom filter:
  • Call create_contentfilteredtopic_with_filter(), setting the filter_name to a registered custom filter
• To use RTI Code Generator with -notypecode:
  • Call create_contentfilteredtopic_with_filter(), setting the filter_name to a registered custom filter

Be careful with memory management of the string sequence in some of the ContentFilteredTopic APIs. See the String Support section in the API Reference HTML documentation (within the Infrastructure module) for details on sequences.

Creating ContentFilteredTopics for Built-in DDS Types

To create a ContentFilteredTopic for a built-in DDS type (see Built-in Data Types), use the standard DomainParticipant operations, create_contentfilteredtopic() or create_contentfilteredtopic_with_filter.

The field names used in the filter expressions for the built-in SQL (see SQL Filter Expression Notation) and StringMatch filters (see STRINGMATCH Filter Expression Notation) must correspond to the names provided in the IDL description of the built-in DDS types.

ContentFilteredTopic Creation Examples:

For simplicity, error handling is not shown in the following examples.

© 2018 RTI