<<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 DDS::Subscriber. More...

#include <managed_subscription.h>

Inheritance diagram for DDS::DataReader:

Public Member Functions
ReadCondition ^	create_readcondition (System::UInt32 sample_states, System::UInt32 view_states, System::UInt32 instance_states)
	Creates a DDS::ReadCondition. More...

ReadCondition ^	create_readcondition_w_params (ReadConditionParams ^ params)
	<<extension>> Creates a DDS::ReadCondition with parameters. More...

QueryCondition ^	create_querycondition (System::UInt32 sample_states, System::UInt32 view_states, System::UInt32 instance_states, System::String^ query_expression, StringSeq^ query_parameters)
	Creates a DDS::QueryCondition. More...

QueryCondition ^	create_querycondition_w_params (QueryConditionParams ^ params)
	<<extension>> Creates a DDS::QueryCondition with parameters. More...

void	delete_readcondition (ReadCondition^% condition)
	Deletes a DDS::ReadCondition or DDS::QueryCondition attached to the DDS::DataReader. More...

void	delete_contained_entities ()
	Deletes all the entities that were created by means of the "create" operations on the DDS::DataReader. More...

void	wait_for_historical_data (Duration_t% max_wait)
	Waits until all "historical" data is received for DDS::DataReader entities that have a non-VOLATILE Durability Qos kind. More...

void	acknowledge_sample (SampleInfo ^ sample_info, AckResponseData_t ^ response_data)
	<<extension>> Acknowledges a single sample explicitly. More...

void	acknowledge_sample (SampleInfo ^ sample_info)
	<<extension>> Acknowledges a single sample explicitly. More...

void	acknowledge_all (AckResponseData_t ^ response_data)
	<<extension>> Acknowledges all previously accessed samples. More...

void	acknowledge_all ()
	<<extension>> Acknowledges all previously accessed samples. More...

void	get_matched_publications (InstanceHandleSeq^ publication_handles)
	Retrieves the list of publications currently "associated" with this DDS::DataReader. More...

void	get_matched_publication_data (PublicationBuiltinTopicData^ publication_data, InstanceHandle_t% publication_handle)
	Retrieves the information on a publication that is currently "associated" with the DDS::DataReader. More...

bool	is_matched_publication_alive (InstanceHandle_t% publication_handle)
	Check if a publication currently matched with a DataReader is alive. More...

void	get_matched_publication_participant_data (ParticipantBuiltinTopicData^ participant_data, InstanceHandle_t% publication_handle)
	<<extension>> Retrieves the information on the discovered DDS::DomainParticipant associated with the publication that is currently matching with the DDS::DataReader. More...

ITopicDescription ^	get_topicdescription ()
	Returns the ITopicDescription associated with the DDS::DataReader. More...

Subscriber ^	get_subscriber ()
	Returns the DDS::Subscriber to which the DDS::DataReader belongs. More...

void	get_sample_rejected_status (SampleRejectedStatus% status)
	Accesses the SAMPLE_REJECTED_STATUS communication status. More...

void	get_liveliness_changed_status (LivelinessChangedStatus% status)
	Accesses the LIVELINESS_CHANGED_STATUS communication status. More...

void	get_requested_deadline_missed_status (RequestedDeadlineMissedStatus% status)
	Accesses the REQUESTED_DEADLINE_MISSED_STATUS communication status. More...

void	get_requested_incompatible_qos_status (RequestedIncompatibleQosStatus^ status)
	Accesses the REQUESTED_INCOMPATIBLE_QOS_STATUS communication status. More...

void	get_sample_lost_status (SampleLostStatus% status)
	Accesses the SAMPLE_LOST_STATUS communication status. More...

void	get_subscription_matched_status (SubscriptionMatchedStatus% status)
	Accesses the SUBSCRIPTION_MATCHED_STATUS communication status. More...

virtual void	get_datareader_cache_status (DataReaderCacheStatus% status)
	<<extension>> Gets the datareader cache status for this reader. More...

virtual void	get_datareader_protocol_status (DataReaderProtocolStatus% status)
	<<extension>> Gets the datareader protocol status for this reader. More...

virtual void	get_matched_publication_datareader_protocol_status (DataReaderProtocolStatus% status, InstanceHandle_t% publication_handle)
	<<extension>> Gets the datareader protocol status for this reader, per matched publication identified by the publication_handle. More...

void	set_qos (DataReaderQos^ qos)
	Sets the reader QoS. More...

void	set_qos_with_profile (System::String^ library_name, System::String^ profile_name)
	<<extension>> Changes the QoS of this reader using the input XML QoS profile. More...

void	get_qos (DataReaderQos^ qos)
	Gets the reader QoS. More...

void	set_listener (DataReaderListener^ l, StatusMask mask)
	Sets the reader listener. More...

DataReaderListener ^	get_listener ()
	Gets the reader listener. More...

TopicQuery ^	create_topic_query (TopicQuerySelection^ selection)
	Creates a DDS::TopicQuery. More...

void	delete_topic_query (TopicQuery^% query)
	Deletes a DDS::TopicQuery. More...

TopicQuery ^	lookup_topic_query (GUID_t% guid)
	Retrieves an existing DDS::TopicQuery. More...

template<typename T >
void	read_untyped (DDS::LoanableSequence< T >^ received_data, DDS::SampleInfoSeq^ info_seq, System::Int32 max_samples, System::UInt32 sample_states, System::UInt32 view_states, System::UInt32 instance_states)
	Reads data samples, if any are available. More...

template<typename T >
void	take_untyped (DDS::LoanableSequence< T >^ received_data, DDS::SampleInfoSeq^ info_seq, System::Int32 max_samples, System::UInt32 sample_states, System::UInt32 view_states, System::UInt32 instance_states)
	Takes data samples, if any are available. More...

template<typename T >
void	read_w_condition_untyped (DDS::LoanableSequence< T >^ received_data, DDS::SampleInfoSeq^ info_seq, System::Int32 max_samples, DDS::ReadCondition^ condition)
	Reads data samples, if any are available. More...

template<typename T >
void	take_w_condition_untyped (DDS::LoanableSequence< T >^ received_data, DDS::SampleInfoSeq^ info_seq, System::Int32 max_samples, DDS::ReadCondition^ condition)
	Takes data samples, if any are available. More...

void	read_next_sample_untyped (System::Object^ received_data, DDS::SampleInfo^ sample_info)
	Reads data samples, if any are available. More...

void	take_next_sample_untyped (System::Object^ received_data, DDS::SampleInfo^ sample_info)
	Takes data samples, if any are available. More...

template<typename T >
void	read_instance_untyped (DDS::LoanableSequence< T >^ received_data, DDS::SampleInfoSeq^ info_seq, System::Int32 max_samples, DDS::InstanceHandle_t% a_handle, System::UInt32 sample_states, System::UInt32 view_states, System::UInt32 instance_states)
	Reads data samples, if any are available. More...

template<typename T >
void	take_instance_untyped (DDS::LoanableSequence< T >^ received_data, DDS::SampleInfoSeq^ info_seq, System::Int32 max_samples, DDS::InstanceHandle_t% a_handle, System::UInt32 sample_states, System::UInt32 view_states, System::UInt32 instance_states)
	Takes data samples, if any are available. More...

template<typename T >
void	read_next_instance_untyped (DDS::LoanableSequence< T >^ received_data, DDS::SampleInfoSeq^ info_seq, System::Int32 max_samples, DDS::InstanceHandle_t% previous_handle, System::UInt32 sample_states, System::UInt32 view_states, System::UInt32 instance_states)
	Reads data samples, if any are available. More...

template<typename T >
void	take_next_instance_untyped (DDS::LoanableSequence< T >^ received_data, DDS::SampleInfoSeq^ info_seq, System::Int32 max_samples, DDS::InstanceHandle_t% previous_handle, System::UInt32 sample_states, System::UInt32 view_states, System::UInt32 instance_states)
	Takes data samples, if any are available. More...

template<typename T >
void	read_next_instance_w_condition_untyped (DDS::LoanableSequence< T >^ received_data, DDS::SampleInfoSeq^ info_seq, System::Int32 max_samples, DDS::InstanceHandle_t% previous_handle, DDS::ReadCondition^ condition)
	Reads data samples, if any are available. More...

template<typename T >
void	take_next_instance_w_condition_untyped (DDS::LoanableSequence< T >^ received_data, DDS::SampleInfoSeq^ info_seq, System::Int32 max_samples, DDS::InstanceHandle_t% previous_handle, DDS::ReadCondition^ condition)
	Takes data samples, if any are available. More...

template<typename T >
void	return_loan_untyped (DDS::LoanableSequence< T >^ received_data, DDS::SampleInfoSeq^ info_seq)
	Returns loaned sample data and meta-data. More...

void	get_key_value_untyped (System::Object^ key_holder, DDS::InstanceHandle_t% handle)
	Fills in the key fields of the given data sample. More...

DDS::InstanceHandle_t	lookup_instance_untyped (System::Object^ key_holder)

virtual void	enable () override
	Enables the DDS::Entity. More...

virtual StatusCondition ^	get_statuscondition () override
	Allows access to the DDS::StatusCondition associated with the DDS::Entity. More...

virtual StatusMask	get_status_changes () override
	Retrieves the list of communication statuses in the DDS::Entity that are triggered. More...

virtual InstanceHandle_t	get_instance_handle () override
	Allows access to the DDS::InstanceHandle_t associated with the DDS::Entity. More...

Properties
static TopicQuerySelection^	TOPIC_QUERY_SELECTION_USE_READER_CONTENT_FILTER `[get]`
	Special value for creating a DDS::TopicQuery that applies the same filter as the DataReader's DDS::ContentFilteredTopic. More...

static TopicQuerySelection^	TOPIC_QUERY_SELECTION_SELECT_ALL `[get]`
	Special value for creating a DDS::TopicQuery that selects all the samples in a DDS::DataWriter cache. 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 DDS::Subscriber.

QoS:: DDS::DataReaderQos

Status:: DATA_AVAILABLE_STATUS;
LIVELINESS_CHANGED_STATUS, DDS::LivelinessChangedStatus;
REQUESTED_DEADLINE_MISSED_STATUS, DDS::RequestedDeadlineMissedStatus;
REQUESTED_INCOMPATIBLE_QOS_STATUS, DDS::RequestedIncompatibleQosStatus;
SAMPLE_LOST_STATUS, DDS::SampleLostStatus;
SAMPLE_REJECTED_STATUS, DDS::SampleRejectedStatus;
SUBSCRIPTION_MATCHED_STATUS, DDS::SubscriptionMatchedStatus;

Listener:: DDS::DataReaderListener

A DDS::DataReader refers to exactly one ITopicDescription (either a DDS::Topic, a DDS::ContentFilteredTopic or a DDS::MultiTopic) 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.

DDS::DataReader 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 DDS::TypedDataReader.

The following operations may be called even if the DDS::DataReader is not enabled. Other operations will fail with the value DDS::Retcode_NotEnabled if called on a disabled DDS::DataReader:

All sample-accessing operations, namely: DDS::TypedDataReader::read, DDS::TypedDataReader::take, DDS::TypedDataReader::read_w_condition, and DDS::TypedDataReader::take_w_condition may fail with the error DDS::Retcode_PreconditionNotMet as described in DDS::Subscriber::begin_access.

See also: Operations Allowed in Listener Callbacks; Access to data samples

Examples:: HelloWorld_subscriber.cpp, and HelloWorldSupport.cpp.

Member Function Documentation

◆ create_readcondition()

ReadCondition ^ DDS::DataReader::create_readcondition	(	System::UInt32	sample_states,
		System::UInt32	view_states,
		System::UInt32	instance_states
	)

Creates a DDS::ReadCondition.

The returned DDS::ReadCondition will be attached and belong to the DDS::DataReader.

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 DDS::ReadCondition created. Returns NULL in case of failure.

◆ create_readcondition_w_params()

ReadCondition ^ DDS::DataReader::create_readcondition_w_params ( ReadConditionParams ^ params )

<<extension>> Creates a DDS::ReadCondition with parameters.

The returned DDS::ReadCondition will be attached and belong to the DDS::DataReader.

Parameters

params <<in>> creation parameters.

Returns: return DDS::ReadCondition created. Returns NULL in case of failure.

◆ create_querycondition()

QueryCondition ^ DDS::DataReader::create_querycondition	(	System::UInt32	sample_states,
		System::UInt32	view_states,
		System::UInt32	instance_states,
		System::String^	query_expression,
		StringSeq^	query_parameters
	)

Creates a DDS::QueryCondition.

The returned DDS::QueryCondition will be attached and belong to the DDS::DataReader.

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. Cannot be NULL.

Returns: return DDS::QueryCondition created. Returns NULL in case of failure.

◆ create_querycondition_w_params()

QueryCondition ^ DDS::DataReader::create_querycondition_w_params ( QueryConditionParams ^ params )

<<extension>> Creates a DDS::QueryCondition with parameters.

The returned DDS::QueryCondition will be attached and belong to the DDS::DataReader.

Parameters

params <<in>> creation parameters.

Returns: return DDS::QueryCondition created. Returns NULL in case of failure.

◆ delete_readcondition()

void DDS::DataReader::delete_readcondition ( ReadCondition^% condition )

Deletes a DDS::ReadCondition or DDS::QueryCondition attached to the DDS::DataReader.

Since DDS::QueryCondition specializes DDS::ReadCondition, it can also be used to delete a DDS::QueryCondition.

Precondition: The DDS::ReadCondition must be attached to the DDS::DataReader, or the operation will fail with the error DDS::Retcode_PreconditionNotMet.

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

One	of the Standard Return Codes, or DDS::Retcode_PreconditionNotMet

◆ delete_contained_entities()

void DDS::DataReader::delete_contained_entities ( )

Deletes all the entities that were created by means of the "create" operations on the DDS::DataReader.

Deletes all contained DDS::ReadCondition, DDS::QueryCondition, and DDS::TopicQuery objects.

The operation will fail with DDS::Retcode_PreconditionNotMet if the any of the contained entities is in a state where it cannot be deleted.

Once DDS::DataReader::delete_contained_entities completes successfully, the application may delete the DDS::DataReader.

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

One	of the Standard Return Codes, or DDS::Retcode_PreconditionNotMet

◆ wait_for_historical_data()

void DDS::DataReader::wait_for_historical_data ( Duration_t% max_wait )

Waits until all "historical" data is received for DDS::DataReader entities that have a non-VOLATILE Durability Qos kind.

This operation is intended only for DDS::DataReader entities that have a non-VOLATILE Durability QoS kind.

As soon as an application enables a non-VOLATILE DDS::DataReader, it will start receiving both "historical" data (i.e., the data that was written prior to the time the DDS::DataReader joined the domain) as well as any new data written by the DDS::DataWriter 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 DDS::DataReader::wait_for_historical_data operations.

DDS::DataReader::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 DDS::DataWriter has been discovered before calling this operation. (One way to do this is by using DDS::DataReader::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. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, DDS::Retcode_Timeout or DDS::Retcode_NotEnabled.

◆ acknowledge_sample() [1/2]

void DDS::DataReader::acknowledge_sample	(	SampleInfo ^	sample_info,
		AckResponseData_t ^	response_data
	)

<<extension>> Acknowledges a single sample explicitly.

Applicable only when DDS::ReliabilityQosPolicy::acknowledgement_mode = DDS::ReliabilityQosPolicyAcknowledgmentModeKind::APPLICATION_EXPLICIT_ACKNOWLEDGEMENT_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 DDS::DataWriter upon acknowledgment (via DDS::DataWriterListener::on_application_acknowledgment)

Exceptions

One	of the Standard Return Codes

◆ acknowledge_sample() [2/2]

void DDS::DataReader::acknowledge_sample ( SampleInfo ^ sample_info )

<<extension>> Acknowledges a single sample explicitly.

Applicable only when DDS::ReliabilityQosPolicy::acknowledgement_mode = DDS::ReliabilityQosPolicyAcknowledgmentModeKind::APPLICATION_EXPLICIT_ACKNOWLEDGEMENT_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

One	of the Standard Return Codes

◆ acknowledge_all() [1/2]

void DDS::DataReader::acknowledge_all ( AckResponseData_t ^ response_data )

<<extension>> Acknowledges all previously accessed samples.

Applicable only when DDS::ReliabilityQosPolicy::acknowledgement_mode = DDS::ReliabilityQosPolicyAcknowledgmentModeKind::APPLICATION_EXPLICIT_ACKNOWLEDGEMENT_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 DDS::DataWriter upon acknowledgment

Exceptions

One	of the Standard Return Codes

◆ acknowledge_all() [2/2]

void DDS::DataReader::acknowledge_all ( )

<<extension>> Acknowledges all previously accessed samples.

Applicable only when DDS::ReliabilityQosPolicy::acknowledgement_mode = DDS::ReliabilityQosPolicyAcknowledgmentModeKind::APPLICATION_EXPLICIT_ACKNOWLEDGEMENT_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

One	of the Standard Return Codes

◆ get_matched_publications()

void DDS::DataReader::get_matched_publications ( InstanceHandleSeq^ publication_handles )

Retrieves the list of publications currently "associated" with this DDS::DataReader.

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 DDS::Topic.
The publication has compatible QoS.
If the applications are using partitions, the publication shares a common partition with this subscription.
The DDS::DomainParticipant has not indicated that the publication's DDS::DomainParticipant should be "ignored" by means of the DDS::DomainParticipant::ignore_publication API.
If the subscription is using a DDS::ContentFilteredTopic 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 DDS::DataWriter entities. These handles match the ones that appear in the instance_handle field of the DDS::SampleInfo when reading the DDS::PublicationBuiltinTopicDataTypeSupport::PUBLICATION_TOPIC_NAME builtin topic.

This API may return the publication handles of publications that are not alive. DDS::DataReader::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_OutOfResources. 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. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, or DDS::Retcode_OutOfResources if the sequence is too small and the system cannot resize it, or DDS::Retcode_NotEnabled

◆ get_matched_publication_data()

void DDS::DataReader::get_matched_publication_data	(	PublicationBuiltinTopicData^	publication_data,
		InstanceHandle_t%	publication_handle
	)

Retrieves the information on a publication that is currently "associated" with the DDS::DataReader.

The publication_handle must correspond to a publication currently associated with the DDS::DataReader. Otherwise, the operation will fail with DDS::Retcode_BadParameter. Use the operation DDS::DataReader::get_matched_publications to find the publications that are currently matched with the DDS::DataReader.

Note: This operation does not retrieve the DDS::PublicationBuiltinTopicData::type_code. This information is available through DDS::DataReaderListener::on_data_available() (if a reader listener is installed on the DDS::PublicationBuiltinTopicDataDataReader).

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 DDS::DataWriter. Must correspond to a publication currently associated with the DDS::DataReader. Cannot be NULL.

Exceptions

One	of the Standard Return Codes or DDS::Retcode_NotEnabled

Referenced by RTI.Connext.Queuing.QueueConsumer< TRep >::CreateSample().

◆ is_matched_publication_alive()

bool DDS::DataReader::is_matched_publication_alive ( InstanceHandle_t% publication_handle )

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_BadParameter.

Parameters

publication_handle <<in>> The DDS::InstanceHandle_t of the matched publication. See DDS::DataReader::get_matched_publications for a description of what is considered a matched publication.

Returns: A boolean indicating whether or not the matched publication is active.

◆ get_matched_publication_participant_data()

void DDS::DataReader::get_matched_publication_participant_data	(	ParticipantBuiltinTopicData^	participant_data,
		InstanceHandle_t%	publication_handle
	)

<<extension>> Retrieves the information on the discovered DDS::DomainParticipant associated with the publication that is currently matching with the DDS::DataReader.

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

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 DDS::DataWriter. Must correspond to a publication currently associated with the DDS::DataReader. Cannot be NULL.

Exceptions

One	of the Standard Return Codes or DDS::Retcode_NotEnabled

◆ get_topicdescription()

ITopicDescription ^ DDS::DataReader::get_topicdescription ( )

Returns the ITopicDescription associated with the DDS::DataReader.

Returns that same ITopicDescription that was used to create the DDS::DataReader.

Returns: ITopicDescription associated with the DDS::DataReader.

◆ get_subscriber()

Subscriber ^ DDS::DataReader::get_subscriber ( )

Returns the DDS::Subscriber to which the DDS::DataReader belongs.

Returns: DDS::Subscriber to which the DDS::DataReader belongs.

◆ get_sample_rejected_status()

void DDS::DataReader::get_sample_rejected_status ( SampleRejectedStatus% status )

Accesses the 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. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ get_liveliness_changed_status()

void DDS::DataReader::get_liveliness_changed_status ( LivelinessChangedStatus% status )

Accesses the 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. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ get_requested_deadline_missed_status()

void DDS::DataReader::get_requested_deadline_missed_status ( RequestedDeadlineMissedStatus% status )

Accesses the 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. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ get_requested_incompatible_qos_status()

void DDS::DataReader::get_requested_incompatible_qos_status ( RequestedIncompatibleQosStatus^ status )

Accesses the 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. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ get_sample_lost_status()

void DDS::DataReader::get_sample_lost_status ( SampleLostStatus% status )

Accesses the 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. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ get_subscription_matched_status()

void DDS::DataReader::get_subscription_matched_status ( SubscriptionMatchedStatus% status )

Accesses the SUBSCRIPTION_MATCHED_STATUS communication status.

Parameters

status <<inout>> DDS::SubscriptionMatchedStatus to be filled in. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ get_datareader_cache_status()

virtual void DDS::DataReader::get_datareader_cache_status ( DataReaderCacheStatus% status )

virtual

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

Parameters

status <<inout>> DDS::DataReaderCacheStatus to be filled in. Cannot be NULL.

Exceptions

One	of the Standard Return Codes or DDS::Retcode_NotEnabled.

◆ get_datareader_protocol_status()

virtual void DDS::DataReader::get_datareader_protocol_status ( DataReaderProtocolStatus% status )

virtual

<<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. Cannot be NULL.

Exceptions

One	of the Standard Return Codes or DDS::Retcode_NotEnabled.

◆ get_matched_publication_datareader_protocol_status()

virtual void DDS::DataReader::get_matched_publication_datareader_protocol_status	(	DataReaderProtocolStatus%	status,
		InstanceHandle_t%	publication_handle
	)

virtual

<<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 DDS::DataWriter. Cannot be NULL.. Must correspond to a publication currently associated with the DDS::DataReader.

Exceptions

One	of the Standard Return Codes or DDS::Retcode_NotEnabled

◆ set_qos()

void DDS::DataReader::set_qos ( DataReaderQos^ qos )

Sets the reader QoS.

Modifies the QoS of the DDS::DataReader.

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 DDS::DataReader is enabled. The special value DDS::Subscriber::DATAREADER_QOS_DEFAULT can be used to indicate that the QoS of the DDS::DataReader should be changed to match the current default DDS::DataReaderQos set in the DDS::Subscriber. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, DDS::Retcode_ImmutablePolicy, or DDS::Retcode_InconsistentPolicy.

See also: DDS::DataReaderQos for rules on consistency among QoS; set_qos (abstract); DDS::DataReader::set_qos; Operations Allowed in Listener Callbacks

◆ set_qos_with_profile()

void DDS::DataReader::set_qos_with_profile	(	System::String^	library_name,
		System::String^	profile_name
	)

<<extension>> Changes the QoS of this reader using the input XML QoS profile.

This operation modifies the QoS of the DDS::DataReader.

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

Exceptions

One	of the Standard Return Codes, DDS::Retcode_ImmutablePolicy, or DDS::Retcode_InconsistentPolicy.

See also: DDS::DataReaderQos for rules on consistency among QoS; DDS::DataReader::set_qos; Operations Allowed in Listener Callbacks

◆ get_qos()

void DDS::DataReader::get_qos ( DataReaderQos^ qos )

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. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

See also: get_qos (abstract)

◆ set_listener()

void DDS::DataReader::set_listener	(	DataReaderListener^	l,
		StatusMask	mask
	)

Sets the reader listener.

Parameters

l	<<in>> DDS::DataReaderListener to set to
mask	<<in>> DDS::StatusMask associated with the DDS::DataReaderListener.

Exceptions

One	of the Standard Return Codes

See also: set_listener (abstract)

◆ get_listener()

DataReaderListener ^ DDS::DataReader::get_listener ( )

Gets the reader listener.

Returns: DDS::DataReaderListener of the DDS::DataReader.

See also: get_listener (abstract)

◆ create_topic_query()

TopicQuery ^ DDS::DataReader::create_topic_query ( TopicQuerySelection^ selection )

Creates a DDS::TopicQuery.

The returned DDS::TopicQuery will have been issued if the DDS::DataReader is enabled. Otherwise, the DDS::TopicQuery will be issued once the DDS::DataReader is enabled

Parameters

selection <<in>> The selection with which to create the DDS::TopicQuery. The special values DDS::DataReader::TOPIC_QUERY_SELECTION_SELECT_ALL and DDS::DataReader::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. Cannot be NULL.

Returns: return Created DDS::TopicQuery. Returns NULL in case of failure.

◆ delete_topic_query()

void DDS::DataReader::delete_topic_query ( TopicQuery^% query )

Deletes a DDS::TopicQuery.

Cancels an active DDS::TopicQuery. 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 DDS::TopicQuery to delete. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ lookup_topic_query()

TopicQuery ^ DDS::DataReader::lookup_topic_query ( GUID_t% guid )

Retrieves an existing DDS::TopicQuery.

Retrieves the DDS::TopicQuery 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 DDS::TopicQuery, use the method DDS::TopicQuery::get_guid.

Parameters

guid	<<in>> The DDS::TopicQuery GUID. Cannot be NULL.

◆ read_untyped()

template<typename T >

void DDS::DataReader::read_untyped	(	DDS::LoanableSequence< T >^	received_data,
		DDS::SampleInfoSeq^	info_seq,
		System::Int32	max_samples,
		System::UInt32	sample_states,
		System::UInt32	view_states,
		System::UInt32	instance_states
	)

Reads data samples, if any are available.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataReader classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataReader::read method instead of this one. See that method for detailed documentation.

See also: DDS::DataReader::take_untyped; DDS::TypedDataReader::read

◆ take_untyped()

template<typename T >

void DDS::DataReader::take_untyped	(	DDS::LoanableSequence< T >^	received_data,
		DDS::SampleInfoSeq^	info_seq,
		System::Int32	max_samples,
		System::UInt32	sample_states,
		System::UInt32	view_states,
		System::UInt32	instance_states
	)

Takes data samples, if any are available.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataReader classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataReader::take method instead of this one. See that method for detailed documentation.

See also: DDS::DataReader::read_untyped; DDS::TypedDataReader::take

◆ read_w_condition_untyped()

template<typename T >

void DDS::DataReader::read_w_condition_untyped	(	DDS::LoanableSequence< T >^	received_data,
		DDS::SampleInfoSeq^	info_seq,
		System::Int32	max_samples,
		DDS::ReadCondition^	condition
	)

Reads data samples, if any are available.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataReader classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataReader::read_w_condition method instead of this one. See that method for detailed documentation.

See also: DDS::DataReader::take_w_condition_untyped; DDS::TypedDataReader::read_w_condition

◆ take_w_condition_untyped()

template<typename T >

void DDS::DataReader::take_w_condition_untyped	(	DDS::LoanableSequence< T >^	received_data,
		DDS::SampleInfoSeq^	info_seq,
		System::Int32	max_samples,
		DDS::ReadCondition^	condition
	)

Takes data samples, if any are available.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataReader classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataReader::take_w_condition method instead of this one. See that method for detailed documentation.

See also: DDS::DataReader::read_w_condition_untyped; DDS::TypedDataReader::take_w_condition

◆ read_next_sample_untyped()

void DDS::DataReader::read_next_sample_untyped	(	System::Object^	received_data,
		DDS::SampleInfo^	sample_info
	)

Reads data samples, if any are available.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataReader classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataReader::read_next_sample method instead of this one. See that method for detailed documentation.

See also: DDS::DataReader::take_next_sample_untyped; DDS::TypedDataReader::read_next_sample

◆ take_next_sample_untyped()

void DDS::DataReader::take_next_sample_untyped	(	System::Object^	received_data,
		DDS::SampleInfo^	sample_info
	)

Takes data samples, if any are available.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataReader classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataReader::take_next_sample method instead of this one. See that method for detailed documentation.

See also: DDS::DataReader::read_next_sample_untyped; DDS::TypedDataReader::take_next_sample

◆ read_instance_untyped()

template<typename T >

void DDS::DataReader::read_instance_untyped	(	DDS::LoanableSequence< T >^	received_data,
		DDS::SampleInfoSeq^	info_seq,
		System::Int32	max_samples,
		DDS::InstanceHandle_t%	a_handle,
		System::UInt32	sample_states,
		System::UInt32	view_states,
		System::UInt32	instance_states
	)

Reads data samples, if any are available.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataReader classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataReader::read_instance method instead of this one. See that method for detailed documentation.

See also: DDS::DataReader::take_instance_untyped; DDS::TypedDataReader::read_instance

◆ take_instance_untyped()

template<typename T >

void DDS::DataReader::take_instance_untyped	(	DDS::LoanableSequence< T >^	received_data,
		DDS::SampleInfoSeq^	info_seq,
		System::Int32	max_samples,
		DDS::InstanceHandle_t%	a_handle,
		System::UInt32	sample_states,
		System::UInt32	view_states,
		System::UInt32	instance_states
	)

Takes data samples, if any are available.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataReader classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataReader::take_instance method instead of this one. See that method for detailed documentation.

See also: DDS::DataReader::read_instance_untyped; DDS::TypedDataReader::take_instance

◆ read_next_instance_untyped()

template<typename T >

void DDS::DataReader::read_next_instance_untyped	(	DDS::LoanableSequence< T >^	received_data,
		DDS::SampleInfoSeq^	info_seq,
		System::Int32	max_samples,
		DDS::InstanceHandle_t%	previous_handle,
		System::UInt32	sample_states,
		System::UInt32	view_states,
		System::UInt32	instance_states
	)

Reads data samples, if any are available.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataReader classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataReader::read_next_instance method instead of this one. See that method for detailed documentation.

See also: DDS::DataReader::take_next_instance_untyped; DDS::TypedDataReader::read_next_instance

◆ take_next_instance_untyped()

template<typename T >

void DDS::DataReader::take_next_instance_untyped	(	DDS::LoanableSequence< T >^	received_data,
		DDS::SampleInfoSeq^	info_seq,
		System::Int32	max_samples,
		DDS::InstanceHandle_t%	previous_handle,
		System::UInt32	sample_states,
		System::UInt32	view_states,
		System::UInt32	instance_states
	)

Takes data samples, if any are available.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataReader classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataReader::take_next_instance method instead of this one. See that method for detailed documentation.

See also: DDS::DataReader::read_next_instance_untyped; DDS::TypedDataReader::take_next_instance

◆ read_next_instance_w_condition_untyped()

template<typename T >

void DDS::DataReader::read_next_instance_w_condition_untyped	(	DDS::LoanableSequence< T >^	received_data,
		DDS::SampleInfoSeq^	info_seq,
		System::Int32	max_samples,
		DDS::InstanceHandle_t%	previous_handle,
		DDS::ReadCondition^	condition
	)

Reads data samples, if any are available.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataReader classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataReader::read_next_instance_w_condition method instead of this one. See that method for detailed documentation.

See also: DDS::DataReader::take_next_instance_w_condition_untyped; DDS::TypedDataReader::read_next_instance_w_condition

◆ take_next_instance_w_condition_untyped()

template<typename T >

void DDS::DataReader::take_next_instance_w_condition_untyped	(	DDS::LoanableSequence< T >^	received_data,
		DDS::SampleInfoSeq^	info_seq,
		System::Int32	max_samples,
		DDS::InstanceHandle_t%	previous_handle,
		DDS::ReadCondition^	condition
	)

Takes data samples, if any are available.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataReader classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataReader::take_next_instance_w_condition method instead of this one. See that method for detailed documentation.

See also: DDS::DataReader::read_next_instance_w_condition_untyped; DDS::TypedDataReader::take_next_instance_w_condition

◆ return_loan_untyped()

template<typename T >

void DDS::DataReader::return_loan_untyped	(	DDS::LoanableSequence< T >^	received_data,
		DDS::SampleInfoSeq^	info_seq
	)

Returns loaned sample data and meta-data.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataReader classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataReader::return_loan method instead of this one. See that method for detailed documentation.

See also: DDS::TypedDataReader::return_loan

Referenced by RTI.Connext.Infrastructure.LoanedSamples< T >::Dispose().

◆ get_key_value_untyped()

void DDS::DataReader::get_key_value_untyped	(	System::Object^	key_holder,
		DDS::InstanceHandle_t%	handle
	)

Fills in the key fields of the given data sample.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataReader classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataReader::get_key_value method instead of this one. See that method for detailed documentation.

See also: DDS::TypedDataReader::get_key_value

◆ lookup_instance_untyped()

DDS::InstanceHandle_t DDS::DataReader::lookup_instance_untyped ( System::Object^ key_holder )

◆ enable()

virtual void DDS::DataReader::enable ( )

overridevirtual

Enables the DDS::Entity.

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 DDS::Entity.

By default, ENTITY_FACTORY is set so that it is not necessary to explicitly call DDS::Entity::enable on newly created entities.

The DDS::Entity::enable operation is idempotent. Calling enable on an already enabled Entity returns OK and has no effect.

If a DDS::Entity has not yet been enabled, the following kinds of operations may be invoked on it:

set or get the QoS policies (including default QoS policies) and listener
DDS::Entity::get_statuscondition
'factory' operations
DDS::Entity::get_status_changes and other get status operations (although the status of a disabled entity never changes)
'lookup' operations

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

It is legal to delete an DDS::Entity 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_PreconditionNotMet.

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 DDS::Publisher will enable all its contained DDS::DataWriter 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

One	of the Standard Return Codes, Standard Return Codes or DDS::Retcode_PreconditionNotMet.

Implements DDS::Entity.

Referenced by RTI.Connext.Queuing.QueueRequester< TReq, TRep >::QueueRequester().

◆ get_statuscondition()

virtual StatusCondition ^ DDS::DataReader::get_statuscondition ( )

overridevirtual

Allows access to the DDS::StatusCondition associated with the DDS::Entity.

The returned condition can then be added to a DDS::WaitSet so that the application can wait for specific status changes that affect the DDS::Entity.

Returns: the status condition associated with this entity.

Implements DDS::Entity.

◆ get_status_changes()

virtual StatusMask DDS::DataReader::get_status_changes ( )

overridevirtual

Retrieves the list of communication statuses in the DDS::Entity 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 DDS::Entity that are triggered.

See also: Status Kinds

Implements DDS::Entity.

◆ get_instance_handle()

virtual InstanceHandle_t DDS::DataReader::get_instance_handle ( )

overridevirtual

Allows access to the DDS::InstanceHandle_t associated with the DDS::Entity.

This operation returns the DDS::InstanceHandle_t that represents the DDS::Entity.

Returns: the instance handle associated with this entity.

Implements DDS::Entity.

Public Member Functions

Properties

Detailed Description

Member Function Documentation

◆ create_readcondition()

◆ create_readcondition_w_params()

◆ create_querycondition()

◆ create_querycondition_w_params()

◆ delete_readcondition()

◆ delete_contained_entities()

◆ wait_for_historical_data()

◆ acknowledge_sample() [1/2]

◆ acknowledge_sample() [2/2]

◆ acknowledge_all() [1/2]

◆ acknowledge_all() [2/2]

◆ get_matched_publications()

◆ get_matched_publication_data()

◆ is_matched_publication_alive()

◆ get_matched_publication_participant_data()

◆ get_topicdescription()

◆ get_subscriber()

◆ get_sample_rejected_status()

◆ get_liveliness_changed_status()

◆ get_requested_deadline_missed_status()

◆ get_requested_incompatible_qos_status()

◆ get_sample_lost_status()

◆ get_subscription_matched_status()

◆ get_datareader_cache_status()

◆ get_datareader_protocol_status()

◆ get_matched_publication_datareader_protocol_status()

◆ set_qos()

◆ set_qos_with_profile()

◆ get_qos()

◆ set_listener()

◆ get_listener()

◆ create_topic_query()

◆ delete_topic_query()

◆ lookup_topic_query()

◆ read_untyped()

◆ take_untyped()

◆ read_w_condition_untyped()

◆ take_w_condition_untyped()

◆ read_next_sample_untyped()

◆ take_next_sample_untyped()

◆ read_instance_untyped()

◆ take_instance_untyped()

◆ read_next_instance_untyped()

◆ take_next_instance_untyped()

◆ read_next_instance_w_condition_untyped()

◆ take_next_instance_w_condition_untyped()

◆ return_loan_untyped()

◆ get_key_value_untyped()

◆ lookup_instance_untyped()

◆ enable()

◆ get_statuscondition()

◆ get_status_changes()

◆ get_instance_handle()