35.2 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 35.6 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 35.5 SQL Filter Expression Notation and 35.6 STRINGMATCH Filter Expression Notation. The filter_expression can be changed with set_expression() (35.4.2 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() (35.4.2 Setting an Expression’s Filter and Parameters), append_to_expression_parameter() (35.4.3 Appending a String to an Expression Parameter) and remove_from_expression_parameter() (35.4.4 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 35.9.2 Registering a Custom Filter). There are two builtin filters, DDS_SQLFILTER_NAME1 In the Java API, you can access the names of the builtin filters by using DomainParticipant.SQLFILTER_NAME and DomainParticipant.STRINGMATCHFILTER_NAME. In the C# API, they can be found in the Filter class. (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 35.6 STRINGMATCH Filter Expression Notation). 2 In the Java API, you can access the names of the builtin filters by using DomainParticipant.SQLFILTER_NAME and DomainParticipant.STRINGMATCHFILTER_NAME. In the C# API, they can be found in the Filter class.

To summarize:

• To use the builtin default SQL filter:
  • Call create_contentfilteredtopic()
  • See 35.5 SQL Filter Expression Notation
• To use the builtin STRINGMATCH filter:
  • Call create_contentfilteredtopic_with_filter(), setting the filter_name to DDS_STRINGMATCHFILTER_NAME
  • See 35.6 STRINGMATCH Filter Expression Notation
• To use a custom filter:
  • 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.

35.2.1 Creating ContentFilteredTopics for Built-in DDS Types

To create a ContentFilteredTopic for a built-in DDS type (see 17.2 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 35.5 SQL Filter Expression Notation) and StringMatch filters (see 35.6 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.