The subscription has a unique resulting type. The data-reader may give access to several instances of the resulting type, which can be distinguished from each other by their key
.
DDSDataReader is an abstract class. It must be specialised for each particular application data-type (see USER_DATA). The additional methods or functions that must be defined in the auto-generated class for a hypothetical application type Foo
are specified in the generic type FooDataReader.
The following operations may be called even if the DDSDataReader is not enabled. Other operations will fail with the value DDS_RETCODE_NOT_ENABLED if called on a disabled DDSDataReader:
virtual DDSReadCondition* DDSDataReader::create_readcondition | ( | DDS_SampleStateMask | sample_states, | |
DDS_ViewStateMask | view_states, | |||
DDS_InstanceStateMask | instance_states | |||
) | [inline, virtual] |
Creates a DDSReadCondition.
The returned DDSReadCondition will be attached and belong to the DDSDataReader.
sample_states | <<in>> sample state of the data samples that are of interest | |
view_states | <<in>> view state of the data samples that are of interest | |
instance_states | <<in>> instance state of the data samples that are of interest |
virtual DDSQueryCondition* DDSDataReader::create_querycondition | ( | DDS_SampleStateMask | sample_states, | |
DDS_ViewStateMask | view_states, | |||
DDS_InstanceStateMask | instance_states, | |||
const char * | query_expression, | |||
const struct DDS_StringSeq & | query_parameters | |||
) | [inline, virtual] |
Creates a DDSQueryCondition.
The returned DDSQueryCondition will be attached and belong to the DDSDataReader.
Queries and Filters Syntax describes the syntax of query_expression
and query_parameters
.
sample_states | <<in>> sample state of the data samples that are of interest | |
view_states | <<in>> view state of the data samples that are of interest | |
instance_states | <<in>> instance state of the data samples that are of interest | |
query_expression | <<in>> Expression for the query. Cannot be NULL. | |
query_parameters | <<in>> Parameters for the query expression. |
virtual DDS_ReturnCode_t DDSDataReader::delete_readcondition | ( | DDSReadCondition * | condition | ) | [inline, virtual] |
Deletes a DDSReadCondition or DDSQueryCondition attached to the DDSDataReader.
Since DDSQueryCondition specializes DDSReadCondition, it can also be used to delete a DDSQueryCondition.
condition | <<in>> Condition to be deleted. |
virtual DDS_ReturnCode_t DDSDataReader::delete_contained_entities | ( | ) | [inline, virtual] |
Deletes all the entities that were created by means of the "create" operations on the DDSDataReader.
Deletes all contained DDSReadCondition and DDSQueryCondition objects.
The operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET if the any of the contained entities is in a state where it cannot be deleted.
Once DDSDataReader::delete_contained_entities completes successfully, the application may delete the DDSDataReader, knowing that it has no contained DDSReadCondition and DDSQueryCondition objects.
virtual DDS_ReturnCode_t DDSDataReader::wait_for_historical_data | ( | const DDS_Duration_t & | max_wait | ) | [inline, virtual] |
Waits until all "historical" data is received for DDSDataReader entities that have a non-VOLATILE Durability Qos kind.
This operation is intended only for DDSDataReader entities that have a non-VOLATILE Durability QoS kind.
As soon as an application enables a non-VOLATILE DDSDataReader, it will start receiving both "historical" data (i.e., the data that was written prior to the time the DDSDataReader joined the domain) as well as any new data written by the DDSDataWriter entities. There are situations where the application logic may require the application to wait until all "historical" data is received. This is the purpose of the DDSDataReader::wait_for_historical_data operations.
The operation DDSDataReader::wait_for_historical_data blocks the calling thread until either all "historical" data is received, or else duration specified by the max_wait parameter clapses, whichever happens first. A successful completion indicates that all the "historical" data was "received"; timing out indicates that max_wait elapsed before all the data was received.
max_wait | <<in>> Timeout value. |
virtual DDS_ReturnCode_t DDSDataReader::get_matched_publications | ( | DDS_InstanceHandleSeq & | publication_handles | ) | [inline, virtual] |
Retrieve the list of publications currently "associated" with this DDSDataReader.
Matching publications are those in the same domain that have a matching DDSTopic, compatible QoS common partition that the DDSDomainParticipant has not indicated should be "ignored" by means of the DDSDomainParticipant::ignore_publication operation.
The handles returned in the publication_handles'
list are the ones that are used by the DDS implementation to locally identify the corresponding matched DDSDataWriter entities. These handles match the ones that appear in the instance_handle
field of the DDS_SampleInfo when reading the DDS_PUBLICATION_TOPIC_NAME builtin topic
publication_handles | <<inout>>. The sequence will be grown if the sequence has ownership and the system has the corresponding resources. Use a sequence without ownership to avoid dynamic memory allocation. If the sequence is too small to store all the matches and the system can not resize the sequence, this method will fail with DDS_RETCODE_OUT_OF_RESOURCES. |
virtual DDS_ReturnCode_t DDSDataReader::get_matched_publication_data | ( | DDS_PublicationBuiltinTopicData & | publication_data, | |
const DDS_InstanceHandle_t & | publication_handle | |||
) | [inline, virtual] |
This operation retrieves the information on a publication that is currently "associated" with the DDSDataReader.
Publication with a matching DDSTopic, compatible QoS and common partition that the application has not indicated should be "ignored" by means of the DDSDomainParticipant::ignore_publication operation.
The publication_handle
must correspond to a publication currently associated with the DDSDataReader. Otherwise, the operation will fail with DDS_RETCODE_BAD_PARAMETER. Use the operation DDSDataReader::get_matched_publications to find the publications that are currently matched with the DDSDataReader.
Note: This operation does not retrieve the following information in DDS_PublicationBuiltinTopicData:
The above information is available through DDSDataReaderListener::on_data_available() (if a reader listener is installed on the DDSPublicationBuiltinTopicDataDataReader).
publication_data | <<inout>>. The information to be filled in on the associated publication. Cannot be NULL. | |
publication_handle | <<in>>. Handle to a specific publication associated with the DDSDataWriter. . Must correspond to a publication currently associated with the DDSDataReader. |
virtual DDSTopicDescription* DDSDataReader::get_topicdescription | ( | ) | [inline, virtual] |
Returns the DDSTopicDescription associated with the DDSDataReader.
Returns that same DDSTopicDescription that was used to create the DDSDataReader.
virtual DDSSubscriber* DDSDataReader::get_subscriber | ( | ) | [inline, virtual] |
Returns the DDSSubscriber to which the DDSDataReader belongs.
virtual DDS_ReturnCode_t DDSDataReader::get_sample_rejected_status | ( | DDS_SampleRejectedStatus & | status | ) | [inline, virtual] |
Accesses the DDS_SAMPLE_REJECTED_STATUS communication status.
status | <<inout>> DDS_SampleRejectedStatus to be filled in. |
virtual DDS_ReturnCode_t DDSDataReader::get_liveliness_changed_status | ( | DDS_LivelinessChangedStatus & | status | ) | [inline, virtual] |
Accesses the DDS_LIVELINESS_CHANGED_STATUS communication status.
status | <<inout>> DDS_LivelinessChangedStatus to be filled in. |
virtual DDS_ReturnCode_t DDSDataReader::get_requested_deadline_missed_status | ( | DDS_RequestedDeadlineMissedStatus & | status | ) | [inline, virtual] |
Accesses the DDS_REQUESTED_DEADLINE_MISSED_STATUS communication status.
status | <<inout>> DDS_RequestedDeadlineMissedStatus to be filled in. |
virtual DDS_ReturnCode_t DDSDataReader::get_requested_incompatible_qos_status | ( | DDS_RequestedIncompatibleQosStatus & | status | ) | [inline, virtual] |
Accesses the DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS communication status.
status | <<inout>> DDS_RequestedIncompatibleQosStatus to be filled in. |
virtual DDS_ReturnCode_t DDSDataReader::get_sample_lost_status | ( | DDS_SampleLostStatus & | status | ) | [inline, virtual] |
Accesses the DDS_SAMPLE_LOST_STATUS communication status.
status | <<inout>> DDS_SampleLostStatus to be filled in. |
virtual DDS_ReturnCode_t DDSDataReader::get_subscription_matched_status | ( | DDS_SubscriptionMatchedStatus & | status | ) | [inline, virtual] |
Accesses the DDS_SUBSCRIPTION_MATCHED_STATUS communication status.
status | <<inout>> DDS_SubscriptionMatchedStatus to be filled in. |
virtual DDS_ReturnCode_t DDSDataReader::get_datareader_cache_status | ( | DDS_DataReaderCacheStatus & | status | ) | [inline, virtual] |
<<eXtension>> Get the datareader cache status for this reader.
status | <<inout>> DDS_DataReaderCacheStatus to be filled in. |
virtual DDS_ReturnCode_t DDSDataReader::get_datareader_protocol_status | ( | DDS_DataReaderProtocolStatus & | status | ) | [inline, virtual] |
<<eXtension>> Get the datareader protocol status for this reader.
status | <<inout>> DDS_DataReaderProtocolStatus to be filled in. |
virtual DDS_ReturnCode_t DDSDataReader::get_matched_publication_datareader_protocol_status | ( | DDS_DataReaderProtocolStatus & | status, | |
const DDS_InstanceHandle_t & | publication_handle | |||
) | [inline, virtual] |
<<eXtension>> Get the datareader protocol status for this reader, per matched publication identified by the publication_handle.
Note: Status for a remote entity is only kept while the entity is alive. Once a remote entity is no longer alive, its status is deleted.
status | <<inout>>. The information to be filled in on the associated publication. Cannot be NULL. | |
publication_handle | <<in>>. Handle to a specific publication associated with the DDSDataWriter. . Must correspond to a publication currently associated with the DDSDataReader. |
virtual DDS_ReturnCode_t DDSDataReader::set_qos | ( | const DDS_DataReaderQos & | qos | ) | [inline, virtual] |
Sets the reader QoS.
This operation modifies the QoS of the DDSDataReader.
The DDS_DataReaderQos::user_data, DDS_DataReaderQos::deadline, DDS_DataReaderQos::latency_budget, DDS_DataReaderQos::time_based_filter, DDS_DataReaderQos::reader_data_lifecycle can be changed. The other policies are immutable.
qos | <<in>> The DDS_DataReaderQos to be set to. Policies must be consistent. Immutable policies cannot be changed after DDSDataReader is enabled. The special value DDS_DATAREADER_QOS_DEFAULT can be used to indicate that the QoS of the DDSDataReader should be changed to match the current default DDS_DataReaderQos set in the DDSSubscriber. |
virtual DDS_ReturnCode_t DDSDataReader::get_qos | ( | DDS_DataReaderQos & | qos | ) | [inline, virtual] |
Gets the reader QoS.
This method may potentially allocate memory depending on the sequences contained in some QoS policies.
qos | <<inout>> The DDS_DataReaderQos to be filled up. |
virtual DDS_ReturnCode_t DDSDataReader::set_qos_with_profile | ( | const char * | library_name, | |
const char * | profile_name | |||
) | [inline, virtual] |
<<eXtension>> Change the QoS of this reader using the input XML QoS profile.
This operation modifies the QoS of the DDSDataReader.
The DDS_DataReaderQos::user_data, DDS_DataReaderQos::deadline, DDS_DataReaderQos::latency_budget, DDS_DataReaderQos::time_based_filter, DDS_DataReaderQos::reader_data_lifecycle can be changed. The other policies are immutable.
library_name | <<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSSubscriber::set_default_library). | |
profile_name | <<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSSubscriber::set_default_profile). |
virtual DDS_ReturnCode_t DDSDataReader::set_listener | ( | DDSDataReaderListener * | l, | |
DDS_StatusMask | mask = DDS_STATUS_MASK_ALL | |||
) | [inline, virtual] |
Sets the reader listener.
l | <<in>> DDSDataReaderListener to set to | |
mask | <<in>> DDS_StatusMask associated with the DDSDataReaderListener. |
virtual DDSDataReaderListener* DDSDataReader::get_listener | ( | ) | [inline, virtual] |
Get the reader listener.
virtual DDS_ReturnCode_t DDSDataReader::enable | ( | ) | [inline, virtual] |
Enables the DDSEntity.
This operation enables the Entity. Entity objects can be created either enabled or disabled. This is controlled by the value of the ENTITY_FACTORY QoS policy on the corresponding factory for the DDSEntity.
By default, ENTITY_FACTORY is set so that it is not necessary to explicitly call DDSEntity::enable on newly created entities.
The DDSEntity::enable operation is idempotent. Calling enable on an already enabled Entity returns OK and has no effect.
If a DDSEntity has not yet been enabled, the following kinds of operations may be invoked on it:
It is legal to delete an DDSEntity that has not been enabled by calling the proper operation on its factory.
Entities created from a factory that is disabled are created disabled, regardless of the setting of the DDS_EntityFactoryQosPolicy.
Calling enable on an Entity whose factory is not enabled will fail and return DDS_RETCODE_PRECONDITION_NOT_MET.
If DDS_EntityFactoryQosPolicy::autoenable_created_entities is TRUE, the enable operation on a factory will automatically enable all entities created from that factory.
Listeners associated with an entity are not called until the entity is enabled.
Conditions associated with a disabled entity are "inactive," that is, they have a trigger_value
== FALSE.
Implements DDSEntity.
virtual DDSStatusCondition* DDSDataReader::get_statuscondition | ( | ) | [inline, virtual] |
Allows access to the DDSStatusCondition associated with the DDSEntity.
The returned condition can then be added to a DDSWaitSet so that the application can wait for specific status changes that affect the DDSEntity.
Implements DDSEntity.
virtual DDS_StatusMask DDSDataReader::get_status_changes | ( | ) | [inline, virtual] |
Retrieves the list of communication statuses in the DDSEntity that are triggered.
That is, the list of statuses whose value has changed since the last time the application read the status using the get_*_status() method.
When the entity is first created or if the entity is not enabled, all communication statuses are in the "untriggered" state so the list returned by the get_status_changes operation will be empty.
The list of statuses returned by the get_status_changes operation refers to the status that are triggered on the Entity itself and does not include statuses that apply to contained entities.
Implements DDSEntity.
virtual DDS_InstanceHandle_t DDSDataReader::get_instance_handle | ( | ) | [inline, virtual] |
Allows access to the DDS_InstanceHandle_t associated with the DDSEntity.
This operation returns the DDS_InstanceHandle_t that represents the DDSEntity.
Implements DDSEntity.