|
RTI Connext C API
Version 6.1.2
|
DDS_Subscriber entity and associated elements More...
Data Structures | |
| struct | DDS_SubscriberSeq |
Declares IDL sequence < DDS_Subscriber > . More... | |
| struct | DDS_SubscriberQos |
| QoS policies supported by a DDS_Subscriber entity. More... | |
| struct | DDS_SubscriberListener |
| <<interface>> DDS_Listener for status about a subscriber. More... | |
Macros | |
| #define | DDS_SubscriberQos_INITIALIZER |
| Initializer for new QoS instances. More... | |
| #define | DDS_SubscriberListener_INITIALIZER |
| <<extension>> Initializer for new DDS_SubscriberListener. More... | |
Typedefs | |
| typedef struct DDS_SubscriberImpl | DDS_Subscriber |
| <<interface>> A subscriber is the object responsible for actually receiving data from a subscription. More... | |
| typedef void(* | DDS_SubscriberListener_DataOnReadersCallback) (void *listener_data, DDS_Subscriber *sub) |
| Prototype of a DDS_SubscriberListener data_on_readers function. More... | |
Variables | |
| const struct DDS_DataReaderQos * | DDS_DATAREADER_QOS_PRINT_ALL |
| Special value which can be supplied to DDS_DataReaderQos_to_string_w_params indicating that all of the QoS should be printed. More... | |
| const struct DDS_DataReaderQos | DDS_DATAREADER_QOS_DEFAULT |
| Special value for creating data reader with default QoS. More... | |
| const 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. More... | |
DDS_Subscriber entity and associated elements
| #define DDS_SubscriberQos_INITIALIZER |
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:
Note that the above assignment is not a substitute for calling DDS_DomainParticipant_get_default_subscriber_qos or DDS_Subscriber_get_qos; one of those should be called subsequently to setting the QoS of a new or existing entity. DDS_SubscriberQos_finalize should be called to free the contained QoS policies that use dynamic memory:
| #define DDS_SubscriberListener_INITIALIZER |
<<extension>> 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 or by enabling related conditions.
The application can access the list of concerned DDS_DataReader objects through the operation DDS_Subscriber_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 DDS_Subscriber_set_qos, DDS_Subscriber_set_qos_with_profile,DDS_Subscriber_get_qos, DDS_Subscriber_set_listener, DDS_Subscriber_get_listener, DDS_Entity_enable and DDS_Subscriber_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_Boolean DDS_SubscriberQos_equals | ( | const struct DDS_SubscriberQos * | self, |
| const struct DDS_SubscriberQos * | other | ||
| ) |
Compares two DDS_SubscriberQos for equality.
| self | <<in>> This SubscriberQos. |
| other | <<in>> The other SubscriberQos to be compared with this SubscriberQos. |
| DDS_ReturnCode_t DDS_SubscriberQos_print | ( | const struct DDS_SubscriberQos * | self | ) |
Prints this DDS_SubscriberQos to stdout.
Only the differences between this DDS_SubscriberQos and the documented default are printed. If you wish to print everything regardless, see DDS_SubscriberQos_to_string_w_params. The output is formatted according to the default values for DDS_QosPrintFormat.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_SubscriberQos_to_string | ( | const struct DDS_SubscriberQos * | self, |
| char * | string, | ||
| DDS_UnsignedLong * | string_size | ||
| ) |
Obtains a string representation of this DDS_SubscriberQos.
Only the differences between this DDS_SubscriberQos and the documented default are printed to the string. If you wish to print everything regardless, see DDS_SubscriberQos_to_string_w_params. The output is formatted according to the default values for DDS_QosPrintFormat.
If the supplied buffer is NULL, the required length of the string is returned via the string_size parameter.
If the supplied buffer is not NULL, the string representation of the DDS_SubscriberQos is written to the buffer.
| self | <<in>> Cannot be NULL. |
| string | <<out>> The char buffer that will be used to store the string representation of this DDS_SubscriberQos. If NULL, this function will return the required length of this buffer through the string_size parameter. |
| string_size | <<inout>> Cannot be NULL. The size of the supplied buffer. If the supplied buffer is NULL, or if the supplied buffer is not large enough, this value will be updated with the required length of the buffer. |
| DDS_ReturnCode_t DDS_SubscriberQos_to_string_w_params | ( | const struct DDS_SubscriberQos * | self, |
| char * | string, | ||
| DDS_UnsignedLong * | string_size, | ||
| const struct DDS_SubscriberQos * | base, | ||
| const struct DDS_QosPrintFormat * | format | ||
| ) |
Obtains a string representation of this DDS_SubscriberQos.
Only the differences between this DDS_SubscriberQos and the DDS_SubscriberQos supplied as the base are printed to the string.
It is possible to supply the sentinel value DDS_SUBSCRIBER_QOS_PRINT_ALL as the base to print everything within the QoS.
If the supplied buffer is NULL, the required length of the string is returned via the string_size parameter.
If the supplied buffer is not NULL, the string representation of the DDS_SubscriberQos is written to the buffer.
| self | <<in>> Cannot be NULL. |
| string | <<out>> The char buffer that will be used to store the string representation of this DDS_SubscriberQos. If NULL, this function will return the required length of this buffer through the string_size parameter. |
| string_size | <<inout>> Cannot be NULL. The size of the supplied buffer. If the supplied buffer is NULL, or if the supplied buffer is not large enough, this value will be updated with the required length of the buffer. |
| base | <<in>> The DDS_SubscriberQos to be used as the base QoS profile. Only the differences with respect to this base profile will be included in the output string. |
| format | <<in>> The DDS_QosPrintFormat to be used to format the output string. |
| DDS_ReturnCode_t DDS_SubscriberQos_initialize | ( | struct DDS_SubscriberQos * | self | ) |
Initializer for new QoS instances.
New DDS_SubscriberQos 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_Subscriber_get_qos or DDS_DomainParticipant_get_default_subscriber_qos; one of those should be called subsequently to setting the QoS of any new or existing entity. DDS_SubscriberQos_finalize should be called to free the contained QoS policies that use dynamic memory:
| self | <<in>> Cannot be NULL. |
| 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_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_Entity* DDS_Subscriber_as_entity | ( | DDS_Subscriber * | subscriber | ) |
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 retrieved qos will match the set of values specified on the last successful call to DDS_Subscriber_set_default_datareader_qos, or DDS_Subscriber_set_default_datareader_qos_with_profile, 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.
| 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 used if DDS_Subscriber_set_default_datareader_qos had never been called. Cannot be NULL. |
| DDS_ReturnCode_t DDS_Subscriber_set_default_datareader_qos_with_profile | ( | DDS_Subscriber * | self, |
| const char * | library_name, | ||
| const char * | profile_name | ||
| ) |
<<extension>> Set the default DDS_DataReaderQos values for this subscriber based on the input XML QoS profile.
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. |
| library_name | <<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS_Subscriber_set_default_library). |
| profile_name | <<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_Subscriber_set_default_profile). |
If the input profile cannot be found the function fails with DDS_RETCODE_ERROR.
| 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 | ||
| ) |
Creates a DDS_DataReader that will be attached and belong to the DDS_Subscriber.
For each application-defined type Foo, there is an implied, auto-generated class FooDataReader (an incarnation of FooDataReader) that extends DDS_DataReader and contains the operations to read data of type Foo.
Note that a common application pattern to construct the QoS for the DDS_DataReader is to:
When a DDS_DataReader is created, only those transports already registered are available to the DDS_DataReader. See Built-in Transport Plugins for details on when a builtin transport is registered.
qos parameter, it is not safe to create the datareader while another thread may be simultaneously calling DDS_Subscriber_set_default_datareader_qos. qos is DDS_DATAREADER_QOS_USE_TOPIC_QOS, topic cannot be DDS_MultiTopic, or else this function will return NULL. | 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 or DDS_ContentFilteredTopic, 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 (in the case of a DDS_ContentFilteredTopic, the DDS_TopicQos of the related DDS_Topic). if DDS_DATAREADER_QOS_USE_TOPIC_QOS is used, topic cannot be a DDS_MultiTopic. Cannot be NULL. |
| listener | <<in>> The listener of the DDS_DataReader. |
| mask | <<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask. |
| DDS_DataReader* DDS_Subscriber_create_datareader_with_profile | ( | DDS_Subscriber * | self, |
| DDS_TopicDescription * | topic, | ||
| const char * | library_name, | ||
| const char * | profile_name, | ||
| const struct DDS_DataReaderListener * | listener, | ||
| DDS_StatusMask | mask | ||
| ) |
<<extension>> Creates a DDS_DataReader object using the DDS_DataReaderQos associated with the input XML QoS profile.
The DDS_DataReader will be attached and belong to the DDS_Subscriber.
For each application-defined type Foo, there is an implied, auto-generated class FooDataReader (an incarnation of FooDataReader) that extends DDS_DataReader and contains the operations to read data of type Foo.
When a DDS_DataReader is created, only those transports already registered are available to the DDS_DataReader. See Built-in Transport Plugins for details on when a builtin transport is registered.
| self | <<in>> Cannot be NULL. |
| topic | <<in>> The DDS_TopicDescription that the DDS_DataReader will be associated with. 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_Subscriber_set_default_library). |
| profile_name | <<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_Subscriber_set_default_profile). |
| listener | <<in>> The listener of the DDS_DataReader. |
| mask | <<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask. |
| 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_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, including the DDS_QueryCondition, DDS_ReadCondition, and DDS_TopicQuery 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.
| self | <<in>> Cannot be NULL. |
| DDS_DataReader* DDS_Subscriber_lookup_datareader | ( | DDS_Subscriber * | self, |
| const char * | topic_name | ||
| ) |
Retrieves an existing DDS_DataReader.
Use this operation on the built-in DDS_Subscriber (Built-in Topics) 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 (see Built-in Transport Plugins for details on when a builtin transport is registered). 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_ReturnCode_t DDS_Subscriber_begin_access | ( | DDS_Subscriber * | self | ) |
Indicates that the application is about to access the data samples in any of the DDS_DataReader objects attached to the DDS_Subscriber.
If the DDS_PresentationQosPolicy::access_scope of the DDS_Subscriber is DDS_GROUP_PRESENTATION_QOS or DDS_HIGHEST_OFFERED_PRESENTATION_QOS and DDS_PresentationQosPolicy::ordered_access is DDS_BOOLEAN_TRUE, the application is required to use this operation to access the samples in order across DataWriters of the same group (DDS_Publisher with DDS_PresentationQosPolicy::access_scope set to DDS_GROUP_PRESENTATION_QOS).
In the above case, this operation must be called prior to calling any of the sample-accessing operations, DDS_Subscriber_get_datareaders on the DDS_Subscriber, and FooDataReader_read, FooDataReader_take, FooDataReader_read_w_condition, and FooDataReader_take_w_condition on any DDS_DataReader.
Once the application has finished accessing the data samples, it must call DDS_Subscriber_end_access
The application is not required to call DDS_Subscriber_begin_access / DDS_Subscriber_end_access to access the samples in order if the PRESENTATION policy in the DDS_Publisher has DDS_PresentationQosPolicy::access_scope set to something other than DDS_GROUP_PRESENTATION_QOS. In this case, calling DDS_Subscriber_begin_access / DDS_Subscriber_end_access is not considered an error and has no effect.
Calls to DDS_Subscriber_begin_access / DDS_Subscriber_end_access may be nested and must be balanced.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_Subscriber_end_access | ( | DDS_Subscriber * | self | ) |
Indicates that the application has finished accessing the data samples in DDS_DataReader objects managed by the DDS_Subscriber.
This operation must be used to close a corresponding begin_access().
This call must close a previous call to DDS_Subscriber_begin_access(), otherwise the operation will fail with the error DDS_RETCODE_PRECONDITION_NOT_MET.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_Subscriber_get_datareaders | ( | DDS_Subscriber * | self, |
| struct DDS_DataReaderSeq * | readers, | ||
| DDS_SampleStateMask | sample_states, | ||
| DDS_ViewStateMask | view_states, | ||
| DDS_InstanceStateMask | instance_states | ||
| ) |
Allows the application to access the DDS_DataReader objects that contain samples with the specified sample_states, view_states and instance_states.
If the application is outside a begin_access()/end_access() block, or if the DDS_PresentationQosPolicy::access_scope of the DDS_Subscriber is DDS_INSTANCE_PRESENTATION_QOS or DDS_TOPIC_PRESENTATION_QOS, or if the DDS_PresentationQosPolicy::ordered_access of the DDS_Subscriber is DDS_BOOLEAN_FALSE, the returned collection is a 'set' containing each DDS_DataReader at most once, in no specified order.
If the application is within a begin_access()/end_access() block, and the PRESENTATION policy of the DDS_Subscriber is DDS_GROUP_PRESENTATION_QOS or DDS_HIGHEST_OFFERED_PRESENTATION_QOS, and DDS_PresentationQosPolicy::ordered_access in the DDS_Subscriber is DDS_BOOLEAN_TRUE, the returned collection is a 'list' of DataReaders where a DataReader may appear more than one time.
To retrieve the samples in the order they were published across DataWriters of the same group (DDS_Publisher configured with DDS_GROUP_PRESENTATION_QOS), the application should read()/take() from each DataReader in the same order as it appears in the output sequence. The application will move to the next DataReader when the read()/take() operation fails with DDS_RETCODE_NO_DATA.
| self | <<in>> Cannot be NULL. |
| readers | <<inout>> a DDS_DataReaderSeq object where the set or list of readers will be returned. Cannot be NULL. |
| sample_states | <<in>> the returned DataReader must contain samples that have one of these sample_states. |
| view_states | <<in>> the returned DataReader must contain samples that have one of these view_states. |
| instance_states | <<in>> the returned DataReader must contain samples that have one of these instance_states. |
| DDS_ReturnCode_t DDS_Subscriber_get_all_datareaders | ( | DDS_Subscriber * | self, |
| struct DDS_DataReaderSeq * | readers | ||
| ) |
Retrieve all the DataReaders created from this Subscriber.
| DDS_ReturnCode_t DDS_Subscriber_notify_datareaders | ( | DDS_Subscriber * | self | ) |
Invokes the operation DDS_DataReaderListener::on_data_available() on the DDS_DataReaderListener objects attached to contained DDS_DataReader entities with DDS_DATA_AVAILABLE_STATUS that is considered changed as described in Changes in read communication status.
This operation is typically invoked from the DDS_SubscriberListener::on_data_on_readers operation in the DDS_SubscriberListener. That way the DDS_SubscriberListener can delegate to the DDS_DataReaderListener objects the handling of the data.
The operation will notify the data readers that have a sample_state of DDS_NOT_READ_SAMPLE_STATE, view_state of DDS_ANY_SAMPLE_STATE and instance_state of DDS_ANY_INSTANCE_STATE.
| self | <<in>> Cannot be NULL. |
| DDS_DomainParticipant* DDS_Subscriber_get_participant | ( | DDS_Subscriber * | self | ) |
Returns the DDS_DomainParticipant to which the DDS_Subscriber belongs.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_Subscriber_copy_from_topic_qos | ( | DDS_Subscriber * | self, |
| struct DDS_DataReaderQos * | datareader_qos, | ||
| const struct DDS_TopicQos * | topic_qos | ||
| ) |
Copies the policies in the DDS_TopicQos to the corresponding policies in the DDS_DataReaderQos.
Copies the policies in the DDS_TopicQos to the corresponding policies in the DDS_DataReaderQos (replacing values in the DDS_DataReaderQos, if present).
This is a "convenience" operation most useful in combination with the operations DDS_Subscriber_get_default_datareader_qos and DDS_Topic_get_qos. The operation DDS_Subscriber_copy_from_topic_qos can be used to merge the DDS_DataReader default QoS policies with the corresponding ones on the DDS_Topic. The resulting QoS can then be used to create a new DDS_DataReader, or set its QoS.
This operation does not check the resulting DDS_DataReaderQos for consistency. This is because the 'merged' DDS_DataReaderQos may not be the final one, as the application can still modify some policies prior to applying the policies to the DDS_DataReader.
| self | <<in>> Cannot be NULL. |
| datareader_qos | <<inout>> DDS_DataReaderQos to be filled-up. Cannot be NULL. |
| topic_qos | <<in>> DDS_TopicQos to be merged with DDS_DataReaderQos. 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::group_data, DDS_SubscriberQos::partition and 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. Immutable 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_set_qos_with_profile | ( | DDS_Subscriber * | self, |
| const char * | library_name, | ||
| const char * | profile_name | ||
| ) |
<<extension>> Change the QoS of this subscriber using the input XML QoS profile.
This operation modifies the QoS of the DDS_Subscriber.
The DDS_SubscriberQos::group_data, DDS_SubscriberQos::partition and DDS_SubscriberQos::entity_factory 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_Subscriber_set_default_library). |
| profile_name | <<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_Subscriber_set_default_profile). |
| 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_default_profile | ( | DDS_Subscriber * | self, |
| const char * | library_name, | ||
| const char * | profile_name | ||
| ) |
<<extension>> Sets the default XML profile for a DDS_Subscriber.
This function specifies the profile that will be used as the default the next time a default Subscriber profile is needed during a call to one of this Subscriber's operations. When calling a DDS_Subscriber function that requires a profile_name parameter, you can use NULL to refer to the default profile. (This same information applies to setting a default library.)
If the default profile is not set, the DDS_Subscriber inherits the default from the DDS_DomainParticipant (see DDS_DomainParticipant_set_default_profile).
This function does not set the default QoS for DDS_DataReader objects created by this DDS_Subscriber; for this functionality, use DDS_Subscriber_set_default_datareader_qos_with_profile (you may pass in NULL after having called set_default_profile()).
This function does not set the default QoS for newly created Subscribers; for this functionality, use DDS_DomainParticipant_set_default_subscriber_qos_with_profile.
| self | <<in>> Cannot be NULL. |
| library_name | <<in>> The library name containing the profile. |
| profile_name | <<in>> The profile name. If profile_name is null any previous default is unset. |
| const char* DDS_Subscriber_get_default_profile | ( | DDS_Subscriber * | self | ) |
<<extension>> Gets the default XML profile associated with a DDS_Subscriber.
| self | <<in>> Cannot be NULL. |
| const char* DDS_Subscriber_get_default_profile_library | ( | DDS_Subscriber * | self | ) |
<<extension>> Gets the library where the default XML QoS profile is contained for a DDS_Subscriber.
The default profile library is automatically set when DDS_Subscriber_set_default_profile is called.
This library can be different than the DDS_Subscriber default library (see DDS_Subscriber_get_default_library).
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_Subscriber_set_default_library | ( | DDS_Subscriber * | self, |
| const char * | library_name | ||
| ) |
<<extension>> Sets the default XML library for a DDS_Subscriber.
This function specifies the library that will be used as the default the next time a default library is needed during a call to one of this Subscriber's operations.
Any API requiring a library_name as a parameter can use null to refer to the default library.
If the default library is not set, the DDS_Subscriber inherits the default from the DDS_DomainParticipant (see DDS_DomainParticipant_set_default_library).
| self | <<in>> Cannot be NULL. |
| library_name | <<in>> Library name. If library_name is null any previous default is unset. |
| const char* DDS_Subscriber_get_default_library | ( | DDS_Subscriber * | self | ) |
<<extension>> Gets the default XML library associated with a DDS_Subscriber.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_Subscriber_set_listener | ( | DDS_Subscriber * | self, |
| const struct DDS_SubscriberListener * | l, | ||
| DDS_StatusMask | mask | ||
| ) |
Sets the subscriber listener.
| self | <<in>> Cannot be NULL. |
| l | <<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. |
| struct DDS_SubscriberListener DDS_Subscriber_get_listener | ( | DDS_Subscriber * | self | ) |
Get the subscriber listener.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_Subscriber_get_listenerX | ( | DDS_Subscriber * | self, |
| struct DDS_SubscriberListener * | listener | ||
| ) |
<<extension>> Get the subscriber listener.
An alternative form of get_listener that fills in an existing listener structure rather than returning one on the stack.
| self | <<in>> Cannot be NULL. |
| listener | <<inout>> DDS_SubscriberListener structure to be filled up. Cannot be NULL. |
| DDS_DataReader* DDS_Subscriber_lookup_datareader_by_name | ( | DDS_Subscriber * | self, |
| const char * | datareader_name | ||
| ) |
<<extension>> Retrieves a DDS_DataReader contained within the DDS_Subscriber the DDS_DataReader entity name.
Every DDS_DataReader in the system has an entity name which is configured and stored in the <<extension>> EntityName policy, ENTITY_NAME.
This operation retrieves the DDS_DataReader within the DDS_Subscriber whose name matches the one specified. If there are several DDS_DataReader with the same name within the DDS_Subscriber, the operation returns the first matching occurrence.
| self | <<in>> Cannot be NULL. |
| datareader_name | <<in>> Entity name of the DDS_DataReader. |
| const struct DDS_DataReaderQos* DDS_DATAREADER_QOS_PRINT_ALL |
Special value which can be supplied to DDS_DataReaderQos_to_string_w_params indicating that all of the QoS should be printed.
The DDS_DataReaderQos_to_string_w_params API accepts a base QoS profile as one of its arguments. The resultant string only contains the differences with respect to the supplied base QoS profile. Supplying the DDS_DATAREADER_QOS_PRINT_ALL sentinel value as the base QoS will result in all of the QoS being printed.
Note that there are some QoS policies and fields which are not intended for public use. Even when DDS_DATAREADER_QOS_PRINT_ALL is supplied as the base, these will not be printed unless they differ from the documented default. If you want to see their values, you must use the print_private field within the DDS_QosPrintFormat structure.
This value should only be used as the base parameter to the DDS_DataReaderQos_to_string_w_params API.
| const struct DDS_DataReaderQos DDS_DATAREADER_QOS_DEFAULT |
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 by means of the operation get_default_datareader_qos and using the resulting QoS to create the DDS_DataReader.
When used in DDS_Subscriber_set_default_datareader_qos, this special value is used to indicate that the default QoS should be reset back to the initial value that would be used if the DDS_Subscriber_set_default_datareader_qos operation had never been called.
When used in DDS_DataReader_set_qos, this special value is used to indicate that the QoS of the DDS_DataReader should be changed to match the current default QoS set in the DDS_Subscriber that the DDS_DataReader belongs to.
| const 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 using the operation DDS_Subscriber_copy_from_topic_qos whereby 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.