|
RTI Connext DDS Micro C API
Version 4.0.1
|
|
RTI Connext DDS Micro C API
Version 4.0.1
|
DDS_Subscriber entity and associated elements More...
Data Structures | |
| struct | DDS_SubscriberQos |
| <<cert>> QoS policies supported by a DDS_Subscriber entity. More... | |
| struct | DDS_SubscriberListener |
| <<interface>> <<cert>> DDS_Listener for status about a subscriber. More... | |
Macros | |
| #define | DDS_SUBSCRIBERQOS_APPGEN_INITIALIZER |
| <<cert>> Initializer for new QoS instances. | |
| #define | DDS_SubscriberQos_INITIALIZER |
| <<cert>> Initializer for new QoS instances. | |
| #define | DDS_SubscriberListener_INITIALIZER |
| <<eXtension>> <<cert>> Initializer for new DDS_SubscriberListener. | |
Typedefs | |
| typedef struct DDS_SubscriberImpl | DDS_Subscriber |
| <<interface>> A subscriber is the object responsible for actually receiving data from a subscription. | |
| typedef void(* | DDS_SubscriberListener_DataOnReadersCallback )(void *listener_data, DDS_Subscriber *sub) |
| Prototype of a DDS_SubscriberListener data_on_readers function. | |
Variables | |
| struct DDS_DataReaderQos | DDS_DATAREADER_QOS_DEFAULT |
| <<cert>> Special value for creating data reader with default QoS. | |
| struct DDS_DataReaderQos | DDS_DATAREADER_QOS_USE_TOPIC_QOS |
| Special value for creating DDS_DataReader with a combination of the default DDS_DataReaderQos and the DDS_TopicQos. | |
DDS_Subscriber entity and associated elements
| #define DDS_SUBSCRIBERQOS_APPGEN_INITIALIZER |
<<cert>> Initializer for new QoS instances.
New DDS_SubscriberQos 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:
| #define DDS_SubscriberQos_INITIALIZER |
<<cert>> Initializer for new QoS instances.
New DDS_SubscriberQos 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:
| #define DDS_SubscriberListener_INITIALIZER |
<<eXtension>> <<cert>> Initializer for new DDS_SubscriberListener.
All the new instances allocated in the stack should be initialized to this value.No memory is allocated.
| typedef struct DDS_SubscriberImpl DDS_Subscriber |
<<interface>> A subscriber is the object responsible for actually receiving data from a subscription.
A subscriber acts on the behalf of one or several DDS_DataReader objects that are related to it. When it receives data (from the other parts of the system), it builds the list of concerned DDS_DataReader objects and then indicates to the application that data is available through its listener.
The application can access the list of concerned DDS_DataReader objects through the operation get_datareaders() and then access the data available through operations on the DDS_DataReader.
The following operations may be called even if the DDS_Subscriber is not enabled. Other operations will the value DDS_RETCODE_NOT_ENABLED if called on a disabled DDS_Subscriber:
All operations except for the base-class operations enable() and create_datareader() may fail with DDS_RETCODE_NOT_ENABLED.
| typedef void(* DDS_SubscriberListener_DataOnReadersCallback)(void *listener_data, DDS_Subscriber *sub) |
Prototype of a DDS_SubscriberListener data_on_readers function.
| DDS_ReturnCode_t DDS_SubscriberQos_initialize | ( | struct DDS_SubscriberQos * | self | ) |
Initializer for new QoS instances.
New DDS_SubscriberQos instances on the 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.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_SubscriberQos_copy | ( | struct DDS_SubscriberQos * | self, |
| const struct DDS_SubscriberQos * | source | ||
| ) |
Copy the contents of the given QoS into this QoS.
DDS_SubscriberQos 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.
| self | <<in>> Cannot be NULL. |
| source | <<in>> The DDS_PublisherQos to copy from. |
| DDS_ReturnCode_t DDS_SubscriberQos_finalize | ( | struct DDS_SubscriberQos * | self | ) |
Free any dynamic memory allocated by the policies in this DDS_SubscriberQos.
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. |
| DDS_Entity* DDS_Subscriber_as_entity | ( | DDS_Subscriber * | subscriber | ) |
<<cert>> Access a DDS_Subscriber's supertype instance.
| subscriber | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_Subscriber_get_default_datareader_qos | ( | DDS_Subscriber * | self, |
| struct DDS_DataReaderQos * | qos | ||
| ) |
Copies the default DDS_DataReaderQos values into the provided DDS_DataReaderQos instance.
The retreived qos will match the set of values specified on the last successful call to DDS_Subscriber_set_default_datareader_qos, or else, if the call was never made, the default values from is owning DDS_DomainParticipant.
This function may potentially allocate memory depending on the sequences contained in some QoS policies.
qos parameter. | self | <<in>> Cannot be NULL. |
| qos | <<inout>> DDS_DataReaderQos to be filled-up. Cannot be NULL. |
| DDS_ReturnCode_t DDS_Subscriber_set_default_datareader_qos | ( | DDS_Subscriber * | self, |
| const struct DDS_DataReaderQos * | qos | ||
| ) |
Sets the default DDS_DataReaderQos values for this subscriber.
This call causes the default values inherited from the owning DDS_DomainParticipant to be overridden.
This default value will be used for newly created DDS_DataReader if DDS_DATAREADER_QOS_DEFAULT is specified as the qos parameter when DDS_Subscriber_create_datareader is called.
qos parameter. | self | <<in>> Cannot be NULL. |
| qos | <<in>> The default DDS_DataReaderQos to be set to. The special value DDS_DATAREADER_QOS_DEFAULT may be passed as qos to indicate that the default QoS should be reset back to the initial values the factory would have used if DDS_Subscriber_set_default_datareader_qos had never been called. Cannot be NULL. |
| DDS_DataReader* DDS_Subscriber_create_datareader | ( | DDS_Subscriber * | self, |
| DDS_TopicDescription * | topic, | ||
| const struct DDS_DataReaderQos * | qos, | ||
| const struct DDS_DataReaderListener * | listener, | ||
| DDS_StatusMask | mask | ||
| ) |
<<cert>> Creates a DDS_DataReader that will be attached and belong to the DDS_Subscriber.
| self | <<in>> Cannot be NULL. |
| topic | <<in>> The DDS_TopicDescription that the DDS_DataReader will be associated with. Cannot be NULL. |
| qos | <<in>> The qos of the DDS_DataReader. The special value DDS_DATAREADER_QOS_DEFAULT can be used to indicate that the DDS_DataReader should be created with the default DDS_DataReaderQos set in the DDS_Subscriber. If DDS_TopicDescription is of type DDS_Topic, the special value DDS_DATAREADER_QOS_USE_TOPIC_QOS can be used to indicate that the DDS_DataReader should be created with the combination of the default DDS_DataReaderQos set on the DDS_Subscriber and the DDS_TopicQos. Cannot be NULL. |
| listener | <<in>> The listener of the DDS_DataReader. |
| mask | <<in>>. Changes of communication status to be invoked on the listener. |
| DDS_ReturnCode_t DDS_Subscriber_delete_datareader | ( | DDS_Subscriber * | self, |
| DDS_DataReader * | a_datareader | ||
| ) |
Deletes a DDS_DataReader that belongs to the DDS_Subscriber.
| self | <<in>> Cannot be NULL. |
| a_datareader | <<in>> The DDS_DataReader to be deleted. |
| DDS_ReturnCode_t DDS_Subscriber_enable | ( | DDS_Entity * | self | ) |
Enables a DDS_Subscriber instance.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_Subscriber_delete_contained_entities | ( | DDS_Subscriber * | self | ) |
Deletes all the entities that were created by means of the "create" operation on the DDS_Subscriber.
Deletes all contained DDS_DataReader objects. This pattern is applied recursively. In this manner, the operation DDS_Subscriber_delete_contained_entities on the DDS_Subscriber will end up deleting all the entities recursively contained in the DDS_Subscriber, that is also the objects belonging to the contained DDS_DataReader.
The operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET if any of the contained entities is in a state where it cannot be deleted. This will occur, for example, if a contained DDS_DataReader cannot be deleted because the application has called a FooDataReader_read or FooDataReader_take operation and has not called the corresponding FooDataReader_return_loan operation to return the loaned samples.
Once DDS_Subscriber_delete_contained_entities completes successfully, the application may delete the DDS_Subscriber, knowing that it has no contained DDS_DataReader objects.
| self | <<in>> Cannot be NULL. |
| DDS_DataReader* DDS_Subscriber_lookup_datareader | ( | DDS_Subscriber * | self, |
| const char * | topic_name | ||
| ) |
<<cert>> Retrieves an existing DDS_DataReader.
Use this operation on the built-in DDS_Subscriber (Discovery) to access the built-in DDS_DataReader entities for the built-in topics.
The built-in DDS_DataReader is created when this operation is called on a built-in topic for the first time. The built-in DDS_DataReader is deleted automatically when the DDS_DomainParticipant is deleted.
To ensure that builtin DDS_DataReader entities receive all the discovery traffic, it is suggested that you lookup the builtin DDS_DataReader before the DDS_DomainParticipant is enabled. Looking up builtin DDS_DataReader may implicitly register builtin transports due to creation of DDS_DataReader. Therefore, if you are want to modify builtin transport properties, do so before using this operation.
Therefore the suggested sequence when looking up builtin DataReaders is:
| self | <<in>> Cannot be NULL. |
| topic_name | <<in>> Name of the DDS_TopicDescription that the retrieved DDS_DataReader is attached to. Cannot be NULL. |
topic_name. If no such DDS_DataReader exists, this operation returns NULL. The returned DDS_DataReader may be enabled or disabled.
If more than one DDS_DataReader is attached to the DDS_Subscriber, this operation may return any one of them.
| DDS_DataReader* DDS_Subscriber_lookup_datareader_by_name | ( | DDS_Subscriber * | self, |
| const char * | reader_name | ||
| ) |
<<cert>> Retrieves a DDS_DataReader by its entity name within this DDS_Subscriber
This returned DDS_DataReader is either enabled or disabled.
Every DDS_DataReader in the system has an entity name which is configured and stored in the EntityName policy, ENTITY_NAME.
This operation retrieves a DDS_DataReader within the DDS_Subscriber given the entity's name. If there are several DDS_DataReader with the same name within the DDS_Subscriber, this function returns the first matching occurrence.
| self | <<in>> Cannot be NULL. |
| reader_name | <<in>> Entity name of the DDS_DataReader. Cannot be NULL. |
| DDS_DomainParticipant* DDS_Subscriber_get_participant | ( | DDS_Subscriber * | self | ) |
<<cert>> Returns the DDS_DomainParticipant to which the DDS_Subscriber belongs.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_Subscriber_set_qos | ( | DDS_Subscriber * | self, |
| const struct DDS_SubscriberQos * | qos | ||
| ) |
Sets the subscriber QoS.
This operation modifies the QoS of the DDS_Subscriber.
The DDS_SubscriberQos::entity_factory can be changed. The other policies are immutable.
| self | <<in>> Cannot be NULL. |
| qos | <<in>> DDS_SubscriberQos to be set to. Policies must be consistent. Policies cannot be changed after DDS_Subscriber is enabled. The special value DDS_SUBSCRIBER_QOS_DEFAULT can be used to indicate that the QoS of the DDS_Subscriber should be changed to match the current default DDS_SubscriberQos set in the DDS_DomainParticipant. Cannot be NULL. |
| DDS_ReturnCode_t DDS_Subscriber_get_qos | ( | DDS_Subscriber * | self, |
| struct DDS_SubscriberQos * | qos | ||
| ) |
Gets the subscriber QoS.
This function may potentially allocate memory depending on the sequences contained in some QoS policies.
| self | <<in>> Cannot be NULL. |
| qos | <<in>> DDS_SubscriberQos to be filled in. Cannot be NULL. |
| DDS_ReturnCode_t DDS_Subscriber_set_listener | ( | DDS_Subscriber * | self, |
| const struct DDS_SubscriberListener * | listener, | ||
| DDS_StatusMask | mask | ||
| ) |
Sets the subscriber listener.
| self | <<in>> Cannot be NULL. |
| listener | <<in>> DDS_SubscriberListener to set to. |
| mask | <<in>> DDS_StatusMask associated with the DDS_SubscriberListener. The callback function on the listener cannot be NULL if the corresponding status is turned on in the mask. |
|
read |
Get the subscriber listener.
| self | <<in>> Cannot be NULL. |
| struct DDS_DataReaderQos DDS_DATAREADER_QOS_DEFAULT |
<<cert>> Special value for creating data reader with default QoS.
When used in DDS_Subscriber_create_datareader, this special value is used to indicate that the DDS_DataReader should be created with the default DDS_DataReader QoS.
| struct DDS_DataReaderQos DDS_DATAREADER_QOS_USE_TOPIC_QOS |
Special value for creating DDS_DataReader with a combination of the default DDS_DataReaderQos and the DDS_TopicQos.
The use of this value is equivalent to the application obtaining the default DDS_DataReaderQos and the DDS_TopicQos (by means of the operation DDS_Topic_get_qos) and then combining these two QoS so that any policy that is set on the DDS_TopicQos "overrides" the corresponding policy on the default QoS. The resulting QoS is then applied to the creation of the DDS_DataReader.
This value should only be used in DDS_Subscriber_create_datareader.
RTI Connext DDS Micro C API Version 4.0.1
Copyright © Mon Jun 3 2024
Real-Time Innovations, Inc