40. DataReaders

To create a DataReader, you need a DomainParticipant, a Topic, and optionally, a Subscriber. You need at least one DataReader for each Topic whose DDS data samples you want to receive.

After you create a DataReader, you will be able to use the operations listed in Table 40.1 DataReader Operations. You are likely to use many of these operations from within your DataReader’s Listener, which is invoked when there are status changes or new DDS data samples. For more details on all operations, see the API reference HTML documentation. The DataReaderListener is described in 40.4 Setting Up DataReaderListeners.

DataReaders are created by using operations on a DomainParticipant or a Subscriber, as described in 39.1 Creating Subscribers Explicitly vs. Implicitly. If you use the DomainParticipant’s operations, the DataReader will belong to an implicit Subscriber that is automatically created by the middleware. If you use a Subscriber’s operations, the DataReader will belong to that Subscriber. So either way, the DataReader belongs to a Subscriber.

Note: Some operations cannot be used within a listener callback, see 15.8.8.1 Restricted Operations in Listener Callbacks.

Table 40.1 DataReader Operations
Purpose	Operation	Description	Reference
Configuring the DataReader	enable	Enables the DataReader.	15.2 Enabling DDS Entities
	equals	Compares two DataReader’s QoS structures for equality.	40.9.2 Comparing QoS Values
	get_qos	Gets the QoS.	40.9 Setting DataReader QosPolicies
	set_qos	Modifies the QoS.
	set_qos_with_profile	Modifies the QoS based on a QoS profile.
	get_listener	Gets the currently installed Listener.	40.4 Setting Up DataReaderListeners
	set_listener	Replaces the Listener.	40.4 Setting Up DataReaderListeners
Accessing DDS Data Samples with “Read” (Use FooData-Reader, see 41.3 Accessing DDS Data Samples with Read or Take)	read	Reads (copies) a collection of DDS data samples from the DataReader.	41.3 Accessing DDS Data Samples with Read or Take
	read_instance	Identical to read, but all DDS samples returned belong to a single instance, which you specify as a parameter.	41.3.4 read_instance and take_instance
	read_instance_w_condition	Identical to read_instance, but all DDS samples returned belong to a single instance and satisfy a specific ReadCondition.	41.3.7 read_instance_w_condition and take_instance_w_condition
	read_next_instance	Similar to read_instance, but the actual instance is not directly specified as a parameter. Instead, the DDS samples will all belong to instance ordered after the one previously read.	41.3.5 read_next_instance and take_next_instance
	read_next_instance_w_ condition	Accesses a collection of DDS data samples of the next instance that match a specific set of ReadConditions, from the DataReader.	41.3.8 read_next_instance_w_condition and take_next_instance_w_condition
	read_next_sample	Reads the next not-previously-accessed data value from the DataReader.	41.3.3 read_next_sample and take_next_sample
	read_w_condition	Accesses a collection of DDS data samples from the DataReader that match specific ReadCondition criteria.	41.3.6 read_w_condition and take_w_condition
Accessing DDS Data Samples with “Take” (Use FooData-Reader, see 41.3 Accessing DDS Data Samples with Read or Take)	take	Like read, but the DDS samples are removed from the DataReader’s receive queue.	41.3 Accessing DDS Data Samples with Read or Take
	take_instance	Identical to take, but all DDS samples returned belong to a single instance, which you specify as a parameter.	41.3.4 read_instance and take_instance
	take_instance_w_condition	Identical to take_instance, but all DDS samples returned belong to a single instance and satisfy a specific ReadCondition.	41.3.7 read_instance_w_condition and take_instance_w_condition
	take_next_instance	Like read_next_instance, but the DDS samples are removed from the DataReader’s receive queue.	41.3.5 read_next_instance and take_next_instance
	take_next_instance		41.3.5 read_next_instance and take_next_instance
	take_next_instance_w_ condition	Accesses (and removes) a collection of DDS data samples of the next instance that match a specific set of ReadConditions, from the DataReader.	41.3.8 read_next_instance_w_condition and take_next_instance_w_condition
	take_next_sample	Like read_next_sample, but the DDS samples are removed from the DataReader’s receive queue.	41.3.3 read_next_sample and take_next_sample
	take_w_condition	Accesses (and removes) a collection of DDS data samples from the DataReader that match specific ReadCondition criteria.	41.3.6 read_w_condition and take_w_condition
Working with DDS Data Samples and FooData-Reader (Use FooData-Reader, see 41.3 Accessing DDS Data Samples with Read or Take)	narrow	A type-safe way to cast a pointer. This takes a DDSDataReader pointer and ‘narrows’ it to a ‘FooDataReader’ where ‘Foo’ is the related data type.	41.1 Using a Type-Specific DataReader (FooDataReader)
	return_loan	Returns buffers loaned in a previous read or take call.	41.2 Loaning and Returning Data and SampleInfo Sequences
	get_key_value	Gets the key for an instance handle.	40.10.5 Getting the Key Value for an Instance
	lookup_instance	Gets the instance handle that corresponds to an instance key.	40.10.4 Looking Up an Instance Handle
Acknowledging DDS Samples	acknowledge_all	Acknowledge all previously accessed DDS samples.	41.4 Acknowledging DDS Samples
Acknowledging DDS Samples	acknowledge_sample	Acknowledge a single DDS sample.	41.4 Acknowledging DDS Samples
Checking Status	get_liveliness_changed_ status	Gets LIVELINESS_CHANGED_STATUS status.	40.7 Statuses for DataReaders
	get_requested_deadline_ missed_status	Gets REQUESTED_DEADLINE_ MISSED_STATUS status.
	get_requested_ incompatible_qos_status	Gets REQUESTED_INCOMPATIBLE_ QOS_STATUS status.
	get_sample_lost_status	Gets SAMPLE_LOST_STATUS status.
	get_sample_rejected_ status	Gets SAMPLE_REJECTED_STATUS status.
	get_subscription_matched_ status	Gets SUBSCRIPTION_MATCHED_STATUS status.
	get_status_changes	Gets a list of statuses that changed since last time the application read the status or the listeners were called.	15.4 Getting Status and Status Changes
	get_datareader_cache_ status	Gets DATA_READER_CACHE_STATUS status.	40.5 Checking DataReader Status and StatusConditions 40.7 Statuses for DataReaders
	get_datareader_protocol_ status	Gets DATA_READER_PROTOCOL_ STATUS status.
	get_matched_publication_ datareader_protocol_ status	Get the protocol status for this DataReader, per matched publication identified by the publication_handle.
Navigating Relationships	get_instance_handle	Returns the DDS_InstanceHandle_t associated with the Entity.	15.3 Getting an Entity’s Instance Handle
	get_matched_publication_ data	Gets information on a publication with a matching Topic and compatible QoS.	40.10.1 Finding Matching Publications
	get_matched_publications	Gets a list of publications that have a matching Topic and compatible QoS. These are the publications currently associated with the DataReader.	40.10.1 Finding Matching Publications
	get_matched_publication_ participant_data	Gets information on a DomainParticipant of a matching publication.	40.10.2 Finding the Matching Publication’s ParticipantBuiltinTopicData
	get_subscriber	Gets the Subscriber that created the DataReader.	40.10.3 Finding a DataReader’s Related Entities
	get_topicdescription	Gets the Topic associated with the DataReader.	40.10.3 Finding a DataReader’s Related Entities
	is_matched_publication_alive	Enables you to query whether the matched DataWriter (using the instance handle returned by get_matched_publications) is alive. get_matched_publications returns all matching DataWriters, including those that are not alive. This operation enables you to see which matching DataWriters are alive.	40.10.1 Finding Matching Publications
Working with Conditions	create_querycondition	Creates a QueryCondition.	15.9.7 ReadConditions and QueryConditions
	create_readcondition	Creates a ReadCondition.
	delete_readcondition	Deletes a ReadCondition/QueryCondition attached to the DataReader.
	delete_contained_entities	Deletes all the ReadConditions/QueryConditions that were created by means of the "create" operations on the DataReader.	40.3.1 Deleting Contained ReadConditions
	get_statuscondition	Gets the StatusCondition associated with the Entity.	15.9.8 StatusConditions
	create_readcondition_w_params	Creates a ReadCondition with parameters.	15.9.7 ReadConditions and QueryConditions
	create_querycondition_w_params	Creates a QueryCondition with parameters.	15.9.7 ReadConditions and QueryConditions
Working with TopicQueries	create_topic_query	Creates a TopicQuery. The returned TopicQuery will haven been issued if the DataReader is enabled. Otherwise, the TopicQuery will be issued once the DataReader is enabled.	60. Topic Queries
	delete_topic_query	Deletes an active 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.
	lookup_topic_query	Retrieves the TopicQuery that corresponds to the input GUID. To get the GUID associated with a TopicQuery, use the TopicQuery's get_guid().
Waiting for Historical Data	wait_for_historical_data	Waits until all "historical" (previously sent) data is received. Only valid for Reliable DataReaders with non-VOLATILE DURABILITY.	40.6 Waiting for Historical Data