Using a ContentFilteredTopic

Once you’ve created a ContentFilteredTopic, you can use the operations listed in ContentFilteredTopic Operations.

ContentFilteredTopic Operations

Operation	Description	Reference
append_to_expression_parameter	Concatenates a string value to the input expression parameter	Appending a String to an Expression Parameter
get_expression_parameters	Gets the expression parameters.	Getting the Current Expression Parameters
get_filter_expression	Gets the expression.	Getting the Filter Expression
get_related_topic	Gets the related Topic.	Getting the Related Topic
narrow	Casts a DDS_TopicDescription pointer to a ContentFilteredTopic pointer.	‘Narrowing’ a ContentFilteredTopic to a TopicDescription
remove_from_expression_parameter	Removes a string value from the input expression parameter	Removing a String from an Expression Parameter
set_expression	Changes the filter expression and parameters.	Setting an Expression’s Filter and Parameters
set_expression_parameters	Changes the expression parameters.

Getting the Current Expression Parameters

To get the expression parameters, use the ContentFilteredTopic’s get_expression_parameters() operation:

DDS_ReturnCode_t get_expression_parameters(struct DDS_StringSeq & parameters)

Where:

parameters

The filter expression parameters. The memory for the strings in this sequence is managed as described in the String Support section of the API Reference HTML documentation (within the Infrastructure module). In particular, be careful to avoid a situation in which Connext DDS allocates a string on your behalf and you then reuse that string in such a way that Connext DDS believes it to have more memory allocated to it than it actually does. This parameter cannot be NULL.

This operation gives you the expression parameters that were specified on the last successful call to set_expression_parameters() or set_expression(), or if they were never called, the parameters specified when the ContentFilteredTopic was created.

Setting an Expression’s Filter and Parameters

To change the filter expression and expression parameters associated with a ContentFilteredTopic:

DDS_ReturnCode set_expression(
	const char * expression, 
	const struct DDS_StringSeq & parameters)

To change just the expression parameters (not the filter expression):

DDS_ReturnCode_t set_expression_parameters(const struct DDS_StringSeq & parameters)

Where:

expression	The new expression to be set in the ContentFilteredTopic.
parameters	The filter expression parameters. Each element in the parameter sequence corresponds to a positional parameter in the filter expression. When using the default DDS_SQLFILTER_NAME, parameter strings are automatically converted to the member type. For example, "4" is converted to the integer 4. This parameter cannot be NULL.

The ContentFilteredTopic’s operations do not manage the sequences; you must ensure that the parameter sequences are valid. Please refer to the String Support section in the API Reference HTML documentation (within the Infrastructure module) for details on sequences.

Appending a String to an Expression Parameter

To concatenate a string to an expression parameter, use the ContentFilteredTopic's append_to_expression_parameter() operation:

DDS_ReturnCode_t append_to_expression_parameter(const DDS_Long index, const char* value);

When using the STRINGMATCH filter, index must be 0.

This function is only intended to be used with the builtin SQL and STRINGMATCH filters. This function can be used in expression parameters associated with MATCH operators (see SQL Extension: Regular Expression Matching) to add a pattern to the match pattern list. For example, if filter_expression is:

symbol MATCH 'IBM'

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

symbol MATCH 'IBM,MSFT'

Removing a String from an Expression Parameter

To remove a string from an expression parameter use the ContentFilteredTopic's remove_from_expression_parameter() operation:

DDS_ReturnCode_t remove_from_expression_parameter(const DDS_Long index,	const char* value)

When using the STRINGMATCH filter, index must be 0.

This function is only intended to be used with the builtin SQL and STRINGMATCH filters. It can be used in expression parameters associated with MATCH operators (see SQL Extension: Regular Expression Matching) to remove a pattern from the match pattern list. For example, if filter_expression is:

symbol MATCH 'IBM,MSFT'

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

symbol MATCH 'MSFT'

Getting the Filter Expression

To get the filter expression that was specified when the ContentFilteredTopic was created or when set_expression() was used:

const char* get_filter_expression ()

Getting the Related Topic

To get the related Topic that was specified when the ContentFilteredTopic was created:

DDS_Topic * get_related_topic ()

‘Narrowing’ a ContentFilteredTopic to a TopicDescription

To safely cast a DDS_TopicDescription pointer to a ContentFilteredTopic pointer, use the ContentFilteredTopic’s narrow() operation:

DDS_TopicDescription* narrow ()

© 2018 RTI