Creating Custom Content Filters

Working with custom content filters.

Working with custom content filters.

Introduction

By default, RTI Connext creates content filters with the DDS_SQL_FILTER, which implements a superset of the DDS-specified SQL WHERE clause. However, in many cases this filter may not be what you want. Some examples are:

• The default filter can only filter based on the content of a sample, not on a computation on the content of a sample. You can use a custom filter that is customized for a specific type and can filter based on a computation of the type members.
• You want to use a different filter language then SQL

This HOWTO explains how to write your own custom filter and is divided into the following sections:

• The Custom Content Filter API
• Example Using C format strings

The Custom Content Filter API

A custom content filter is created by calling the DDS_DomainParticipant_register_contentfilter function with a DDS_ContentFilter that contains a compile, an evaluate function and a finalize function. DDS_ContentFilteredTopic can be created with DDS_DomainParticipant_create_contentfilteredtopic_with_filter to use this filter.

A custom content filter is used by RTI Connext at the following times during the life-time of a DDS_ContentFilteredTopic (the function called is shown in parenthesis).

• When a DDS_ContentFilteredTopic is created (compile)
• When the filter parameters are changed on the DDS_ContentFilteredTopic (compile) with DDS_ContentFilteredTopic_set_expression_parameters
• When a sample is filtered (evaluate). This function is called by the RTI Connext core with a de-serialized sample
• When a DDS_ContentFilteredTopic is deleted (finalize)

The compile function

The compile function is used to compile a filter expression and expression parameters. Please note that the term compile is intentionally loosely defined. It is up to the user to decide what this function should do and return.

See DDS_ContentFilter::compile for details.

The evaluate function

The evaluate function is called each time a sample is received to determine if a sample should be filtered out and discarded.

See DDS_ContentFilter::evaluate for details.

The finalize function

The finalize function is called when an instance of the custom content filter is no longer needed. When this function is called, it is safe to free all resources used by this particular instance of the custom content filter.

See DDS_ContentFilter::finalize for details.

Example Using C format strings

Assume that you have a type Foo.

You want to write a custom filter function that will drop all samples where the value of Foo.x > x and x is a value determined by an expression parameter. The filter will only be used to filter samples of type Foo.

Writing the Compile Function

The first thing to note is that we can ignore the filter expression, since we already know what the expression is. The second is that x is a parameter that can be changed. By using this information, the compile function is very easy to implement. Simply return the parameter string. This string will then be passed to the evaluate function every time a sample of this type is filtered.

Below is the entire compile function.

 
DDS_ReturnCode_t
howto_write_simple_compile_function(void *handle,
                                    void **new_compile_data,
                                    const char *expression,
                                    const struct DDS_StringSeq *parameters,
                                    const struct DDS_TypeCode *type_code,
                                    const char *type_class_name,
                                    void *old_compile_data)
{
    *new_compile_data = (void*)DDS_String_dup(*DDS_StringSeq_get_reference(parameters,0));
 
    return DDS_RETCODE_OK;
}

Writing the Evaluate Function

The next step is to implement the evaluate function. The evaluate function receives the parameter string with the actual value to test against. Thus the evaluate function must read the actual value from the parameter string before evaluating the expression. Below is the entire evaluate function.

 
DDS_Boolean
howto_write_simple_evaluate_function(void *filter_data,
                                     void *compile_data,
                                     const void *sample,
                                     const struct DDS_FilterSampleInfo * meta_data)
{
    char *parameter = (char*)compile_data;
    DDS_Long x;
 
    Foo *foo_sample = (Foo*)sample;
 
    sscanf(parameter,"%d",&x);
 
    return (foo_sample->x > x ? DDS_BOOLEAN_FALSE : DDS_BOOLEAN_TRUE);
}

Writing the Finalize Function

The last function to write is the finalize function. It is safe to free all resources used by this particular instance of the custom content filter that is allocated in compile. Below is the entire finalize function.

 
void
howto_write_simple_finalize_function(void *filter_data,
                                     void *compile_data)
{
    /* free parameter string from compile function */
    DDS_String_free((char *)compile_data);
}

Registering the Filter

Before the custom filter can be used, it must be registered with RTI Connext:

 
    struct DDS_ContentFilter filter = DDS_ContentFilter_INITIALIZER;
    filter.compile = howto_write_simple_compile_function;
    filter.evaluate = howto_write_simple_evaluate_function;
    filter.finalize = howto_write_simple_finalize_function;
    filter.filter_data = NULL;
 
    if (DDS_DomainParticipant_register_contentfilter(
        participant, "MyCustomFilter", &filter) != DDS_RETCODE_OK) {
        printf("Failed to register custom filter\n");
    }

Unregistering the Filter

When the filter is no longer needed, it can be unregistered from RTI Connext:

 
    if (DDS_DomainParticipant_unregister_contentfilter(
        participant, "MyCustomFilter" ) != DDS_RETCODE_OK) {
        printf("Failed to unregister custom filter\n");
    }