RTI Connext C++ API  Version 5.0.0
DDSContentFilteredTopic Class Referenceabstract

<<interface>> Specialization of DDSTopicDescription that allows for content-based subscriptions. More...

Inheritance diagram for DDSContentFilteredTopic:
DDSTopicDescription

Public Member Functions

virtual const char * get_filter_expression ()=0
 Get the filter_expression.
 
virtual DDS_ReturnCode_t get_expression_parameters (DDS_StringSeq &parameters)=0
 Get the expression_parameters.
 
virtual DDS_ReturnCode_t set_expression_parameters (const DDS_StringSeq &parameters)=0
 Set the expression_parameters.
 
virtual DDS_ReturnCode_t append_to_expression_parameter (const DDS_Long index, const char *val)=0
 <<eXtension>> Appends a string term to the specified parameter string.
 
virtual DDS_ReturnCode_t remove_from_expression_parameter (const DDS_Long index, const char *val)=0
 <<eXtension>> Removes a string term from the specified parameter string.
 
virtual DDSTopicget_related_topic ()=0
 Get the related_topic.
 
- Public Member Functions inherited from DDSTopicDescription
virtual const char * get_type_name ()=0
 Get the associated type_name.
 
virtual const char * get_name ()=0
 Get the name used to create this DDSTopicDescription .
 
virtual DDSDomainParticipantget_participant ()=0
 Get the DDSDomainParticipant to which the DDSTopicDescription belongs.
 

Static Public Member Functions

static DDSContentFilteredTopicnarrow (DDSTopicDescription *topic_description)
 Narrow the given DDSTopicDescription pointer to a DDSContentFilteredTopic pointer.
 

Detailed Description

<<interface>> Specialization of DDSTopicDescription that allows for content-based subscriptions.

It describes a more sophisticated subscription that indicates a DDSDataReader does not want to necessarily see all values of each instance published under the DDSTopic. 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.

Note on Content-Based Filtering and Sparse Value Types

If you are a user of the Dynamic Data API, you may define sparse value types; that is, types for which every data sample need not include a value for every field defined in the type. (See DDS_TK_SPARSE and DDS_TypeCodeFactory::create_sparse_tc.) In order for a filter expression on a field to be well defined, that field must be present in the data sample. That means that you will only be able to perform a content-based filter on fields that are marked as DDS_TYPECODE_KEY_MEMBER or DDS_TYPECODE_NONKEY_REQUIRED_MEMBER.

Member Function Documentation

static DDSContentFilteredTopic* DDSContentFilteredTopic::narrow ( DDSTopicDescription topic_description)
static

Narrow the given DDSTopicDescription pointer to a DDSContentFilteredTopic pointer.

Returns
DDSContentFilteredTopic if this DDSTopicDescription is a DDSContentFilteredTopic. Otherwise, return NULL.
virtual const char* DDSContentFilteredTopic::get_filter_expression ( )
pure virtual

Get the filter_expression.

Return the filter_expression associated with the DDSContentFilteredTopic.

Returns
the filter_expression.
virtual DDS_ReturnCode_t DDSContentFilteredTopic::get_expression_parameters ( DDS_StringSeq parameters)
pure virtual

Get the expression_parameters.

Return the expression_parameters associated with the DDSContentFilteredTopic. expression_parameters is either specified on the last successful call to DDSContentFilteredTopic::set_expression_parameters or, if that method is never called, the parameters specified when the DDSContentFilteredTopic was created.

Parameters
parameters<<inout>> the filter expression parameters. The memory for the strings in this sequence is managed according to the conventions described in Conventions. In particular, be careful to avoid a situation in which RTI Connext allocates a string on your behalf and you then reuse that string in such a way that RTI Connext believes it to have more memory allocated to it than it actually does.
Returns
One of the Standard Return Codes
See Also
DDSDomainParticipant::create_contentfilteredtopic
DDSContentFilteredTopic::set_expression_parameters
virtual DDS_ReturnCode_t DDSContentFilteredTopic::set_expression_parameters ( const DDS_StringSeq parameters)
pure virtual

Set the expression_parameters.

Change the expression_parameters associated with the DDSContentFilteredTopic.

Parameters
parameters<<in>> the filter expression parameters . Length of sequence cannot be greater than 100.
Returns
One of the Standard Return Codes
virtual DDS_ReturnCode_t DDSContentFilteredTopic::append_to_expression_parameter ( const DDS_Long  index,
const char *  val 
)
pure virtual

<<eXtension>> Appends a string term to the specified parameter string.

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 DDS_STRINGMATCHFILTER_NAME filter, index must be 0.
val<<in>> The string term to be appended to the parameter string.
Returns
One of the Standard Return Codes
virtual DDS_ReturnCode_t DDSContentFilteredTopic::remove_from_expression_parameter ( const DDS_Long  index,
const char *  val 
)
pure virtual

<<eXtension>> Removes a string term from the specified parameter string.

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 DDS_STRINGMATCHFILTER_NAME filter, index must be 0.
val<<in>> The string term to be removed from the parameter string.
Returns
One of the Standard Return Codes
virtual DDSTopic* DDSContentFilteredTopic::get_related_topic ( )
pure virtual

Get the related_topic.

Return the DDSTopic specified when the DDSContentFilteredTopic was created.

Returns
The DDSTopic assocated with the DDSContentFilteredTopic.

RTI Connext C++ API Version 5.0.0 Copyright © Thu Aug 30 2012 Real-Time Innovations, Inc