RTI Connext Traditional C++ API Version 7.2.0

<<interface>> Allows the application to: (1) declare the data it wishes to receive (i.e. make a subscription) and (2) access the data received by the attached DDSSubscriber. More...

Inheritance diagram for DDSDataReader:
DDSDomainEntity DDSEntity DDSDynamicDataReader DDSDynamicDataReader DDSKeyedOctetsDataReader DDSKeyedStringDataReader DDSOctetsDataReader DDSParticipantBuiltinTopicDataDataReader DDSPublicationBuiltinTopicDataDataReader DDSServiceRequestDataReader DDSStringDataReader DDSSubscriptionBuiltinTopicDataDataReader DDSTopicBuiltinTopicDataDataReader FooDataReader

Public Member Functions

virtual DDSReadConditioncreate_readcondition (DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
 Creates a DDSReadCondition. More...
 
virtual DDSReadConditioncreate_readcondition_w_params (DDS_ReadConditionParams &params)
 <<extension>> Creates a DDSReadCondition with parameters. More...
 
virtual DDSQueryConditioncreate_querycondition (DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states, const char *query_expression, const struct DDS_StringSeq &query_parameters)
 Creates a DDSQueryCondition. More...
 
virtual DDSQueryConditioncreate_querycondition_w_params (DDS_QueryConditionParams &params)
 <<extension>> Creates a DDSQueryCondition with parameters. More...
 
virtual DDS_ReturnCode_t delete_readcondition (DDSReadCondition *condition)
 Deletes a DDSReadCondition or DDSQueryCondition attached to the DDSDataReader. More...
 
virtual DDS_ReturnCode_t delete_contained_entities ()
 Deletes all the entities that were created by means of the "create" operations on the DDSDataReader. More...
 
virtual DDS_ReturnCode_t wait_for_historical_data (const DDS_Duration_t &max_wait)
 Waits until all "historical" data is received for DDSDataReader entities that have a non-VOLATILE Durability Qos kind. More...
 
virtual DDS_ReturnCode_t acknowledge_sample (const DDS_SampleInfo &sample_info)
 <<extension>> Acknowledges a single sample explicitly. More...
 
virtual DDS_ReturnCode_t acknowledge_all ()
 <<extension>> Acknowledges all previously accessed samples. More...
 
virtual DDS_ReturnCode_t acknowledge_sample (const DDS_SampleInfo &sample_info, const DDS_AckResponseData_t &response_data)
 <<extension>> Acknowledges a single sample explicitly. More...
 
virtual DDS_ReturnCode_t acknowledge_all (const DDS_AckResponseData_t &response_data)
 <<extension>> Acknowledges all previously accessed samples. More...
 
virtual DDS_ReturnCode_t get_matched_publications (DDS_InstanceHandleSeq &publication_handles)
 Retrieves the list of publications currently "associated" with this DDSDataReader. More...
 
virtual DDS_ReturnCode_t get_matched_publication_data (DDS_PublicationBuiltinTopicData &publication_data, const DDS_InstanceHandle_t &publication_handle)
 Retrieves the information on a publication that is currently "associated" with the DDSDataReader. More...
 
virtual DDS_ReturnCode_t is_matched_publication_alive (DDS_Boolean &is_alive, const DDS_InstanceHandle_t &publication_handle)
 Check if a publication currently matched with a DataReader is alive. More...
 
virtual DDS_ReturnCode_t get_matched_publication_participant_data (DDS_ParticipantBuiltinTopicData &participant_data, const DDS_InstanceHandle_t &publication_handle)
 <<extension>> Retrieves the information on the discovered DDSDomainParticipant associated with the publication that is currently matching with the DDSDataReader. More...
 
virtual DDSTopicDescriptionget_topicdescription ()
 Returns the DDSTopicDescription associated with the DDSDataReader. More...
 
virtual DDSSubscriberget_subscriber ()
 Returns the DDSSubscriber to which the DDSDataReader belongs. More...
 
virtual DDS_ReturnCode_t get_sample_rejected_status (DDS_SampleRejectedStatus &status)
 Accesses the DDS_SAMPLE_REJECTED_STATUS communication status. More...
 
virtual DDS_ReturnCode_t get_liveliness_changed_status (DDS_LivelinessChangedStatus &status)
 Accesses the DDS_LIVELINESS_CHANGED_STATUS communication status. More...
 
virtual DDS_ReturnCode_t get_requested_deadline_missed_status (DDS_RequestedDeadlineMissedStatus &status)
 Accesses the DDS_REQUESTED_DEADLINE_MISSED_STATUS communication status. More...
 
virtual DDS_ReturnCode_t get_requested_incompatible_qos_status (DDS_RequestedIncompatibleQosStatus &status)
 Accesses the DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS communication status. More...
 
virtual DDS_ReturnCode_t get_sample_lost_status (DDS_SampleLostStatus &status)
 Accesses the DDS_SAMPLE_LOST_STATUS communication status. More...
 
virtual DDS_ReturnCode_t get_subscription_matched_status (DDS_SubscriptionMatchedStatus &status)
 Accesses the DDS_SUBSCRIPTION_MATCHED_STATUS communication status. More...
 
virtual DDS_ReturnCode_t get_datareader_cache_status (DDS_DataReaderCacheStatus &status)
 <<extension>> Gets the datareader cache status for this reader. More...
 
virtual DDS_ReturnCode_t get_datareader_protocol_status (DDS_DataReaderProtocolStatus &status)
 <<extension>> Gets the datareader protocol status for this reader. More...
 
virtual DDS_ReturnCode_t get_matched_publication_datareader_protocol_status (DDS_DataReaderProtocolStatus &status, const DDS_InstanceHandle_t &publication_handle)
 <<extension>> Gets the datareader protocol status for this reader, per matched publication identified by the publication_handle. More...
 
virtual DDS_ReturnCode_t set_qos (const DDS_DataReaderQos &qos)
 Sets the reader QoS. More...
 
virtual DDS_ReturnCode_t get_qos (DDS_DataReaderQos &qos)
 Gets the reader QoS. More...
 
virtual DDS_ReturnCode_t set_qos_with_profile (const char *library_name, const char *profile_name)
 <<extension>> Changes the QoS of this reader using the input XML QoS profile. More...
 
virtual DDS_ReturnCode_t set_property (const char *property_name, const char *value, bool propagate)
 Set the value for a property that applies to a DataReader. More...
 
virtual DDS_ReturnCode_t set_listener (DDSDataReaderListener *l, DDS_StatusMask mask=DDS_STATUS_MASK_ALL)
 Sets the reader listener. More...
 
virtual DDSDataReaderListenerget_listener ()
 Gets the reader listener. More...
 
virtual DDSTopicQuerycreate_topic_query (const DDS_TopicQuerySelection &selection)
 Creates a DDSTopicQuery. More...
 
virtual DDS_ReturnCode_t delete_topic_query (DDSTopicQuery *query)
 Deletes a DDSTopicQuery. More...
 
virtual DDSTopicQuerylookup_topic_query (const DDS_GUID_t &guid)
 Retrieves an existing DDSTopicQuery. More...
 
virtual DDS_ReturnCode_t take_discovery_snapshot ()
 Take a snapshot of the compatible and incompatible remote writers matched by a local reader. More...
 
virtual DDS_ReturnCode_t take_discovery_snapshot (const char *file_name)
 Take a snapshot of the compatible and incompatible remote writers matched by a local reader. More...
 
virtual DDS_ReturnCode_t enable ()
 Enables the DDSEntity. More...
 
virtual DDSStatusConditionget_statuscondition ()
 Allows access to the DDSStatusCondition associated with the DDSEntity. More...
 
virtual DDS_StatusMask get_status_changes ()
 Retrieves the list of communication statuses in the DDSEntity that are triggered. More...
 
virtual DDS_InstanceHandle_t get_instance_handle ()
 Allows access to the DDS_InstanceHandle_t associated with the DDSEntity. More...
 
virtual DDS_ReturnCode_t enable ()=0
 Enables the DDSEntity. More...
 
virtual DDSStatusConditionget_statuscondition ()=0
 Allows access to the DDSStatusCondition associated with the DDSEntity. More...
 
virtual DDS_StatusMask get_status_changes ()=0
 Retrieves the list of communication statuses in the DDSEntity that are triggered. More...
 
virtual DDS_InstanceHandle_t get_instance_handle ()=0
 Allows access to the DDS_InstanceHandle_t associated with the DDSEntity. More...
 

Detailed Description

<<interface>> Allows the application to: (1) declare the data it wishes to receive (i.e. make a subscription) and (2) access the data received by the attached DDSSubscriber.

QoS:
DDS_DataReaderQos
Status:
DDS_DATA_AVAILABLE_STATUS;
DDS_LIVELINESS_CHANGED_STATUS, DDS_LivelinessChangedStatus;
DDS_REQUESTED_DEADLINE_MISSED_STATUS, DDS_RequestedDeadlineMissedStatus;
DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS, DDS_RequestedIncompatibleQosStatus;
DDS_SAMPLE_LOST_STATUS, DDS_SampleLostStatus;
DDS_SAMPLE_REJECTED_STATUS, DDS_SampleRejectedStatus;
DDS_SUBSCRIPTION_MATCHED_STATUS, DDS_SubscriptionMatchedStatus;
Listener:
DDSDataReaderListener

A DDSDataReader refers to exactly one DDSTopicDescription (either a DDSTopic, a DDSContentFilteredTopic or a DDSMultiTopic) that identifies the data to be read.

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:

All sample-accessing operations, namely: FooDataReader::read, FooDataReader::take, FooDataReader::read_w_condition, and FooDataReader::take_w_condition may fail with the error DDS_RETCODE_PRECONDITION_NOT_MET as described in DDSSubscriber::begin_access.

See also
Operations Allowed in Listener Callbacks
Access to data samples
Examples
HelloWorldSupport.cxx, and HelloWorld_subscriber.cxx.

Member Function Documentation

◆ create_readcondition()

virtual DDSReadCondition * DDSDataReader::create_readcondition ( DDS_SampleStateMask  sample_states,
DDS_ViewStateMask  view_states,
DDS_InstanceStateMask  instance_states 
)
inlinevirtual

Creates a DDSReadCondition.

The returned DDSReadCondition will be attached and belong to the DDSDataReader.

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
Returns
return DDSReadCondition created. Returns NULL in case of failure.

◆ create_readcondition_w_params()

virtual DDSReadCondition * DDSDataReader::create_readcondition_w_params ( DDS_ReadConditionParams params)
inlinevirtual

<<extension>> Creates a DDSReadCondition with parameters.

The returned DDSReadCondition will be attached and belong to the DDSDataReader.

Parameters
params<<in>> creation parameters.
Returns
return DDSReadCondition created. Returns NULL in case of failure.

◆ create_querycondition()

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 
)
inlinevirtual

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.

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.
Returns
return DDSQueryCondition created. Returns NULL in case of failure.

◆ create_querycondition_w_params()

virtual DDSQueryCondition * DDSDataReader::create_querycondition_w_params ( DDS_QueryConditionParams params)
inlinevirtual

<<extension>> Creates a DDSQueryCondition with parameters.

The returned DDSQueryCondition will be attached and belong to the DDSDataReader.

Parameters
params<<in>> creation parameters.
Returns
return DDSQueryCondition created. Returns NULL in case of failure.

◆ delete_readcondition()

virtual DDS_ReturnCode_t DDSDataReader::delete_readcondition ( DDSReadCondition condition)
inlinevirtual

Deletes a DDSReadCondition or DDSQueryCondition attached to the DDSDataReader.

Since DDSQueryCondition specializes DDSReadCondition, it can also be used to delete a DDSQueryCondition.

Precondition
The DDSReadCondition must be attached to the DDSDataReader, or the operation will fail with the error DDS_RETCODE_PRECONDITION_NOT_MET.
MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
Parameters
condition<<in>> Condition to be deleted.
Exceptions
Oneof the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET

◆ delete_contained_entities()

virtual DDS_ReturnCode_t DDSDataReader::delete_contained_entities ( )
inlinevirtual

Deletes all the entities that were created by means of the "create" operations on the DDSDataReader.

Deletes all contained DDSReadCondition, DDSQueryCondition, and DDSTopicQuery 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.

MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
Exceptions
Oneof the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET

◆ wait_for_historical_data()

virtual DDS_ReturnCode_t DDSDataReader::wait_for_historical_data ( const DDS_Duration_t max_wait)
inlinevirtual

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.

DDSDataReader::wait_for_historical_data() blocks the calling thread until either all "historical" data is received, or until the duration specified by the max_wait parameter elapses, whichever happens first. It will return immediately if no DataWriters have been discovered at the time the operation is called; therefore it is advisable to make sure at least one DDSDataWriter has been discovered before calling this operation. (One way to do this is by using DDSDataReader::get_subscription_matched_status.)

A successful completion indicates that all the "historical" data was "received"; timing out indicates that max_wait elapsed before all the data was received.

Parameters
max_wait<<in>> Timeout value.
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_TIMEOUT or DDS_RETCODE_NOT_ENABLED.

◆ acknowledge_sample() [1/2]

virtual DDS_ReturnCode_t DDSDataReader::acknowledge_sample ( const DDS_SampleInfo sample_info)
inlinevirtual

<<extension>> Acknowledges a single sample explicitly.

Applicable only when DDS_ReliabilityQosPolicy::acknowledgment_kind = DDS_APPLICATION_EXPLICIT_ACKNOWLEDGMENT_MODE

A call to this method does not necessarily trigger the sending of an AppAck RTPS message from the DataReader to the DataWriter. How and when AppAck messages are sent can be configured using the QoS values DDS_RtpsReliableReaderProtocol_t::samples_per_app_ack and DDS_RtpsReliableReaderProtocol_t::app_ack_period.

Parameters
sample_info<<in>> DDS_SampleInfo identifying the sample being acknowledged.
Exceptions
Oneof the Standard Return Codes

◆ acknowledge_all() [1/2]

virtual DDS_ReturnCode_t DDSDataReader::acknowledge_all ( )
inlinevirtual

<<extension>> Acknowledges all previously accessed samples.

Applicable only when DDS_ReliabilityQosPolicy::acknowledgment_kind = DDS_APPLICATION_EXPLICIT_ACKNOWLEDGMENT_MODE

A call to this method does not necessarily trigger the sending of an AppAck RTPS message from the DataReader to the DataWriter. How and when AppAck messages are sent can be configured using the QoS values DDS_RtpsReliableReaderProtocol_t::samples_per_app_ack and DDS_RtpsReliableReaderProtocol_t::app_ack_period.

Exceptions
Oneof the Standard Return Codes

◆ acknowledge_sample() [2/2]

virtual DDS_ReturnCode_t DDSDataReader::acknowledge_sample ( const DDS_SampleInfo sample_info,
const DDS_AckResponseData_t response_data 
)
inlinevirtual

<<extension>> Acknowledges a single sample explicitly.

Applicable only when DDS_ReliabilityQosPolicy::acknowledgment_kind = DDS_APPLICATION_EXPLICIT_ACKNOWLEDGMENT_MODE

A call to this method does not necessarily trigger the sending of an AppAck RTPS message from the DataReader to the DataWriter. How and when AppAck messages are sent can be configured using the QoS values DDS_RtpsReliableReaderProtocol_t::samples_per_app_ack and DDS_RtpsReliableReaderProtocol_t::app_ack_period.

The maximum length of the response is configured using DDS_DataReaderResourceLimitsQosPolicy::max_app_ack_response_length

Parameters
sample_info<<in>> DDS_SampleInfo identifying the sample being acknowledged.
response_data<<in>> Response data sent to DDSDataWriter upon acknowledgment (via DDSDataWriterListener::on_application_acknowledgment)
Exceptions
Oneof the Standard Return Codes

◆ acknowledge_all() [2/2]

virtual DDS_ReturnCode_t DDSDataReader::acknowledge_all ( const DDS_AckResponseData_t response_data)
inlinevirtual

<<extension>> Acknowledges all previously accessed samples.

Applicable only when DDS_ReliabilityQosPolicy::acknowledgment_kind = DDS_APPLICATION_EXPLICIT_ACKNOWLEDGMENT_MODE

A call to this method does not necessarily trigger the sending of an AppAck RTPS message from the DataReader to the DataWriter. How and when AppAck messages are sent can be configured using the QoS values DDS_RtpsReliableReaderProtocol_t::samples_per_app_ack and DDS_RtpsReliableReaderProtocol_t::app_ack_period.

The maximum length of the response is configured using DDS_DataReaderResourceLimitsQosPolicy::max_app_ack_response_length.

Parameters
response_data<<in>> Response data sent to DDSDataWriter upon acknowledgment
Exceptions
Oneof the Standard Return Codes

◆ get_matched_publications()

virtual DDS_ReturnCode_t DDSDataReader::get_matched_publications ( DDS_InstanceHandleSeq publication_handles)
inlinevirtual

Retrieves the list of publications currently "associated" with this DDSDataReader.

A publication is considered to be matching if all of the following criteria are true:

  • The publication is within the same domain as this subscription.
  • The publication has a matching DDSTopic.
  • The publication has compatible QoS.
  • If the applications are using partitions, the publication shares a common partition with this subscription.
  • The DDSDomainParticipant has not indicated that the publication's DDSDomainParticipant should be "ignored" by means of the DDSDomainParticipant::ignore_publication API.
  • If the subscription is using a DDSContentFilteredTopic and the publication is using the DDS_MultiChannelQosPolicy, there is an intersection between at least one of the associated filters.
  • If the endpoints need to exchange key material to communicate (i.e., they are securing their communications), the reader has completed the key exchange with the writer.

The handles returned in the publication_handles list are the ones that are used by the RTI Connext 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.

This API may return the publication handles of publications that are not alive. DDSDataReader::is_matched_publication_alive can be used to check the liveliness of the remote publication.

Parameters
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 of the matches and the system cannot resize the sequence, this method will fail with DDS_RETCODE_OUT_OF_RESOURCES. The maximum number of matches possible is configured with DDS_DomainParticipantResourceLimitsQosPolicy. You can use a zero-maximum sequence without ownership to quickly check whether there are any matches without allocating any memory.
Exceptions
Oneof the Standard Return Codes, or DDS_RETCODE_OUT_OF_RESOURCES if the sequence is too small and the system cannot resize it, or DDS_RETCODE_NOT_ENABLED

◆ get_matched_publication_data()

virtual DDS_ReturnCode_t DDSDataReader::get_matched_publication_data ( DDS_PublicationBuiltinTopicData publication_data,
const DDS_InstanceHandle_t publication_handle 
)
inlinevirtual

Retrieves the information on a publication that is currently "associated" with the DDSDataReader.

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 DDS_PublicationBuiltinTopicData::type_code. This information is available through DDSDataReaderListener::on_data_available() (if a reader listener is installed on the DDSPublicationBuiltinTopicDataDataReader).

Parameters
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.
Exceptions
Oneof the Standard Return Codes or DDS_RETCODE_NOT_ENABLED

◆ is_matched_publication_alive()

virtual DDS_ReturnCode_t DDSDataReader::is_matched_publication_alive ( DDS_Boolean is_alive,
const DDS_InstanceHandle_t publication_handle 
)
inlinevirtual

Check if a publication currently matched with a DataReader is alive.

This API is used for querying the endpoint liveliness of a matched publication. A matched publication will be marked as not alive if the liveliness that it committed to through its LIVELINESS QoS policy was not respected. Note that if the participant associated with the matched publication loses liveliness, the DDS_InstanceHandle_t will become invalid and this function will fail with DDS_RETCODE_BAD_PARAMETER.

Parameters
publication_handle<<in>> The DDS_InstanceHandle_t of the matched publication. See DDSDataReader::get_matched_publications for a description of what is considered a matched publication.
is_alive<<out>> Indicates whether or not the matched publication is alive.
Exceptions
Oneof the Standard Return Codes

◆ get_matched_publication_participant_data()

virtual DDS_ReturnCode_t DDSDataReader::get_matched_publication_participant_data ( DDS_ParticipantBuiltinTopicData participant_data,
const DDS_InstanceHandle_t publication_handle 
)
inlinevirtual

<<extension>> Retrieves the information on the discovered DDSDomainParticipant associated with the publication that is currently matching with the DDSDataReader.

The publication_handle must correspond to a publication currently associated with the DDSDataReader. Otherwise, the operation will fail with DDS_RETCODE_BAD_PARAMETER. The operation may also fail with DDS_RETCODE_PRECONDITION_NOT_MET if the publication corresponds to the same DDSDomainParticipant that the DataReader belongs to. Use the operation DDSDataReader::get_matched_publications to find the publications that are currently matched with the DDSDataReader.

Parameters
participant_data<<inout>>. The information to be filled in on the associated participant. Cannot be NULL.
publication_handle<<in>>. Handle to a specific publication associated with a DDSDataWriter. Must correspond to a publication currently associated with the DDSDataReader.
Exceptions
Oneof the Standard Return Codes or DDS_RETCODE_NOT_ENABLED

◆ get_topicdescription()

virtual DDSTopicDescription * DDSDataReader::get_topicdescription ( )
inlinevirtual

Returns the DDSTopicDescription associated with the DDSDataReader.

Returns that same DDSTopicDescription that was used to create the DDSDataReader.

Returns
DDSTopicDescription associated with the DDSDataReader.

◆ get_subscriber()

virtual DDSSubscriber * DDSDataReader::get_subscriber ( )
inlinevirtual

Returns the DDSSubscriber to which the DDSDataReader belongs.

Returns
DDSSubscriber to which the DDSDataReader belongs.

◆ get_sample_rejected_status()

virtual DDS_ReturnCode_t DDSDataReader::get_sample_rejected_status ( DDS_SampleRejectedStatus status)
inlinevirtual

Accesses the DDS_SAMPLE_REJECTED_STATUS communication status.

This also resets the status so that it is no longer considered changed.

Parameters
status<<inout>> DDS_SampleRejectedStatus to be filled in.
Exceptions
Oneof the Standard Return Codes

◆ get_liveliness_changed_status()

virtual DDS_ReturnCode_t DDSDataReader::get_liveliness_changed_status ( DDS_LivelinessChangedStatus status)
inlinevirtual

Accesses the DDS_LIVELINESS_CHANGED_STATUS communication status.

This also resets the status so that it is no longer considered changed.

Parameters
status<<inout>> DDS_LivelinessChangedStatus to be filled in.
Exceptions
Oneof the Standard Return Codes

◆ get_requested_deadline_missed_status()

virtual DDS_ReturnCode_t DDSDataReader::get_requested_deadline_missed_status ( DDS_RequestedDeadlineMissedStatus status)
inlinevirtual

Accesses the DDS_REQUESTED_DEADLINE_MISSED_STATUS communication status.

This also resets the status so that it is no longer considered changed.

Parameters
status<<inout>> DDS_RequestedDeadlineMissedStatus to be filled in.
Exceptions
Oneof the Standard Return Codes

◆ get_requested_incompatible_qos_status()

virtual DDS_ReturnCode_t DDSDataReader::get_requested_incompatible_qos_status ( DDS_RequestedIncompatibleQosStatus status)
inlinevirtual

Accesses the DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS communication status.

This also resets the status so that it is no longer considered changed.

Parameters
status<<inout>> DDS_RequestedIncompatibleQosStatus to be filled in.
Exceptions
Oneof the Standard Return Codes

◆ get_sample_lost_status()

virtual DDS_ReturnCode_t DDSDataReader::get_sample_lost_status ( DDS_SampleLostStatus status)
inlinevirtual

Accesses the DDS_SAMPLE_LOST_STATUS communication status.

This also resets the status so that it is no longer considered changed.

Parameters
status<<inout>> DDS_SampleLostStatus to be filled in.
Exceptions
Oneof the Standard Return Codes

◆ get_subscription_matched_status()

virtual DDS_ReturnCode_t DDSDataReader::get_subscription_matched_status ( DDS_SubscriptionMatchedStatus status)
inlinevirtual

Accesses the DDS_SUBSCRIPTION_MATCHED_STATUS communication status.

Parameters
status<<inout>> DDS_SubscriptionMatchedStatus to be filled in.
Exceptions
Oneof the Standard Return Codes

◆ get_datareader_cache_status()

virtual DDS_ReturnCode_t DDSDataReader::get_datareader_cache_status ( DDS_DataReaderCacheStatus status)
inlinevirtual

<<extension>> Gets the datareader cache status for this reader.

Parameters
status<<inout>> DDS_DataReaderCacheStatus to be filled in.
Exceptions
Oneof the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

◆ get_datareader_protocol_status()

virtual DDS_ReturnCode_t DDSDataReader::get_datareader_protocol_status ( DDS_DataReaderProtocolStatus status)
inlinevirtual

<<extension>> Gets the datareader protocol status for this reader.

This also resets the status so that it is no longer considered changed.

Parameters
status<<inout>> DDS_DataReaderProtocolStatus to be filled in.
Exceptions
Oneof the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

◆ get_matched_publication_datareader_protocol_status()

virtual DDS_ReturnCode_t DDSDataReader::get_matched_publication_datareader_protocol_status ( DDS_DataReaderProtocolStatus status,
const DDS_InstanceHandle_t publication_handle 
)
inlinevirtual

<<extension>> Gets the datareader protocol status for this reader, per matched publication identified by the publication_handle.

This also resets the status so that it is no longer considered changed.

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.

Parameters
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.
Exceptions
Oneof the Standard Return Codes or DDS_RETCODE_NOT_ENABLED

◆ set_qos()

virtual DDS_ReturnCode_t DDSDataReader::set_qos ( const DDS_DataReaderQos qos)
inlinevirtual

Sets the reader QoS.

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.

Parameters
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.
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY, or DDS_RETCODE_INCONSISTENT_POLICY.
See also
DDS_DataReaderQos for rules on consistency among QoS
set_qos (abstract)
DDSDataReader::set_qos
Operations Allowed in Listener Callbacks

◆ get_qos()

virtual DDS_ReturnCode_t DDSDataReader::get_qos ( DDS_DataReaderQos qos)
inlinevirtual

Gets the reader QoS.

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

Parameters
qos<<inout>> The DDS_DataReaderQos to be filled up.
Exceptions
Oneof the Standard Return Codes
See also
get_qos (abstract)

◆ set_qos_with_profile()

virtual DDS_ReturnCode_t DDSDataReader::set_qos_with_profile ( const char *  library_name,
const char *  profile_name 
)
inlinevirtual

<<extension>> Changes 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.

Parameters
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).
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY, or DDS_RETCODE_INCONSISTENT_POLICY.
See also
DDS_DataReaderQos for rules on consistency among QoS
DDSDataReader::set_qos
Operations Allowed in Listener Callbacks

◆ set_property()

virtual DDS_ReturnCode_t DDSDataReader::set_property ( const char *  property_name,
const char *  value,
bool  propagate 
)
inlinevirtual

Set the value for a property that applies to a DataReader.

Warning
This method is not implemented in all APIs and it's intended only for testing purposes. You should use DDSDataReader::set_qos instead.
Parameters
property_name<<in>>. Name of the property that you want to set.
value<<in>>. New value for the property.
propagate<<in>>. Indicates if the property will be propagated or not.
Exceptions
Oneof the Standard Return Codes
See also
DDSDomainParticipant::set_property
DDSDataWriter::set_property
DDSDataReader::set_qos

◆ set_listener()

virtual DDS_ReturnCode_t DDSDataReader::set_listener ( DDSDataReaderListener l,
DDS_StatusMask  mask = DDS_STATUS_MASK_ALL 
)
inlinevirtual

Sets the reader listener.

Parameters
l<<in>> DDSDataReaderListener to set to
mask<<in>> DDS_StatusMask associated with the DDSDataReaderListener.
Exceptions
Oneof the Standard Return Codes
See also
set_listener (abstract)

◆ get_listener()

virtual DDSDataReaderListener * DDSDataReader::get_listener ( )
inlinevirtual

Gets the reader listener.

Returns
DDSDataReaderListener of the DDSDataReader.
See also
get_listener (abstract)

◆ create_topic_query()

virtual DDSTopicQuery * DDSDataReader::create_topic_query ( const DDS_TopicQuerySelection selection)
inlinevirtual

Creates a DDSTopicQuery.

The returned DDSTopicQuery will have been issued if the DDSDataReader is enabled. Otherwise, the DDSTopicQuery will be issued once the DDSDataReader is enabled

Parameters
selection<<in>> The selection with which to create the DDSTopicQuery. The special values DDS_TOPIC_QUERY_SELECTION_SELECT_ALL and DDS_TOPIC_QUERY_SELECTION_USE_READER_CONTENT_FILTER can be used. The expression can start with the special condition "@instance_state = ALIVE AND" followed by the rest of the expression. This restricts the selection to samples of alive instances.
Returns
return Created DDSTopicQuery. Returns NULL in case of failure.

◆ delete_topic_query()

virtual DDS_ReturnCode_t DDSDataReader::delete_topic_query ( DDSTopicQuery query)
inlinevirtual

Deletes a DDSTopicQuery.

Cancels an active DDSTopicQuery. After deleting a TopicQuery, new DataWriters won't discover it and existing DataWriters currently publishing cached samples may stop before delivering all of them.

Parameters
query<<in>> The DDSTopicQuery to delete.
Exceptions
Oneof the Standard Return Codes

◆ lookup_topic_query()

virtual DDSTopicQuery * DDSDataReader::lookup_topic_query ( const DDS_GUID_t guid)
inlinevirtual

Retrieves an existing DDSTopicQuery.

Retrieves the DDSTopicQuery that corresponds to the input DDS_GUID_t.

If no TopicQuery is found for the specified GUID or the TopicQuery is marked for deletion, this returns NULL.

To get the DDS_GUID_t associated with a DDSTopicQuery, use the method DDSTopicQuery::get_guid.

Parameters
guid<<in>> The DDSTopicQuery GUID.

◆ take_discovery_snapshot() [1/2]

virtual DDS_ReturnCode_t DDSDataReader::take_discovery_snapshot ( )
inlinevirtual

Take a snapshot of the compatible and incompatible remote writers matched by a local reader.

The snapshot will be printed through the NDDSConfigLogger. A possible output may be the following:

Remote writers that match the local reader domain=0 name="readerTestName"
guid="0x0101542A,0x2C59B595,0xA1693BDF:0x80000004"
topic="FooTopic" type="FooType"
----------------------------------------------------------------------------
Compatible writers:
1. 0x0101D8D1,0x20B83C0D,0x4495246E:0x80000003 name="writer1TestName"
kind="unkeyed user datareader"
unicastLocators="udpv4://192.168.1.170:7411"
liveliness="ALIVE"
Incompatible writers:
1. 0x0101D8D1,0x20B83C0D,0x4495246E:0x80000103 name="writer2TestName"
kind="unkeyed user datareader"
unicastLocators="udpv4://192.168.1.170:7411"
reason="Inconsistent QoS"
----------------------------------------------------------------------------
Exceptions
Oneof the Standard Return Codes.

◆ take_discovery_snapshot() [2/2]

virtual DDS_ReturnCode_t DDSDataReader::take_discovery_snapshot ( const char *  file_name)
inlinevirtual

Take a snapshot of the compatible and incompatible remote writers matched by a local reader.

The snapshot will be printed in the file specified by file_name. A possible output may be the following:

Remote writers that match the local reader domain=0 name="readerTestName"
guid="0x0101542A,0x2C59B595,0xA1693BDF:0x80000004"
topic="FooTopic" type="FooType"
----------------------------------------------------------------------------
Compatible writers:
1. 0x0101D8D1,0x20B83C0D,0x4495246E:0x80000003 name="writer1TestName"
kind="unkeyed user datareader"
unicastLocators="udpv4://192.168.1.170:7411"
liveliness="ALIVE"
Incompatible writers:
1. 0x0101D8D1,0x20B83C0D,0x4495246E:0x80000103 name="writer2TestName"
kind="unkeyed user datareader"
unicastLocators="udpv4://192.168.1.170:7411"
reason="Inconsistent QoS"
----------------------------------------------------------------------------
Parameters
file_name<<in>> Name of the file where snapshot should be printed.
Exceptions
Oneof the Standard Return Codes.

◆ enable()

virtual DDS_ReturnCode_t DDSDataReader::enable ( )
inlinevirtual

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:

Other operations may explicitly state that they may be called on disabled entities; those that do not will return the error DDS_RETCODE_NOT_ENABLED.

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 Entity that is disabled are created disabled, regardless of the setting of the DDS_EntityFactoryQosPolicy.

Calling enable on an Entity whose factory Entity 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 (for example, enabling a DDSPublisher will enable all its contained DDSDataWriter objects)

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.

Exceptions
Oneof the Standard Return Codes, Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET.

Implements DDSEntity.

◆ get_statuscondition()

virtual DDSStatusCondition * DDSDataReader::get_statuscondition ( )
inlinevirtual

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.

Returns
the status condition associated with this entity.

Implements DDSEntity.

◆ get_status_changes()

virtual DDS_StatusMask DDSDataReader::get_status_changes ( )
inlinevirtual

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.

Returns
list of communication statuses in the DDSEntity that are triggered.
See also
Status Kinds

Implements DDSEntity.

◆ get_instance_handle()

virtual DDS_InstanceHandle_t DDSDataReader::get_instance_handle ( )
inlinevirtual

Allows access to the DDS_InstanceHandle_t associated with the DDSEntity.

This operation returns the DDS_InstanceHandle_t that represents the DDSEntity.

Returns
the instance handle associated with this entity.

Implements DDSEntity.