RTI Connext C API  Version 5.1.0
Topics

DDS_Topic entity and associated elements More...

Data Structures

struct  DDS_InconsistentTopicStatus
 DDS_INCONSISTENT_TOPIC_STATUS More...
 
struct  DDS_TopicQos
 QoS policies supported by a DDS_Topic entity. More...
 
struct  DDS_TopicListener
 <<interface>> DDS_Listener for DDS_Topic entities. More...
 
struct  DDS_ContentFilter
 <<interface>> Interface to be used by a custom filter of a DDS_ContentFilteredTopic More...
 
struct  DDS_ExpressionProperty
 Provides additional information about the filter expression passed to DDS_ContentFilter::writer_compile. More...
 
struct  DDS_FilterSampleInfo
 Provides meta information associated with the sample. More...
 

Macros

#define DDS_InconsistentTopicStatus_INITIALIZER
 Initializer for new status instances.
 
#define DDS_TopicQos_INITIALIZER
 Initializer for new QoS instances.
 
#define DDS_TopicListener_INITIALIZER
 Initializer for new DDS_TopicListener.
 
#define DDS_ContentFilter_INITIALIZER
 Initializer for new DDS_ContentFilter.
 

Typedefs

typedef struct
DDS_TopicDescriptionImpl 
DDS_TopicDescription
 <<interface>> Base class for DDS_Topic, DDS_ContentFilteredTopic, and DDS_MultiTopic.
 
typedef struct DDS_TopicWrapperI DDS_Topic
 <<interface>> The most basic description of the data to be published and subscribed.
 
typedef void(* DDS_TopicListener_InconsistentTopicCallback )(void *listener_data, DDS_Topic *topic, const struct DDS_InconsistentTopicStatus *status)
 Prototype of DDS_TopicListener::on_inconsistent_topic.
 
typedef struct
DDS_ContentFilteredTopicWrapperI 
DDS_ContentFilteredTopic
 <<interface>> Specialization of DDS_TopicDescription that allows for content-based subscriptions.
 
typedef DDS_ReturnCode_t(* DDS_ContentFilterCompileFunction )(void *filter_data, 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)
 Prototype of DDS_ContentFilter::compile.
 
typedef DDS_Boolean(* DDS_ContentFilterEvaluateFunction )(void *filter_data, void *compile_data, const void *sample, const struct DDS_FilterSampleInfo *meta_data)
 Prototype of DDS_ContentFilter::evaluate.
 
typedef void(* DDS_ContentFilterFinalizeFunction )(void *filter_data, void *compile_data)
 Prototype of DDS_ContentFilter::finalize.
 
typedef void(* DDS_ContentFilterWriterFinalizeFunction )(void *filter_data, void *writer_filter_data, const struct DDS_Cookie_t *cookie)
 Prototype of DDS_ContentFilter::writer_finalize.
 
typedef DDS_ReturnCode_t(* DDS_ContentFilterWriterAttachFunction )(void *filter_data, void **writer_filter_data, void *reserved)
 Prototype of DDS_ContentFilter::writer_attach.
 
typedef void(* DDS_ContentFilterWriterDetachFunction )(void *filter_data, void *writer_filter_data)
 Prototype of DDS_ContentFilter::writer_detach.
 
typedef DDS_ReturnCode_t(* DDS_ContentFilterWriterCompileFunction )(void *filter_data, void *writer_filter_data, struct DDS_ExpressionProperty *prop, const char *expression, const struct DDS_StringSeq *parameters, const struct DDS_TypeCode *type_code, const char *type_class_name, const struct DDS_Cookie_t *cookie)
 Prototype of DDS_ContentFilter::writer_compile.
 
typedef struct DDS_CookieSeq *(* DDS_ContentFilterWriterEvaluateFunction )(void *filter_data, void *writer_filter_data, const void *sample, const struct DDS_FilterSampleInfo *meta_data)
 Prototype of DDS_ContentFilter::writer_evaluate.
 
typedef void(* DDS_ContentFilterWriterReturnLoanFunction )(void *filter_data, void *writer_filter_data, struct DDS_CookieSeq *cookies)
 Prototype of DDS_ContentFilter::writer_return_loan.
 
typedef struct DDS_MultiTopicImpl DDS_MultiTopic
 [Not supported (optional)] <<interface>> A specialization of DDS_TopicDescription that allows subscriptions that combine/filter/rearrange data coming from several topics.
 

Functions

DDS_ReturnCode_t DDS_InconsistentTopicStatus_initialize (struct DDS_InconsistentTopicStatus *self)
 Initializer for new status instances.
 
DDS_ReturnCode_t DDS_InconsistentTopicStatus_copy (struct DDS_InconsistentTopicStatus *self, const struct DDS_InconsistentTopicStatus *source)
 Copy the contents of the given status into this status.
 
DDS_ReturnCode_t DDS_InconsistentTopicStatus_finalize (struct DDS_InconsistentTopicStatus *self)
 Free any dynamic memory allocated by status instances.
 
DDS_Boolean DDS_TopicQos_equals (const struct DDS_TopicQos *self, const struct DDS_TopicQos *other)
 Compares two DDS_TopicQos for equality.
 
DDS_ReturnCode_t DDS_TopicQos_initialize (struct DDS_TopicQos *self)
 Initializer for new QoS instances.
 
DDS_ReturnCode_t DDS_TopicQos_copy (struct DDS_TopicQos *self, const struct DDS_TopicQos *source)
 Copy the contents of the given QoS into this QoS.
 
DDS_ReturnCode_t DDS_TopicQos_finalize (struct DDS_TopicQos *self)
 Free any dynamic memory allocated by the policies in this DDS_TopicQos.
 
const char * DDS_TopicDescription_get_type_name (DDS_TopicDescription *self)
 Get the associated type_name.
 
const char * DDS_TopicDescription_get_name (DDS_TopicDescription *self)
 Get the name used to create this DDS_TopicDescription .
 
DDS_DomainParticipantDDS_TopicDescription_get_participant (DDS_TopicDescription *self)
 Get the DDS_DomainParticipant to which the DDS_TopicDescription belongs.
 
DDS_EntityDDS_Topic_as_entity (DDS_Topic *topic)
 Access a DDS_Topic's DDS_Entity supertype instance.
 
DDS_TopicDescriptionDDS_Topic_as_topicdescription (DDS_Topic *topic)
 Access a DDS_Topic's DDS_TopicDescription supertype instance.
 
DDS_TopicDDS_Topic_narrow (DDS_TopicDescription *self)
 Narrow the given DDS_TopicDescription pointer to a DDS_Topic pointer.
 
DDS_TopicDDS_Topic_narrow_from_entity (DDS_Entity *self)
 Narrow the given DDS_Entity pointer to a DDS_Topic pointer.
 
DDS_ReturnCode_t DDS_Topic_get_inconsistent_topic_status (DDS_Topic *self, struct DDS_InconsistentTopicStatus *status)
 Allows the application to retrieve the DDS_INCONSISTENT_TOPIC_STATUS status of a DDS_Topic.
 
DDS_ReturnCode_t DDS_Topic_set_qos (DDS_Topic *self, const struct DDS_TopicQos *qos)
 Set the topic QoS.
 
DDS_ReturnCode_t DDS_Topic_set_qos_with_profile (DDS_Topic *self, const char *library_name, const char *profile_name)
 <<eXtension>> Change the QoS of this topic using the input XML QoS profile.
 
DDS_ReturnCode_t DDS_Topic_get_qos (DDS_Topic *self, struct DDS_TopicQos *qos)
 Get the topic QoS.
 
DDS_ReturnCode_t DDS_Topic_set_listener (DDS_Topic *self, const struct DDS_TopicListener *l, DDS_StatusMask mask)
 Set the topic listener.
 
struct DDS_TopicListener DDS_Topic_get_listener (DDS_Topic *self)
 Get the topic listener.
 
DDS_ReturnCode_t DDS_Topic_get_listenerX (DDS_Topic *self, struct DDS_TopicListener *listener)
 <<eXtension>> Get the topic listener.
 
DDS_TopicDescriptionDDS_ContentFilteredTopic_as_topicdescription (DDS_ContentFilteredTopic *contentFilteredTopic)
 Access a DDS_ContentFilteredTopic's supertype instance.
 
DDS_ContentFilteredTopicDDS_ContentFilteredTopic_narrow (DDS_TopicDescription *self)
 Narrow the given DDS_TopicDescription pointer to a DDS_ContentFilteredTopic pointer.
 
const char * DDS_ContentFilteredTopic_get_filter_expression (DDS_ContentFilteredTopic *self)
 Get the filter_expression.
 
DDS_ReturnCode_t DDS_ContentFilteredTopic_get_expression_parameters (DDS_ContentFilteredTopic *self, struct DDS_StringSeq *parameters)
 Get the expression_parameters.
 
DDS_ReturnCode_t DDS_ContentFilteredTopic_set_expression_parameters (DDS_ContentFilteredTopic *self, const struct DDS_StringSeq *parameters)
 Set the expression_parameters.
 
DDS_ReturnCode_t DDS_ContentFilteredTopic_set_expression (DDS_ContentFilteredTopic *self, const char *expression, const struct DDS_StringSeq *parameters)
 Set the filter_expression and expression_parameters.
 
DDS_ReturnCode_t DDS_ContentFilteredTopic_append_to_expression_parameter (DDS_ContentFilteredTopic *self, const DDS_Long index, const char *val)
 <<eXtension>> Appends a string term to the specified parameter string.
 
DDS_ReturnCode_t DDS_ContentFilteredTopic_remove_from_expression_parameter (DDS_ContentFilteredTopic *self, const DDS_Long index, const char *val)
 <<eXtension>> Removes a string term from the specified parameter string.
 
DDS_TopicDDS_ContentFilteredTopic_get_related_topic (DDS_ContentFilteredTopic *self)
 Get the related_topic.
 
DDS_TopicDescriptionDDS_MultiTopic_as_topicdescription (DDS_MultiTopic *multiTopic)
 Access a DDS_MultiTopic's supertype instance.
 
DDS_MultiTopicDDS_MultiTopic_narrow (DDS_TopicDescription *self)
 Narrow the given DDS_TopicDescription pointer to a DDS_MultiTopic pointer.
 
const char * DDS_MultiTopic_get_subscription_expression (DDS_MultiTopic *self)
 Get the expression for this DDS_MultiTopic.
 
DDS_ReturnCode_t DDS_MultiTopic_get_expression_parameters (DDS_MultiTopic *self, struct DDS_StringSeq *parameters)
 Get the expression parameters.
 
DDS_ReturnCode_t DDS_MultiTopic_set_expression_parameters (DDS_MultiTopic *self, const struct DDS_StringSeq *parameters)
 Set the expression_parameters.
 

Detailed Description

DDS_Topic entity and associated elements

Macro Definition Documentation

#define DDS_InconsistentTopicStatus_INITIALIZER

Initializer for new status instances.

New DDS_InconsistentTopicStatus instances that are stored on the stack should be initialized with this value before they are passed to any function. This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory.

The simplest way to create a status structure is to initialize it on the stack at the time of its creation. DDS_InconsistentTopicStatus_finalize should be called to free the contained fields that use dynamic memory:

DDS_Topic_get_inconsistent_topic(myTopic, &myStatus);
See Also
DDS_InconsistentTopicStatus_initialize
DDS_Topic_get_inconsistent_topic_status
DDS_InconsistentTopicStatus_finalize
#define DDS_TopicQos_INITIALIZER

Initializer for new QoS instances.

New DDS_TopicQos instances stored on the stack should be initialized with this value before they are passed to any function. This step ensures that those contained QoS policies that use dynamic memory are properly initialized. This does not allocate memory.

The simplest way to create a new QoS structure is to initialize it on the stack at the time of its creation:

Note that the above assignment is not a substitute for calling DDS_DomainParticipant_get_default_topic_qos or DDS_Topic_get_qos; one of those should be called subsequently to setting the QoS of a new or existing entity. DDS_TopicQos_finalize should be called to free the contained QoS policies that use dynamic memory:

See Also
DDS_DomainParticipant_get_default_topic_qos
DDS_TopicQos_finalize
#define DDS_TopicListener_INITIALIZER

Initializer for new DDS_TopicListener.

All the new DDS_TopicListener instances allocated in the stack should be initialized to this value.No memory is allocated.

/* initialize listener functions */
listener.on_inconsistent_topic = ....;
DDS_Topic_set_listener(myTopic, &listener, mask);
See Also
DDS_Topic_set_listener
DDS_TopicListener
#define DDS_ContentFilter_INITIALIZER

Initializer for new DDS_ContentFilter.

All the new DDS_ContentFilter instances allocated in the stack should be initialized to this value. No memory is allocated.

See Also
DDS_ContentFilter
DDS_DomainParticipant_create_contentfilteredtopic_with_filter

Typedef Documentation

typedef struct DDS_TopicDescriptionImpl DDS_TopicDescription

<<interface>> Base class for DDS_Topic, DDS_ContentFilteredTopic, and DDS_MultiTopic.

DDS_TopicDescription represents the fact that both publications and subscriptions are tied to a single data-type. Its attribute type_name defines a unique resulting type for the publication or the subscription and therefore creates an implicit association with a DDS_TypeSupport.

DDS_TopicDescription has also a name that allows it to be retrieved locally.

See Also
DDS_TypeSupport, FooTypeSupport
typedef struct DDS_TopicWrapperI DDS_Topic

<<interface>> The most basic description of the data to be published and subscribed.

QoS:
DDS_TopicQos
Status:
DDS_INCONSISTENT_TOPIC_STATUS, DDS_InconsistentTopicStatus
Listener:
DDS_TopicListener

A DDS_Topic is identified by its name, which must be unique in the whole domain. In addition (by virtue of extending DDS_TopicDescription) it fully specifies the type of the data that can be communicated when publishing or subscribing to the DDS_Topic.

DDS_Topic is the only DDS_TopicDescription that can be used for publications and therefore associated with a DDS_DataWriter.

The following operations may be called even if the DDS_Topic is not enabled. Other operations will fail with the value DDS_RETCODE_NOT_ENABLED if called on a disabled DDS_Topic:

  • All the base-class operations set_qos(), set_qos_with_profile(), get_qos(), set_listener(), get_listener() enable(), get_statuscondition() and get_status_changes()
  • get_inconsistent_topic_status()
See Also
Operations Allowed in Listener Callbacks
typedef void(* DDS_TopicListener_InconsistentTopicCallback)(void *listener_data, DDS_Topic *topic, const struct DDS_InconsistentTopicStatus *status)

Prototype of DDS_TopicListener::on_inconsistent_topic.

Parameters
listener_data<<out>> Data associated with the listener when the listener is set
topic<<out>> Locally created DDS_Topic that triggers the listener callback
status<<out>> Current inconsistent status of the locally created DDS_Topic
typedef struct DDS_ContentFilteredTopicWrapperI DDS_ContentFilteredTopic

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

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

typedef DDS_ReturnCode_t(* DDS_ContentFilterCompileFunction)(void *filter_data, 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)

Prototype of DDS_ContentFilter::compile.

Compile an instance of the content filter according to the filter expression and parameters of the given data type.

This function is called when an instance of the locally registered content filter is created or when the expression parameter for the locally registered content filter instance is changed.

An instance of the locally registered content filter is created every time a local DDS_ContentFilteredTopic with the matching filter name is created, or when a DDS_DataReader with a matching filter name is discovered.

It is possible for multiple threads to be calling into this function at the same time. However, this function will never be called on a content filter that has been unregistered.

Parameters
filter_data<<in>> The opaque pointer that the content filter was registered with in DDS_DomainParticipant_register_contentfilter. Can be NULL. When a custom filter is registered, it is registered with a filter_data. This filter_data is user defined, e.g., it could be a reference to a program context. This is useful if the content filter functions are registered with different filter names. For instance, each filter name could have its own context and the DDS_ContentFilter::compile function can access this context.
new_compile_data<<out>> User specified opaque pointer of this instance of the content filter. This value is then passed to the DDS_ContentFilter::evaluate and DDS_ContentFilter::finalize functions for this instance of the content filter. Can be set to NULL.
expression<<in>> An ASCIIZ string with the filter expression. The memory used by this string is owned by RTI Connext and must not be freed. If you want to manipulate this string, you must first make a copy of it.
parameters<<in>> A string sequence with the expression parameters the DDS_ContentFilteredTopic was created with. The string sequence is equal (but not identical) to the string sequence passed to DDS_DomainParticipant_create_contentfilteredtopic. Note that the sequence passed to the compile function is owned by RTI Connext and must not be referenced outside the compile function.
type_code<<in>> A pointer to the type code for the related DDS_Topic of the DDS_ContentFilteredTopic. A type_code is a description of a type in terms of which types it contains (such as long, string, etc.) and the corresponding member field names in the data type structure. The type code can be used to write custom content filters that can be used with any type.
type_class_name<<in>> Fully qualified class name of the related DDS_Topic.
old_compile_data<<in>> The previous new_compile_data value from a previous call to this instance of a content filter. If the compile function is called more than once for an instance of a DDS_ContentFilteredTopic, e.g., if the expression parameters are changed, then the new_compile_data value returned by the previous invocation is passed in the old_compile_data parameter (which can be NULL). If this is a new instance of the filter, NULL is passed. This parameter is useful for freeing or reusing previously allocated resources.
Returns
One of the Standard Return Codes
typedef DDS_Boolean(* DDS_ContentFilterEvaluateFunction)(void *filter_data, void *compile_data, const void *sample, const struct DDS_FilterSampleInfo *meta_data)

Prototype of DDS_ContentFilter::evaluate.

Evaluate whether the sample is passing the filter or not according to the sample content.

This function is called when a sample for a locally created DDS_DataReader associated with the filter is received, or when a sample for a discovered DDS_DataReader assocated with the filter needs to be sent.

It is possible for multiple threads to be calling into this function at the same time. However, this function will never be called on a content filter that has been unregistered.

Parameters
filter_data<<in>> The opaque pointer that the content filter was registered with in DDS_DomainParticipant_register_contentfilter. Can be NULL.
compile_data<<in>> The last return value of the DDS_ContentFilter::compile function for this instance of the content filter. Can be NULL.
sample<<in>> Pointer to a deserialized sample to be filtered
meta_data<<in>> Pointer to meta data associated with the sample.
Returns
The function must return 0 if the sample should be filtered out, non zero otherwise
typedef void(* DDS_ContentFilterFinalizeFunction)(void *filter_data, void *compile_data)

Prototype of DDS_ContentFilter::finalize.

A previously compiled instance of the content filter is no longer in use and resources can now be cleaned up.

This function is called when an instance of the locally registered content filter is deleted.

An instance of the locally registered content filter is deleted every time a local DDS_ContentFilteredTopic with the matching filter name is deleted, or when a DDS_DataReader with a matching filter name is removed due to discovery.

This function is also called on all instances of the discovered DDS_DataReader with a matching filter name if the filter is unregistered with DDS_DomainParticipant_unregister_contentfilter

It is possible for multiple threads to be calling into this function at the same time. However, this function will never be called on a content filter that has been unregistered.

Parameters
filter_data<<in>> The opaque pointer that the content filter was registered with in DDS_DomainParticipant_register_contentfilter. Can be NULL.
compile_data<<in>> The last return value of the DDS_ContentFilter::compile function for this instance of the content filter. Can be NULL.
typedef void(* DDS_ContentFilterWriterFinalizeFunction)(void *filter_data, void *writer_filter_data, const struct DDS_Cookie_t *cookie)

Prototype of DDS_ContentFilter::writer_finalize.

A writer-side filtering API to clean up a previously compiled instance of the content filter.

This function is called to notify the filter implementation that the DDS_DataWriter is no longer matching with a DDS_DataReader for which it was previously performing writer-side filtering. This will allow the filter to purge any state it was maintaining for the DDS_DataReader.

It is possible for multiple threads to be calling into this function at the same time.

Parameters
filter_data<<in>> The opaque pointer that the content filter was registered with in DDS_DomainParticipant_register_contentfilter. Can be NULL.
writer_filter_data<<in>> A pointer to the state created using DDS_ContentFilter::writer_attach.
cookieDDS_Cookie_t to uniquely identify DDS_DataReader for which DDS_ContentFilter::writer_finalize was called.
typedef DDS_ReturnCode_t(* DDS_ContentFilterWriterAttachFunction)(void *filter_data, void **writer_filter_data, void *reserved)

Prototype of DDS_ContentFilter::writer_attach.

A writer-side filtering API to create some state that can facilitate filtering on the writer side.

This function is called to create some state required to perform filtering on the writer side using writer-side filtering APIs. This function will be called for every DDS_DataWriter; it will be called only the first time the DDS_DataWriter matches a DDS_DataReader using the specified filter. This function will not be called for any subsequent DataReaders that match the DataWriter and are using the same filter.

Parameters
filter_data<<in>> The opaque pointer that the content filter was registered with in DDS_DomainParticipant_register_contentfilter. Can be NULL.
writer_filter_data<<out>> A user-specified opaque pointer to some state created on the DDS_DataWriter that will help perform writer-side filtering efficiently.
typedef void(* DDS_ContentFilterWriterDetachFunction)(void *filter_data, void *writer_filter_data)

Prototype of DDS_ContentFilter::writer_detach.

A writer-side filtering API to clean up a previously created state using DDS_ContentFilter::writer_attach.

This function is called to delete any state created using the DDS_ContentFilter::writer_attach function. This function will be called when the DDS_DataWriter is deleted.

Parameters
filter_data<<in>> The opaque pointer that the content filter was registered in DDS_DomainParticipant_register_contentfilter. Can be NULL.
writer_filter_data<<in>> A pointer to the state created using DDS_ContentFilter::writer_attach.
typedef DDS_ReturnCode_t(* DDS_ContentFilterWriterCompileFunction)(void *filter_data, void *writer_filter_data, struct DDS_ExpressionProperty *prop, const char *expression, const struct DDS_StringSeq *parameters, const struct DDS_TypeCode *type_code, const char *type_class_name, const struct DDS_Cookie_t *cookie)

Prototype of DDS_ContentFilter::writer_compile.

A writer-side filtering API to compile an instance of the content filter according to the filter expression and parameters specified by a matching DDS_DataReader.

This function is called when the DDS_DataWriter discovers a DDS_DataReader with a DDS_ContentFilteredTopic or when a DDS_DataWriter is notified of a change in a DataReader's filter parameter for the locally registered content filter instance.

It is possible for multiple threads to be calling into this function at the same time.

Parameters
filter_data<<in>> The opaque pointer that the content filter was registered with in DDS_DomainParticipant_register_contentfilter. Can be NULL.
writer_filter_data<<in>> A pointer to the state created using DDS_ContentFilter::writer_attach .
prop<<out>> A pointer to DDS_ExpressionProperty that allows you to indicate to RTI Connext if a filter expression can be optimized.
expression<<in>> An ASCIIZ string with the filter expression. The memory used by this string is owned by RTI Connext and must not be freed. If you want to manipulate this string, you must first make a copy of it.
parameters<<in>> A string sequence with the expression parameters with which the DDS_ContentFilteredTopic was created. The string sequence is equal (but not identical) to the string sequence passed to DDS_DomainParticipant_create_contentfilteredtopic. Note that the sequence passed to the compile function is owned by RTI Connext and must not be referenced outside the compile function.
type_code<<in>> A pointer to the type code for the related DDS_Topic of the DDS_ContentFilteredTopic. A type_code is a description of a type in terms of which types it contains (such as long, string, etc.) and the corresponding member field names in the data type structure. The type code can be used to write custom content filters that can be used with any type.
type_class_name<<in>> Fully qualified class name of the related DDS_Topic.
cookie<<in>> DDS_Cookie_t to uniquely identify DDS_DataReader for which DDS_ContentFilter::writer_compile was called.
Returns
One of the Standard Return Codes
typedef struct DDS_CookieSeq*(* DDS_ContentFilterWriterEvaluateFunction)(void *filter_data, void *writer_filter_data, const void *sample, const struct DDS_FilterSampleInfo *meta_data)
read

Prototype of DDS_ContentFilter::writer_evaluate.

A writer-side filtering API to retrieve a list of DataReaders whose content filters pass the sample.

This function is called every time a DDS_DataWriter writes a new sample. Its purpose is to evaluate the sample for all the readers for which the DDS_DataWriter is performing writer-side filtering and return the list of Cookie_t structures associated with the DataReaders whose filters pass the sample.

It is possible for multiple threads to be calling into this function at the same time

Parameters
filter_data<<in>> The opaque pointer that the content filter was registered with in DDS_DomainParticipant_register_contentfilter. Can be NULL.
writer_filter_data<<in>> A pointer to the state created using DDS_ContentFilter::writer_attach .
sample<<in>> Pointer to a deserialized sample to be filtered.
meta_data<<in>> Pointer to meta data associated with the sample.
Returns
The function returns ::DDS_CookieSeq which identifies the set of DataReaders whose filters pass the sample.
typedef void(* DDS_ContentFilterWriterReturnLoanFunction)(void *filter_data, void *writer_filter_data, struct DDS_CookieSeq *cookies)

Prototype of DDS_ContentFilter::writer_return_loan.

A writer-side filtering API to return the loan on the list of DataReaders returned by DDS_ContentFilter::writer_evaluate.

This function is called to return the loan on ::DDS_CookieSeq returned by DDS_ContentFilter::writer_return_loan. It is possible for multiple threads to be calling into this function at the same time.

Parameters
filter_data<<in>> The opaque pointer that the content filter was registered with in DDS_DomainParticipant_register_contentfilter. Can be NULL.
writer_filter_data<<in>> A pointer to the state created using DDS_ContentFilter::writer_attach.
cookies<<in>> ::DDS_CookieSeq for which the DDS_ContentFilter::writer_return_loan was invoked.
typedef struct DDS_MultiTopicImpl DDS_MultiTopic

[Not supported (optional)] <<interface>> A specialization of DDS_TopicDescription that allows subscriptions that combine/filter/rearrange data coming from several topics.

DDS_MultiTopic allows a more sophisticated subscription that can select and combine data received from multiple topics into a single resulting type (specified by the inherited type_name). The data will then be filtered (selection) and possibly re-arranged (aggregation/projection) according to a subscription_expression with parameters expression_parameters.

  • The subscription_expression is a string that identifies the selection and re-arrangement of data from the associated topics. It is similar to an SQL statement where the SELECT part provides the fields to be kept, the FROM part provides the names of the topics that are searched for those fields, and the WHERE clause gives the content filter. The Topics combined may have different types but they are restricted in that the type of the fields used for the NATURAL JOIN operation must be the same.
  • The expression_parameters attribute is a sequence of strings that give values to the 'parameters' (i.e. "%n" tokens) in the subscription_expression. The number of supplied parameters must fit with the requested values in the subscription_expression (i.e. the number of n tokens).

Note that the source for data may not be restricted to a single topic.

DDS_DataReader entities associated with a DDS_MultiTopic may access instances that are "constructed" at the DDS_DataReader side from the instances written by multiple DDS_DataWriter entities. The DDS_MultiTopic access instance will begin to exist as soon as all the constituting DDS_Topic instances are in existence. The view_state and instance_state is computed from the corresponding states of the constituting instances:

Queries and Filters Syntax describes the syntax of subscription_expression and expression_parameters.

Function Documentation

DDS_ReturnCode_t DDS_InconsistentTopicStatus_initialize ( struct DDS_InconsistentTopicStatus self)

Initializer for new status instances.

New DDS_InconsistentTopicStatus instances stored in heap memory should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.

DDS_InconsistentTopicStatus_finalize should be called to free the contained fields that use dynamic memory:

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See Also
DDS_InconsistentTopicStatus_INITIALIZER
DDS_Topic_get_inconsistent_topic_status
DDS_InconsistentTopicStatus_finalize
DDS_ReturnCode_t DDS_InconsistentTopicStatus_copy ( struct DDS_InconsistentTopicStatus self,
const struct DDS_InconsistentTopicStatus source 
)

Copy the contents of the given status into this status.

Status instances can use dynamic memory because of the sequences contained in some status. A shallow copy by assignment is therefore unsafe. This function performs a deep copy, allocating memory if necessary.

Parameters
self<<in>> Cannot be NULL.
source<<in>>. Status to be copied from.
Returns
One of the Standard Return Codes
See Also
DDS_InconsistentTopicStatus_INITIALIZER
DDS_InconsistentTopicStatus_initialize
DDS_InconsistentTopicStatus_finalize
DDS_ReturnCode_t DDS_InconsistentTopicStatus_finalize ( struct DDS_InconsistentTopicStatus self)

Free any dynamic memory allocated by status instances.

Some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status unchanged. It should be called on all instances before they are freed (or, in the case of stack-based instances, before they go out of scope).

Note that if this status instance is stored in heap memory, calling this function will not call free() on it; the user is responsible for explicitly freeing any heap-based status instance after calling this function.

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See Also
DDS_InconsistentTopicStatus_INITIALIZER
DDS_InconsistentTopicStatus_initialize
DDS_Boolean DDS_TopicQos_equals ( const struct DDS_TopicQos self,
const struct DDS_TopicQos other 
)

Compares two DDS_TopicQos for equality.

Parameters
self<<in>> This TopicQos.
other<<in>> The other TopicQos to be compared with this TopicQos.
Returns
DDS_BOOLEAN_TRUE if the two Qos objects are equal or DDS_BOOLEAN_FALSE otherwise.
DDS_ReturnCode_t DDS_TopicQos_initialize ( struct DDS_TopicQos self)

Initializer for new QoS instances.

New DDS_TopicQos instances on heap should be initialized with this function before they are passed to any function. This step ensures that those contained QoS policies that use dynamic memory are properly initialized. This function does not allocate memory.

Calling this function is not a substitute for calling DDS_Topic_get_qos or DDS_DomainParticipant_get_default_topic_qos; one of those should be called subsequently to setting the QoS of any new or existing entity. DDS_TopicQos_finalize should be called to free the contained QoS policies that use dynamic memory:

DDS_TopicQos *myQos = malloc(sizeof(struct DDS_TopicQos));
DDS_DomainParticipantFactory_get_default_topic_qos(myFactory, myQos);
DDS_Topic_set_qos(myTopic, myQos);
free(myQos);
Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See Also
DDS_TopicQos_INITIALIZER
DDS_DomainParticipant_get_default_topic_qos
DDS_TopicQos_finalize
DDS_ReturnCode_t DDS_TopicQos_copy ( struct DDS_TopicQos self,
const struct DDS_TopicQos source 
)

Copy the contents of the given QoS into this QoS.

DDS_TopicQos instances can use dynamic memory because of the sequences contained in some QoS policies. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.

Parameters
self<<in>> Cannot be NULL.
source<<in>>. QoS to be copied from.
Returns
One of the Standard Return Codes
See Also
DDS_TopicQos_INITIALIZER
DDS_TopicQos_initialize
DDS_TopicQos_finalize
DDS_ReturnCode_t DDS_TopicQos_finalize ( struct DDS_TopicQos self)

Free any dynamic memory allocated by the policies in this DDS_TopicQos.

Some QoS policies may use dynamic memory (regardless of whether the QoS itself is in dynamic memory). This function frees that memory but otherwise leaves this QoS unchanged. It should be called on all instances before they are freed (or, in the case of stack-based instances, before they go out of scope).

This function does not leave this object in an invalid state. It is permissable to clear a QoS and then subsequently allocate new dynamic memory in one or more of its QoS policies.

Note that if this QoS instance is stored in heap memory, calling this function will not call free() on it; the user is responsible for explicitly freeing any heap-based QoS instance after calling this function.

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See Also
DDS_TopicQos_INITIALIZER
DDS_TopicQos_initialize
const char* DDS_TopicDescription_get_type_name ( DDS_TopicDescription self)

Get the associated type_name.

The type name defines a locally unique type for the publication or the subscription.

The type_name corresponds to a unique string used to register a type via the FooTypeSupport_register_type function.

Thus, the type_name implies an association with a corresponding DDS_TypeSupport and this DDS_TopicDescription.

Parameters
self<<in>> Cannot be NULL.
Returns
the type name. The returned type name is valid until the DDS_TopicDescription is deleted.
Postcondition
The result is non-NULL.
See Also
DDS_TypeSupport, FooTypeSupport
const char* DDS_TopicDescription_get_name ( DDS_TopicDescription self)

Get the name used to create this DDS_TopicDescription .

Parameters
self<<in>> Cannot be NULL.
Returns
the name used to create this DDS_TopicDescription. The returned topic name is valid until the DDS_TopicDescription is deleted.
Postcondition
The result is non-NULL.
DDS_DomainParticipant* DDS_TopicDescription_get_participant ( DDS_TopicDescription self)

Get the DDS_DomainParticipant to which the DDS_TopicDescription belongs.

Parameters
self<<in>> Cannot be NULL.
Returns
The DDS_DomainParticipant to which the DDS_TopicDescription belongs.
Postcondition
The result is non-NULL.
DDS_Entity* DDS_Topic_as_entity ( DDS_Topic topic)

Access a DDS_Topic's DDS_Entity supertype instance.

Returns
DDS_Topic's supertype DDS_Entity instance
DDS_TopicDescription* DDS_Topic_as_topicdescription ( DDS_Topic topic)

Access a DDS_Topic's DDS_TopicDescription supertype instance.

Returns
DDS_Topic's supertype DDS_TopicDescription instance
DDS_Topic* DDS_Topic_narrow ( DDS_TopicDescription self)

Narrow the given DDS_TopicDescription pointer to a DDS_Topic pointer.

Returns
DDS_Topic if this DDS_TopicDescription is a DDS_Topic. Otherwise, return NULL.
DDS_Topic* DDS_Topic_narrow_from_entity ( DDS_Entity self)

Narrow the given DDS_Entity pointer to a DDS_Topic pointer.

Parameters
self<<in>> Cannot be NULL.
Returns
DDS_Topic if this DDS_Entity is a DDS_Topic. Otherwise, return NULL.
DDS_ReturnCode_t DDS_Topic_get_inconsistent_topic_status ( DDS_Topic self,
struct DDS_InconsistentTopicStatus status 
)

Allows the application to retrieve the DDS_INCONSISTENT_TOPIC_STATUS status of a DDS_Topic.

Retrieve the current DDS_InconsistentTopicStatus

Parameters
self<<in>> Cannot be NULL.
status<<inout>> Status to be retrieved. Cannot be NULL.
Returns
One of the Standard Return Codes
See Also
DDS_InconsistentTopicStatus
DDS_ReturnCode_t DDS_Topic_set_qos ( DDS_Topic self,
const struct DDS_TopicQos qos 
)

Set the topic QoS.

The DDS_TopicQos::topic_data and DDS_TopicQos::deadline, DDS_TopicQos::latency_budget, DDS_TopicQos::transport_priority and DDS_TopicQos::lifespan can be changed. The other policies are immutable.

Parameters
qos<<in>> Set of policies to be applied to DDS_Topic.

Policies must be consistent. Immutable policies cannot be changed after DDS_Topic is enabled. The special value DDS_TOPIC_QOS_DEFAULT can be used to indicate that the QoS of the DDS_Topic should be changed to match the current default DDS_TopicQos set in the DDS_DomainParticipant. Cannot be NULL.

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY if immutable policy is changed, or DDS_RETCODE_INCONSISTENT_POLICY if policies are inconsistent
See Also
DDS_TopicQos for rules on consistency among QoS
set_qos (abstract)
Operations Allowed in Listener Callbacks
DDS_ReturnCode_t DDS_Topic_set_qos_with_profile ( DDS_Topic self,
const char *  library_name,
const char *  profile_name 
)

<<eXtension>> Change the QoS of this topic using the input XML QoS profile.

The DDS_TopicQos::topic_data and DDS_TopicQos::deadline, DDS_TopicQos::latency_budget, DDS_TopicQos::transport_priority and DDS_TopicQos::lifespan can be changed. The other policies are immutable.

Parameters
self<<in>> Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS_DomainParticipant_set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_DomainParticipant_set_default_profile).
Returns
One of the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY if immutable policy is changed, or DDS_RETCODE_INCONSISTENT_POLICY if policies are inconsistent
See Also
DDS_TopicQos for rules on consistency among QoS
Operations Allowed in Listener Callbacks
DDS_ReturnCode_t DDS_Topic_get_qos ( DDS_Topic self,
struct DDS_TopicQos qos 
)

Get the topic QoS.

This function may potentially allocate memory depending on the sequences contained in some QoS policies.

Parameters
self<<in>> Cannot be NULL.
qos<<inout>> QoS to be filled up. Cannot be NULL.
Returns
One of the Standard Return Codes
See Also
get_qos (abstract)
DDS_ReturnCode_t DDS_Topic_set_listener ( DDS_Topic self,
const struct DDS_TopicListener l,
DDS_StatusMask  mask 
)

Set the topic listener.

Parameters
self<<in>> Cannot be NULL.
l<<in>> Listener to be installed on entity.
mask<<in>> Changes of communication status to be invoked on the listener. See DDS_StatusMask. The callback function on the listener cannot be NULL if the corresponding status is turned on in the mask.
Returns
One of the Standard Return Codes
See Also
set_listener (abstract)
struct DDS_TopicListener DDS_Topic_get_listener ( DDS_Topic self)
read

Get the topic listener.

Parameters
self<<in>> Cannot be NULL.
Returns
Existing listener attached to the DDS_Topic.
See Also
DDS_Topic_get_listenerX
get_listener (abstract)
DDS_ReturnCode_t DDS_Topic_get_listenerX ( DDS_Topic self,
struct DDS_TopicListener listener 
)

<<eXtension>> Get the topic listener.

An alternative form of get_listener that fills in an existing listener structure rather than returning one on the stack.

Parameters
self<<in>> Cannot be NULL.
listener<<inout>> Listener structure to be filled up. Cannnot be NULL.
See Also
DDS_Topic_get_listener
get_listener (abstract)
DDS_TopicDescription* DDS_ContentFilteredTopic_as_topicdescription ( DDS_ContentFilteredTopic contentFilteredTopic)

Access a DDS_ContentFilteredTopic's supertype instance.

Parameters
contentFilteredTopic<<in>> Cannot be NULL.
Returns
DDS_ContentFilteredTopic's supertype DDS_TopicDescription instance
DDS_ContentFilteredTopic* DDS_ContentFilteredTopic_narrow ( DDS_TopicDescription self)

Narrow the given DDS_TopicDescription pointer to a DDS_ContentFilteredTopic pointer.

Parameters
self<<in>> Cannot be NULL.
Returns
DDS_ContentFilteredTopic if this DDS_TopicDescription is a DDS_ContentFilteredTopic. Otherwise, return NULL.
const char* DDS_ContentFilteredTopic_get_filter_expression ( DDS_ContentFilteredTopic self)

Get the filter_expression.

Return the filter_expression associated with the DDS_ContentFilteredTopic. filter_expression is either specified on the last successful call to DDS_ContentFilteredTopic_set_expression or, if that function is never called, the expression specified when the DDS_ContentFilteredTopic was created.

Parameters
self<<in>> Cannot be NULL.
Returns
the filter_expression.
DDS_ReturnCode_t DDS_ContentFilteredTopic_get_expression_parameters ( DDS_ContentFilteredTopic self,
struct DDS_StringSeq parameters 
)

Get the expression_parameters.

Return the expression_parameters associated with the DDS_ContentFilteredTopic. expression_parameters is either specified on the last successful call to DDS_ContentFilteredTopic_set_expression_parameters, DDS_ContentFilteredTopic_set_expression or, if that function is never called, the parameters specified when the DDS_ContentFilteredTopic was created.

Parameters
self<<in>> Cannot be NULL.
parameters<<inout>> the filter expression parameters. Cannot be NULL.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
DDS_DomainParticipant_create_contentfilteredtopic
DDS_ContentFilteredTopic_set_expression_parameters
DDS_ReturnCode_t DDS_ContentFilteredTopic_set_expression_parameters ( DDS_ContentFilteredTopic self,
const struct DDS_StringSeq parameters 
)

Set the expression_parameters.

Change the expression_parameters associated with the DDS_ContentFilteredTopic.

Parameters
self<<in>> Cannot be NULL.
parameters<<in>> the filter expression parameters Cannot be NULL.Length of sequence cannot be greater than 100.
Returns
One of the Standard Return Codes
DDS_ReturnCode_t DDS_ContentFilteredTopic_set_expression ( DDS_ContentFilteredTopic self,
const char *  expression,
const struct DDS_StringSeq parameters 
)

Set the filter_expression and expression_parameters.

Changes the filter_expression and expression_parameters associated with the DDS_ContentFilteredTopic.

Parameters
self<<in>> Cannot be NULL.
expression<<in>> the filter expression. Cannot be NULL.
parameters<<in>> the filter expression parameters Cannot be NULL.Length of sequence cannot be greater than 100.
Returns
One of the Standard Return Codes.
DDS_ReturnCode_t DDS_ContentFilteredTopic_append_to_expression_parameter ( DDS_ContentFilteredTopic self,
const DDS_Long  index,
const char *  val 
)

<<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 function 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
self<<in>> Cannot be NULL.
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
DDS_ReturnCode_t DDS_ContentFilteredTopic_remove_from_expression_parameter ( DDS_ContentFilteredTopic self,
const DDS_Long  index,
const char *  val 
)

<<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 function 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
self<<in>> Cannot be NULL.
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
DDS_Topic* DDS_ContentFilteredTopic_get_related_topic ( DDS_ContentFilteredTopic self)

Get the related_topic.

Return the DDS_Topic specified when the DDS_ContentFilteredTopic was created.

Parameters
self<<in>> Cannot be NULL.
Returns
The DDS_Topic assocated with the DDS_ContentFilteredTopic.
DDS_TopicDescription* DDS_MultiTopic_as_topicdescription ( DDS_MultiTopic multiTopic)

Access a DDS_MultiTopic's supertype instance.

Parameters
multiTopic<<in>> Cannot be NULL.
Returns
DDS_MultiTopic's supertype DDS_TopicDescription instance
DDS_MultiTopic* DDS_MultiTopic_narrow ( DDS_TopicDescription self)

Narrow the given DDS_TopicDescription pointer to a DDS_MultiTopic pointer.

Parameters
self<<in>> Cannot be NULL.
Returns
DDS_MultiTopic if this DDS_TopicDescription is a DDS_MultiTopic. Otherwise, return NULL.
const char* DDS_MultiTopic_get_subscription_expression ( DDS_MultiTopic self)

Get the expression for this DDS_MultiTopic.

The expressions syntax is described in the DDS specification. It is specified when the DDS_MultiTopic is created.

Parameters
self<<in>> Cannot be NULL.
Returns
subscription_expression of the DDS_MultiTopic.
DDS_ReturnCode_t DDS_MultiTopic_get_expression_parameters ( DDS_MultiTopic self,
struct DDS_StringSeq parameters 
)

Get the expression parameters.

The expressions syntax is described in the DDS specification.

The parameters is either specified on the last successful call to DDS_MultiTopic_set_expression_parameters, or if DDS_MultiTopic_set_expression_parameters was never called, the parameters specified when the DDS_MultiTopic was created.

Parameters
self<<in>> Cannot be NULL.
parameters<<inout>> Fill in this sequence with the expression parameters. Cannot be NULL.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
DDS_ReturnCode_t DDS_MultiTopic_set_expression_parameters ( DDS_MultiTopic self,
const struct DDS_StringSeq parameters 
)

Set the expression_parameters.

Changes the expression_parameters associated with the DDS_MultiTopic.

Parameters
self<<in>> Cannot be NULL.
parameters<<in>> the filter expression parameters
Returns
One of the Standard Return Codes.

RTI Connext C API Version 5.1.0 Copyright © Mon Feb 3 2014 Real-Time Innovations, Inc