|
RTI Connext C API
Version 5.1.0
|
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. | |
DDS_Topic entity and associated elements
| #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:
| #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:
| #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.
| #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.
| 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.
| typedef struct DDS_TopicWrapperI DDS_Topic |
<<interface>> The most basic description of the data to be published and subscribed.
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:
| typedef void(* DDS_TopicListener_InconsistentTopicCallback)(void *listener_data, DDS_Topic *topic, const struct DDS_InconsistentTopicStatus *status) |
| 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.
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. 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.
| 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. |
| 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.
| 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. |
| 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.
| 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.
| 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. |
| cookie | DDS_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.
| 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.
| 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.
| 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. |
|
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
| 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. |
| 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.
| 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.
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. 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:
view_state of the DDS_MultiTopic instance is DDS_NEW_VIEW_STATE if at least one of the constituting instances has view_state = DDS_NEW_VIEW_STATE. Otherwise, it will be DDS_NOT_NEW_VIEW_STATE. instance_state of the DDS_MultiTopic instance is DDS_ALIVE_INSTANCE_STATE if the instance_state of all the constituting DDS_Topic instances is DDS_ALIVE_INSTANCE_STATE. It is DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE if at least one of the constituting DDS_Topic instances is DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE. Otherwise, it is DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE. Queries and Filters Syntax describes the syntax of subscription_expression and expression_parameters.
| 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:
| self | <<in>> Cannot be NULL. |
| 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.
| 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.
| self | <<in>> Cannot be NULL. |
| DDS_Boolean DDS_TopicQos_equals | ( | const struct DDS_TopicQos * | self, |
| const struct DDS_TopicQos * | other | ||
| ) |
Compares two DDS_TopicQos for equality.
| self | <<in>> This TopicQos. |
| other | <<in>> The other TopicQos to be compared with this TopicQos. |
| 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:
| self | <<in>> Cannot be NULL. |
| 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.
| 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.
| self | <<in>> Cannot be NULL. |
| 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.
| self | <<in>> Cannot be NULL. |
| const char* DDS_TopicDescription_get_name | ( | DDS_TopicDescription * | self | ) |
Get the name used to create this DDS_TopicDescription .
| self | <<in>> Cannot be NULL. |
| DDS_DomainParticipant* DDS_TopicDescription_get_participant | ( | DDS_TopicDescription * | self | ) |
Get the DDS_DomainParticipant to which the DDS_TopicDescription belongs.
| self | <<in>> Cannot be NULL. |
| DDS_Entity* DDS_Topic_as_entity | ( | DDS_Topic * | topic | ) |
Access a DDS_Topic's DDS_Entity supertype instance.
| DDS_TopicDescription* DDS_Topic_as_topicdescription | ( | DDS_Topic * | topic | ) |
Access a DDS_Topic's DDS_TopicDescription supertype instance.
| DDS_Topic* DDS_Topic_narrow | ( | DDS_TopicDescription * | self | ) |
Narrow the given DDS_TopicDescription pointer to a DDS_Topic pointer.
| DDS_Topic* DDS_Topic_narrow_from_entity | ( | DDS_Entity * | self | ) |
Narrow the given DDS_Entity pointer to a DDS_Topic pointer.
| self | <<in>> Cannot be 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
| 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.
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.
| self | <<in>> Cannot be NULL. |
| 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.
| 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). |
| 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.
| DDS_ReturnCode_t DDS_Topic_set_listener | ( | DDS_Topic * | self, |
| const struct DDS_TopicListener * | l, | ||
| DDS_StatusMask | mask | ||
| ) |
Set the topic listener.
| 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. |
|
read |
| 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.
| DDS_TopicDescription* DDS_ContentFilteredTopic_as_topicdescription | ( | DDS_ContentFilteredTopic * | contentFilteredTopic | ) |
Access a DDS_ContentFilteredTopic's supertype instance.
| contentFilteredTopic | <<in>> Cannot be NULL. |
| DDS_ContentFilteredTopic* DDS_ContentFilteredTopic_narrow | ( | DDS_TopicDescription * | self | ) |
Narrow the given DDS_TopicDescription pointer to a DDS_ContentFilteredTopic pointer.
| self | <<in>> Cannot be 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.
| self | <<in>> Cannot be NULL. |
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.
| 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. |
| 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.
| self | <<in>> Cannot be NULL. |
| parameters | <<in>> the filter expression parameters Cannot be NULL.Length of sequence cannot be greater than 100. |
| 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.
| 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. |
| 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'
| 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. |
| 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'
| 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. |
| 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.
| self | <<in>> Cannot be NULL. |
| DDS_TopicDescription* DDS_MultiTopic_as_topicdescription | ( | DDS_MultiTopic * | multiTopic | ) |
Access a DDS_MultiTopic's supertype instance.
| multiTopic | <<in>> Cannot be NULL. |
| DDS_MultiTopic* DDS_MultiTopic_narrow | ( | DDS_TopicDescription * | self | ) |
Narrow the given DDS_TopicDescription pointer to a DDS_MultiTopic pointer.
| self | <<in>> Cannot be 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.
| self | <<in>> Cannot be NULL. |
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.
| 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. |
| 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.
RTI Connext C API Version 5.1.0
Copyright © Mon Feb 3 2014
Real-Time Innovations, Inc