<<interface>> <<generic>> User data type-specific data reader. More...

Inheritance diagram for FooDataReader:

Public Member Functions
virtual DDS_ReturnCode_t	read (FooSeq &received_data, DDS_SampleInfoSeq &info_seq, DDS_Long max_samples, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)=0
	Access a collection of data samples from the DDSDataReader. More...

virtual DDS_ReturnCode_t	take (FooSeq &received_data, DDS_SampleInfoSeq &info_seq, DDS_Long max_samples, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)=0
	Access a collection of data-samples from the DDSDataReader. More...

virtual DDS_ReturnCode_t	read_w_condition (FooSeq &received_data, DDS_SampleInfoSeq &info_seq, DDS_Long max_samples, DDSReadCondition *condition)=0
	Accesses via FooDataReader::read the samples that match the criteria specified in the DDSReadCondition. More...

virtual DDS_ReturnCode_t	take_w_condition (FooSeq &received_data, DDS_SampleInfoSeq &info_seq, DDS_Long max_samples, DDSReadCondition *condition)=0
	Analogous to FooDataReader::read_w_condition except it accesses samples via the FooDataReader::take operation. More...

virtual DDS_ReturnCode_t	read_next_sample (Foo &received_data, DDS_SampleInfo &sample_info)=0
	Copies the next not-previously-accessed data value from the DDSDataReader. More...

virtual DDS_ReturnCode_t	take_next_sample (Foo &received_data, DDS_SampleInfo &sample_info)=0
	Copies the next not-previously-accessed data value from the DDSDataReader. More...

virtual DDS_ReturnCode_t	read_instance (FooSeq &received_data, DDS_SampleInfoSeq &info_seq, DDS_Long max_samples, const DDS_InstanceHandle_t &a_handle, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)=0
	Access a collection of data samples from the DDSDataReader. More...

virtual DDS_ReturnCode_t	take_instance (FooSeq &received_data, DDS_SampleInfoSeq &info_seq, DDS_Long max_samples, const DDS_InstanceHandle_t &a_handle, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)=0
	Access a collection of data samples from the DDSDataReader. More...

virtual DDS_ReturnCode_t	read_instance_w_condition (FooSeq &received_data, DDS_SampleInfoSeq &info_seq, DDS_Long max_samples, const DDS_InstanceHandle_t &previous_handle, DDSReadCondition *condition)=0
	<<extension>> Accesses via FooDataReader::read_instance the samples that match the criteria specified in the DDSReadCondition. More...

virtual DDS_ReturnCode_t	take_instance_w_condition (FooSeq &received_data, DDS_SampleInfoSeq &info_seq, DDS_Long max_samples, const DDS_InstanceHandle_t &previous_handle, DDSReadCondition *condition)=0
	<<extension>> Accesses via FooDataReader::take_instance the samples that match the criteria specified in the DDSReadCondition. More...

virtual DDS_ReturnCode_t	read_next_instance (FooSeq &received_data, DDS_SampleInfoSeq &info_seq, DDS_Long max_samples, const DDS_InstanceHandle_t &previous_handle, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)=0
	Access a collection of data samples from the DDSDataReader. More...

virtual DDS_ReturnCode_t	take_next_instance (FooSeq &received_data, DDS_SampleInfoSeq &info_seq, DDS_Long max_samples, const DDS_InstanceHandle_t &previous_handle, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)=0
	Access a collection of data samples from the DDSDataReader. More...

virtual DDS_ReturnCode_t	read_next_instance_w_condition (FooSeq &received_data, DDS_SampleInfoSeq &info_seq, DDS_Long max_samples, const DDS_InstanceHandle_t &previous_handle, DDSReadCondition *condition)=0
	Accesses via FooDataReader::read_next_instance the samples that match the criteria specified in the DDSReadCondition. More...

virtual DDS_ReturnCode_t	take_next_instance_w_condition (FooSeq &received_data, DDS_SampleInfoSeq &info_seq, DDS_Long max_samples, const DDS_InstanceHandle_t &previous_handle, DDSReadCondition *condition)=0
	Accesses via FooDataReader::take_next_instance the samples that match the criteria specified in the DDSReadCondition. More...

virtual DDS_ReturnCode_t	return_loan (FooSeq &received_data, DDS_SampleInfoSeq &info_seq)=0
	Indicates to the DDSDataReader that the application is done accessing the collection of `received_data` and `info_seq` obtained by some earlier invocation of read or take on the DDSDataReader. More...

virtual DDS_ReturnCode_t	get_key_value (Foo &key_holder, const DDS_InstanceHandle_t handle)=0
	Retrieve the instance `key` that corresponds to an instance `handle`. More...

virtual DDS_InstanceHandle_t	lookup_instance (const Foo &key_holder)=0
	Retrieves the instance `handle` that corresponds to an instance `key_holder`. More...

virtual DDS_ReturnCode_t	is_data_consistent (DDS_Boolean &is_data_consistent, const TData sample, const DDS_SampleInfo sample_info)=0
	When using Zero Copy transfer over shared memory, checks if the sample has been overwritten by the DataWriter. More...

Public Member Functions inherited from DDSDataReader
virtual DDSReadCondition *	create_readcondition (DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
	Creates a DDSReadCondition. More...

virtual DDSReadCondition *	create_readcondition_w_params (DDS_ReadConditionParams &params)
	<<extension>> Creates a DDSReadCondition with parameters. More...

virtual DDSQueryCondition *	create_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 DDSQueryCondition *	create_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 DDSTopicDescription *	get_topicdescription ()
	Returns the DDSTopicDescription associated with the DDSDataReader. More...

virtual DDSSubscriber *	get_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 DDSDataReaderListener *	get_listener ()
	Gets the reader listener. More...

virtual DDSTopicQuery *	create_topic_query (const DDS_TopicQuerySelection &selection)
	Creates a DDSTopicQuery. More...

virtual DDS_ReturnCode_t	delete_topic_query (DDSTopicQuery *query)
	Deletes a DDSTopicQuery. More...

virtual DDSTopicQuery *	lookup_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 DDSStatusCondition *	get_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 DDSStatusCondition *	get_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...

Static Public Member Functions
static FooDataReader *	narrow (DDSDataReader *reader)
	Narrow the given DDSDataReader pointer to a FooDataReader pointer. More...

Detailed Description

<<interface>> <<generic>> User data type-specific data reader.

Defines the user data type specific reader interface generated for each application class.

The concrete user data type reader automatically generated by the implementation is an incarnation of this class.

See also: DDSDataReader; Foo; FooDataWriter; the Code Generator User's Manual

Member Function Documentation

◆ narrow()

static FooDataReader * FooDataReader::narrow ( DDSDataReader * reader )

static

Narrow the given DDSDataReader pointer to a FooDataReader pointer.

◆ read()

virtual DDS_ReturnCode_t FooDataReader::read	(	FooSeq &	received_data,
		DDS_SampleInfoSeq &	info_seq,
		DDS_Long	max_samples,
		DDS_SampleStateMask	sample_states,
		DDS_ViewStateMask	view_states,
		DDS_InstanceStateMask	instance_states
	)

pure virtual

Access a collection of data samples from the DDSDataReader.

This operation offers the same functionality and API as FooDataReader::take except that the samples returned remain in the DDSDataReader such that they can be retrieved again by means of a read or take operation.

Please refer to the documentation of FooDataReader::take() for details on the number of samples returned within the received_data and info_seq as well as the order in which the samples appear in these sequences.

The act of reading a sample changes its sample_state to DDS_READ_SAMPLE_STATE. If the sample belongs to the most recent generation of the instance, it will also set the view_state of the instance to be DDS_NOT_NEW_VIEW_STATE. It will not affect the instance_state of the instance.

Once the application completes its use of the samples, it must 'return the loan' to the DDSDataReader by calling the FooDataReader::return_loan operation.

Important: When you loan data from the middleware, you must not keep any pointers to any part of the data samples or the DDS_SampleInfo objects after the call to FooDataReader::return_loan. Returning the loan places the objects back into a pool, allowing the middleware to overwrite them with new data.

Note: While you must call FooDataReader::return_loan at some point, you do not have to do so before the next FooDataReader::take call. However, failure to return the loan will eventually deplete the DDSDataReader of the buffers it needs to receive new samples and eventually samples will start to be lost. The total number of buffers available to the DDSDataReader is specified by the DDS_ResourceLimitsQosPolicy and the DDS_DataReaderResourceLimitsQosPolicy.

Important: If the samples "returned" by this method are loaned from RTI Connext (see FooDataReader::take for more information on memory loaning), it is important that their contents not be changed. Because the memory in which the data is stored belongs to the middleware, any modifications made to the data will be seen the next time the same samples are read or taken; the samples will no longer reflect the state that was received from the network.

Parameters

received_data	<<inout>> User data type-specific FooSeq object where the received data samples will be returned.
info_seq	<<inout>> A DDS_SampleInfoSeq object where the received sample info will be returned.
max_samples	<<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for FooDataReader::take().
sample_states	<<in>> Data samples matching one of these `sample_states` are returned.
view_states	<<in>> Data samples matching one of these `view_state` are returned.
instance_states	<<in>> Data samples matching ones of these `instance_state` are returned.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.

See also: FooDataReader::take; FooDataReader::read_w_condition,; FooDataReader::take_w_condition; DDS_LENGTH_UNLIMITED

◆ take()

virtual DDS_ReturnCode_t FooDataReader::take	(	FooSeq &	received_data,
		DDS_SampleInfoSeq &	info_seq,
		DDS_Long	max_samples,
		DDS_SampleStateMask	sample_states,
		DDS_ViewStateMask	view_states,
		DDS_InstanceStateMask	instance_states
	)

pure virtual

Access a collection of data-samples from the DDSDataReader.

The operation will return the list of samples received by the DDSDataReader since the last FooDataReader::take operation that matches the specified DDS_SampleStateMask, DDS_ViewStateMask and DDS_InstanceStateMask.

This operation may fail with DDS_RETCODE_ERROR if the DDS_DataReaderResourceLimitsQosPolicy::max_outstanding_reads limit has been exceeded.

The actual number of samples returned depends on the information that has been received by the middleware as well as the DDS_HistoryQosPolicy, DDS_ResourceLimitsQosPolicy, DDS_DataReaderResourceLimitsQosPolicy and the characteristics of the data-type that is associated with the DDSDataReader:

In the case where the DDS_HistoryQosPolicy::kind is DDS_KEEP_LAST_HISTORY_QOS, the call will return at most DDS_HistoryQosPolicy::depth samples for each ALIVE instance and (DDS_HistoryQosPolicy::depth +1) samples for each NOT_ALIVE instance. The extra sample is an invalid sample (DDS_SampleInfo::valid_data is FALSE) that is used to indicate the instance state transition from ALIVE to NOT_ALIVE.

The maximum number of samples returned is limited by DDS_ResourceLimitsQosPolicy::max_samples, and by DDS_DataReaderResourceLimitsQosPolicy::max_samples_per_read.

For multiple instances, the number of samples returned is additionally limited by the product (DDS_ResourceLimitsQosPolicy::max_samples_per_instance
- DDS_ResourceLimitsQosPolicy::max_instances)

If DDS_DataReaderResourceLimitsQosPolicy::max_infos is limited, the number of samples returned may also be limited if insufficient DDS_SampleInfo resources are available.

If the read or take succeeds and the number of samples returned has been limited (by means of a maximum limit, as listed above, or insufficient DDS_SampleInfo resources), the call will complete successfully and provide those samples the reader is able to return. The user may need to make additional calls, or return outstanding loaned buffers in the case of insufficient resources, in order to access remaining samples.

Note that in the case where the DDSTopic associated with the DDSDataReader is bound to a data-type that has no key definition, then there will be at most one instance in the DDSDataReader. So the per-sample limits will apply.

The act of taking a sample removes it from RTI Connext so it cannot be read or taken again. If the sample belongs to the most recent generation of the instance, it will also set the view_state of the sample's instance to DDS_NOT_NEW_VIEW_STATE. It will not affect the instance_state of the sample's instance.

After FooDataReader::take completes, received_data and info_seq will be of the same length and contain the received data.

If the sequences are empty (maximum size equals 0) when the FooDataReader::take is called, the samples returned in the received_data and the corresponding info_seq are 'loaned' to the application from buffers provided by the DDSDataReader. The application can use them as desired and has guaranteed exclusive access to them.

Once the application completes its use of the samples it must 'return the loan' to the DDSDataReader by calling the FooDataReader::return_loan operation.

Important: When you loan data from the middleware, you must not keep any pointers to any part of the data samples or the DDS_SampleInfo objects after the call to FooDataReader::return_loan. Returning the loan places the objects back into a pool, allowing the middleware to overwrite them with new data.

Note: While you must call FooDataReader::return_loan at some point, you do not have to do so before the next FooDataReader::take call. However, failure to return the loan will eventually deplete the DDSDataReader of the buffers it needs to receive new samples and eventually samples will start to be lost. The total number of buffers available to the DDSDataReader is specified by the DDS_ResourceLimitsQosPolicy and the DDS_DataReaderResourceLimitsQosPolicy.

If the sequences are not empty (maximum size not equal to 0 and length not equal to 0) when FooDataReader::take is called, samples are copied to received_data and info_seq. The application will not need to call FooDataReader::return_loan.

The order of the samples returned to the caller depends on the DDS_PresentationQosPolicy.

If DDS_PresentationQosPolicy::access_scope is DDS_INSTANCE_PRESENTATION_QOS, the returned collection is a list where samples belonging to the same data instance are consecutive.

If DDS_PresentationQosPolicy::access_scope is DDS_TOPIC_PRESENTATION_QOS and DDS_PresentationQosPolicy::ordered_access is set to DDS_BOOLEAN_FALSE, then the returned collection is a list where samples belonging to the same data instance are consecutive.

If DDS_PresentationQosPolicy::access_scope is DDS_TOPIC_PRESENTATION_QOS and DDS_PresentationQosPolicy::ordered_access is set to DDS_BOOLEAN_TRUE, then the returned collection is a list where the relative order of samples as they were written by a DataWriter is preserved also across different instances. In other words, changes made by a single DataWriter are made available to subscribers in the same order in which they occur. Samples belonging to the same instance may or may not be consecutive. This is because, to preserve order within a single DataWriter, it may be necessary to mix samples from different instances.

If DDS_PresentationQosPolicy::access_scope is DDS_GROUP_PRESENTATION_QOS and DDS_PresentationQosPolicy::ordered_access is set to DDS_BOOLEAN_FALSE, then the returned collection is a list where samples belonging to the same data instance are consecutive.

If DDS_PresentationQosPolicy::access_scope is DDS_GROUP_PRESENTATION_QOS and DDS_PresentationQosPolicy::ordered_access is set to DDS_BOOLEAN_TRUE, then changes made to instances by a set of DataWriters attached to a common Publisher are made available in the order in which they were written. For this to happen, the application must take the samples using the Subscriber's DDSSubscriber::begin_access and DDSSubscriber::end_access operations (see the "Ordered Access" section in the "PRESENTATION QosPolicy" section of the Core Libraries User's Manual).

In all of the above cases, the relative order between the samples of one instance is consistent with the DESTINATION_ORDER policy:

If DDS_DestinationOrderQosPolicy::kind is DDS_BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS, samples belonging to the same instances will appear in the relative order in which there were received (FIFO, earlier samples ahead of the later samples).

If DDS_DestinationOrderQosPolicy::kind is DDS_BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS, samples belonging to the same instances will appear in the relative order implied by the source_timestamp (FIFO, smaller values of source_timestamp ahead of the larger values).

If the DDSDataReader has no samples that meet the constraints, the method will fail with DDS_RETCODE_NO_DATA.

In addition to the collection of samples, the read and take operations also use a collection of DDS_SampleInfo structures.

The initial (input) properties of the received_data and info_seq collections will determine the precise behavior of the read or take operation. For the purposes of this description, the collections are modeled as having these properties:

whether the collection container owns the memory of the elements within (owns, see FooSeq::has_ownership)
the current-length (len, see FooSeq::length())
the maximum length (max_len, see FooSeq::maximum())

The initial values of the owns, len and max_len properties for the received_data and info_seq collections govern the behavior of the read and take operations as specified by the following rules:

The values of owns, len and max_len properties for the two collections must be identical. Otherwise read/take will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
On successful output, the values of owns, len and max_len will be the same for both collections.
If the initial max_len==0, then the received_data and info_seq collections will be filled with elements that are loaned by the DDSDataReader. On output, owns will be FALSE, len will be set to the number of values returned, and max_len will be set to a value verifying max_len >= len. The use of this variant allows for Zero Copy access to the data and the application will need to return the loan to the DDSDataWriter using FooDataReader::return_loan.
If the initial max_len>0 and owns==FALSE, then the read or take operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET. This avoids the potential hard-to-detect memory leaks caused by an application forgetting to return the loan.
If initial max_len>0 and owns==TRUE, then the read or take operation will copy the received_data values and DDS_SampleInfo values into the elements already inside the collections. On output, owns will be TRUE, len will be set to the number of values copied and max_len will remain unchanged. The use of this variant forces a copy but the application can control where the copy is placed and the application will not need to return the loan. The number of samples copied depends on the relative values of max_len and max_samples:
- If max_samples == LENGTH_UNLIMITED, then at most max_len values will be copied. The use of this variant lets the application limit the number of samples returned to what the sequence can accommodate.
- If max_samples <= max_len, then at most max_samples values will be copied. The use of this variant lets the application limit the number of samples returned to fewer that what the sequence can accommodate.
- If max_samples > max_len, then the read or take operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET. This avoids the potential confusion where the application expects to be able to access up to max_samples, but that number can never be returned, even if they are available in the DDSDataReader, because the output sequence cannot accommodate them.

As described above, upon completion, the received_data and info_seq collections may contain elements loaned from the DDSDataReader. If this is the case, the application will need to use FooDataReader::return_loan to return the loan once it is no longer using the received_data in the collection. When FooDataReader::return_loan completes, the collection will have owns=FALSE and max_len=0. The application can determine whether it is necessary to return the loan or not based on how the state of the collections when the read/take operation was called or by accessing the owns property. However, in many cases it may be simpler to always call FooDataReader::return_loan, as this operation is harmless (i.e., it leaves all elements unchanged) if the collection does not have a loan. To avoid potential memory leaks, the implementation of the Foo and DDS_SampleInfo collections should disallow changing the length of a collection for which owns==FALSE. Furthermore, deleting a collection for which owns==FALSE should be considered an error.

On output, the collection of Foo values and the collection of DDS_SampleInfo structures are of the same length and are in a one-to-one correspondence. Each DDS_SampleInfo provides information, such as the source_timestamp, the sample_state, view_state, and instance_state, etc., about the corresponding sample. Some elements in the returned collection may not have valid data. If the instance_state in the DDS_SampleInfo is DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE or DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE, then the last sample for that instance in the collection (that is, the one whose DDS_SampleInfo has sample_rank==0) does not contain valid data.

Samples that contain no data do not count towards the limits imposed by the DDS_ResourceLimitsQosPolicy. The act of reading/taking a sample sets its sample_state to DDS_READ_SAMPLE_STATE.

If the sample belongs to the most recent generation of the instance, it will also set the view_state of the instance to DDS_NOT_NEW_VIEW_STATE. It will not affect the instance_state of the instance.

This operation must be provided on the specialized class that is generated for the particular application data-type that is being read (Foo).

If the DDSDataReader has no samples that meet the constraints, the operations fails with DDS_RETCODE_NO_DATA. For an example on how take can be used, please refer to the Access received data via a reader "receive example".

Parameters

received_data	<<inout>> User data type-specific FooSeq object where the received data samples will be returned.
info_seq	<<inout>> A DDS_SampleInfoSeq object where the received sample info will be returned.
max_samples	<<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described above.
sample_states	<<in>> Data samples matching one of these `sample_states` are returned.
view_states	<<in>> Data samples matching one of these `view_state` are returned.
instance_states	<<in>> Data samples matching one of these `instance_state` are returned.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.

See also: FooDataReader::read; FooDataReader::read_w_condition, FooDataReader::take_w_condition; DDS_LENGTH_UNLIMITED

◆ read_w_condition()

virtual DDS_ReturnCode_t FooDataReader::read_w_condition	(	FooSeq &	received_data,
		DDS_SampleInfoSeq &	info_seq,
		DDS_Long	max_samples,
		DDSReadCondition *	condition
	)

pure virtual

Accesses via FooDataReader::read the samples that match the criteria specified in the DDSReadCondition.

This operation is especially useful in combination with DDSQueryCondition to filter data samples based on the content.

The specified DDSReadCondition must be attached to the DDSDataReader; otherwise the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

In case the DDSReadCondition is a plain DDSReadCondition and not the specialized DDSQueryCondition, the operation is equivalent to calling FooDataReader::read and passing as sample_states, view_states and instance_states the value of the corresponding attributes in the read_condition. Using this operation, the application can avoid repeating the same parameters specified when creating the DDSReadCondition.

The samples are accessed with the same semantics as FooDataReader::read.

If the DDSDataReader has no samples that meet the constraints, the operation will fail with DDS_RETCODE_NO_DATA.

Parameters

received_data	<<inout>> user data type-specific FooSeq object where the received data samples will be returned.
info_seq	<<inout>> a DDS_SampleInfoSeq object where the received sample info will be returned.
max_samples	<<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for FooDataReader::take().
condition	<<in>> the DDSReadCondition to select samples of interest. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.

See also: FooDataReader::read; FooDataReader::take, FooDataReader::take_w_condition; DDS_LENGTH_UNLIMITED

◆ take_w_condition()

virtual DDS_ReturnCode_t FooDataReader::take_w_condition	(	FooSeq &	received_data,
		DDS_SampleInfoSeq &	info_seq,
		DDS_Long	max_samples,
		DDSReadCondition *	condition
	)

pure virtual

Analogous to FooDataReader::read_w_condition except it accesses samples via the FooDataReader::take operation.

This operation is analogous to FooDataReader::read_w_condition except that it accesses samples via the FooDataReader::take operation.

The specified DDSReadCondition must be attached to the DDSDataReader; otherwise the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

The samples are accessed with the same semantics as FooDataReader::take.

This operation is especially useful in combination with DDSQueryCondition to filter data samples based on the content.

If the DDSDataReader has no samples that meet the constraints, the method will fail with DDS_RETCODE_NO_DATA.

Parameters

received_data	<<inout>> user data type-specific FooSeq object where the received data samples will be returned.
info_seq	<<inout>> a DDS_SampleInfoSeq object where the received sample info will be returned.
max_samples	<<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for FooDataReader::take().
condition	<<in>> the DDSReadCondition to select samples of interest. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.

See also: FooDataReader::read_w_condition, FooDataReader::read; FooDataReader::take; DDS_LENGTH_UNLIMITED

◆ read_next_sample()

virtual DDS_ReturnCode_t FooDataReader::read_next_sample	(	Foo &	received_data,
		DDS_SampleInfo &	sample_info
	)

pure virtual

Copies the next not-previously-accessed data value from the DDSDataReader.

This operation copies the next not-previously-accessed data value from the DDSDataReader. This operation also copies the corresponding DDS_SampleInfo. The implied order among the samples stored in the DDSDataReader is the same as for the FooDataReader::read operation.

The FooDataReader::read_next_sample operation is semantically equivalent to the FooDataReader::read operation, where the input data sequences has max_len=1, the sample_states=NOT_READ, the view_states=ANY_VIEW_STATE, and the instance_states=ANY_INSTANCE_STATE.

The FooDataReader::read_next_sample operation provides a simplified API to 'read' samples, avoiding the need for the application to manage sequences and specify states.

If there is no unread data in the DDSDataReader, the operation will fail with DDS_RETCODE_NO_DATA and nothing is copied.

Note: Calling FooDataReader::read_next_sample from the DDSDataReaderListener::on_data_available() callback reads only one sample of potentially many samples in the reader queue, because DDSDataReaderListener::on_data_available() is triggered only once when new samples arrive in the queue. Therefore, it is recommended that you call FooDataReader::read_next_sample in a loop within the on_data_available callback until FooDataReader::read_next_sample returns DDS_RETCODE_NO_DATA . This ensures that all samples in the reader queue are serviced by application logic. (You may also choose to use FooDataReader::read rather than FooDataReader::read_next_sample in order to read more than one sample at a time.)

Parameters

received_data	<<inout>> user data type-specific Foo object where the next received data sample will be returned. The received_data must have been fully allocated. Otherwise, this operation may fail.
sample_info	<<inout>> a DDS_SampleInfo object where the next received sample info will be returned.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.

See also: FooDataReader::read

◆ take_next_sample()

virtual DDS_ReturnCode_t FooDataReader::take_next_sample	(	Foo &	received_data,
		DDS_SampleInfo &	sample_info
	)

pure virtual

Copies the next not-previously-accessed data value from the DDSDataReader.

This operation copies the next not-previously-accessed data value from the DDSDataReader and 'removes' it from the DDSDataReader so that it is no longer accessible. This operation also copies the corresponding DDS_SampleInfo. This operation is analogous to the FooDataReader::read_next_sample except for the fact that the sample is removed from the DDSDataReader.

The FooDataReader::take_next_sample operation is semantically equivalent to the FooDataReader::take operation, where the input data sequences has max_len=1, the sample_states=NOT_READ, the view_states=ANY_VIEW_STATE, and the instance_states=ANY_INSTANCE_STATE.

The FooDataReader::take_next_sample operation provides a simplified API to 'take' samples, avoiding the need for the application to manage sequences and specify states.

If there is no unread data in the DDSDataReader, the operation will fail with DDS_RETCODE_NO_DATA and nothing is copied.

Note: Calling FooDataReader::take_next_sample from the DDSDataReaderListener::on_data_available() callback retrieves only one sample of potentially many samples in the reader queue, because DDSDataReaderListener::on_data_available() is triggered only once when new samples arrive in the queue. Therefore, it is recommended that you call FooDataReader::take_next_sample in a loop within the on_data_available callback until FooDataReader::take_next_sample returns DDS_RETCODE_NO_DATA . This ensures that all samples in the reader queue are serviced by application logic. (You may also choose to use the FooDataReader::take rather than FooDataReader::take_next_sample in order to take more than one sample at a time.)

Parameters

received_data	<<inout>> user data type-specific Foo object where the next received data sample will be returned. The received_data must have been fully allocated. Otherwise, this operation may fail.
sample_info	<<inout>> a DDS_SampleInfo object where the next received sample info will be returned.

Exceptions

One	of the Standard Return Codes,

DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.

See also: FooDataReader::take

◆ read_instance()

virtual DDS_ReturnCode_t FooDataReader::read_instance	(	FooSeq &	received_data,
		DDS_SampleInfoSeq &	info_seq,
		DDS_Long	max_samples,
		const DDS_InstanceHandle_t &	a_handle,
		DDS_SampleStateMask	sample_states,
		DDS_ViewStateMask	view_states,
		DDS_InstanceStateMask	instance_states
	)

pure virtual

Access a collection of data samples from the DDSDataReader.

This operation accesses a collection of data values from the DDSDataReader. The behavior is identical to FooDataReader::read, except that all samples returned belong to the single specified instance whose handle is a_handle.

Upon successful completion, the data collection will contain samples all belonging to the same instance. The corresponding DDS_SampleInfo verifies DDS_SampleInfo::instance_handle == a_handle.

The FooDataReader::read_instance operation is semantically equivalent to the FooDataReader::read operation, except in building the collection, the DDSDataReader will check that the sample belongs to the specified instance and otherwise it will not place the sample in the returned collection.

The behavior of the FooDataReader::read_instance operation follows the same rules as the FooDataReader::read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to the FooDataReader::read, the FooDataReader::read_instance operation may 'loan' elements to the output collections, which must then be returned by means of FooDataReader::return_loan.

Similar to the FooDataReader::read, this operation must be provided on the specialized class that is generated for the particular application data-type that is being taken.

If the DDSDataReader has no samples that meet the constraints, the method will fail with DDS_RETCODE_NO_DATA.

This operation may fail with DDS_RETCODE_BAD_PARAMETER if the DDS_InstanceHandle_t a_handle does not correspond to an existing data-object known to the DDSDataReader.

Parameters

received_data	<<inout>> user data type-specific FooSeq object where the received data samples will be returned.
info_seq	<<inout>> a DDS_SampleInfoSeq object where the received sample info will be returned.
max_samples	<<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for FooDataReader::take().
a_handle	<<in>> The specified instance to return samples for. The method will fail with DDS_RETCODE_BAD_PARAMETER if the `handle` does not correspond to an existing data-object known to the DDSDataReader.
sample_states	<<in>> data samples matching ones of these `sample_states` are returned.
view_states	<<in>> data samples matching ones of these `view_state` are returned.
instance_states	<<in>> data samples matching ones of these `instance_state` are returned.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.

See also: FooDataReader::read; DDS_LENGTH_UNLIMITED

◆ take_instance()

virtual DDS_ReturnCode_t FooDataReader::take_instance	(	FooSeq &	received_data,
		DDS_SampleInfoSeq &	info_seq,
		DDS_Long	max_samples,
		const DDS_InstanceHandle_t &	a_handle,
		DDS_SampleStateMask	sample_states,
		DDS_ViewStateMask	view_states,
		DDS_InstanceStateMask	instance_states
	)

pure virtual

Access a collection of data samples from the DDSDataReader.

This operation accesses a collection of data values from the DDSDataReader. The behavior is identical to FooDataReader::take, except for that all samples returned belong to the single specified instance whose handle is a_handle.

The semantics are the same for the FooDataReader::take operation, except in building the collection, the DDSDataReader will check that the sample belongs to the specified instance, and otherwise it will not place the sample in the returned collection.

The behavior of the FooDataReader::take_instance operation follows the same rules as the FooDataReader::read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to the FooDataReader::read, the FooDataReader::take_instance operation may 'loan' elements to the output collections, which must then be returned by means of FooDataReader::return_loan.

Similar to the FooDataReader::read, this operation must be provided on the specialized class that is generated for the particular application data-type that is being taken.

If the DDSDataReader has no samples that meet the constraints, the method fails with DDS_RETCODE_NO_DATA.

This operation may fail with DDS_RETCODE_BAD_PARAMETER if the DDS_InstanceHandle_t a_handle does not correspond to an existing data-object known to the DDSDataReader.

Parameters

received_data	<<inout>> user data type-specific FooSeq object where the received data samples will be returned.
info_seq	<<inout>> a DDS_SampleInfoSeq object where the received sample info will be returned.
max_samples	<<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for FooDataReader::take().
a_handle	<<in>> The specified instance to return samples for. The method will fail with DDS_RETCODE_BAD_PARAMETER if the `handle` does not correspond to an existing data-object known to the DDSDataReader.
sample_states	<<in>> data samples matching ones of these `sample_states` are returned.
view_states	<<in>> data samples matching ones of these `view_state` are returned.
instance_states	<<in>> data samples matching ones of these `instance_state` are returned.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.

See also: FooDataReader::take; DDS_LENGTH_UNLIMITED

◆ read_instance_w_condition()

virtual DDS_ReturnCode_t FooDataReader::read_instance_w_condition	(	FooSeq &	received_data,
		DDS_SampleInfoSeq &	info_seq,
		DDS_Long	max_samples,
		const DDS_InstanceHandle_t &	previous_handle,
		DDSReadCondition *	condition
	)

pure virtual

<<extension>> Accesses via FooDataReader::read_instance the samples that match the criteria specified in the DDSReadCondition.

This operation accesses a collection of data values from the DDSDataReader. The behavior is identical to FooDataReader::read_instance, except that all returned samples satisfy the specified condition. In other words, on success, all returned samples belong to belong the single specified instance whose handle is a_handle, and for which the specified DDSReadCondition evaluates to TRUE.

The behavior of the FooDataReader::read_instance_w_condition operation follows the same rules as the FooDataReader::read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to the FooDataReader::read, the FooDataReader::read_instance_w_condition operation may 'loan' elements to the output collections, which must then be returned by means of FooDataReader::return_loan.

Similar to FooDataReader::read, this operation must be provided on the specialized class that is generated for the particular application data-type that is being taken.

If the DDSDataReader has no samples that meet the constraints, the method will fail with DDS_RETCODE_NO_DATA.

Parameters

received_data	<<inout>> user data type-specific FooSeq object where the received data samples will be returned.
info_seq	<<inout>> a DDS_SampleInfoSeq object where the received sample info will be returned.
max_samples	<<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for FooDataReader::take().
previous_handle	<<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned.
condition	<<in>> the DDSReadCondition to select samples of interest. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.

See also: FooDataReader::read_next_instance; DDS_LENGTH_UNLIMITED

◆ take_instance_w_condition()

virtual DDS_ReturnCode_t FooDataReader::take_instance_w_condition	(	FooSeq &	received_data,
		DDS_SampleInfoSeq &	info_seq,
		DDS_Long	max_samples,
		const DDS_InstanceHandle_t &	previous_handle,
		DDSReadCondition *	condition
	)

pure virtual

<<extension>> Accesses via FooDataReader::take_instance the samples that match the criteria specified in the DDSReadCondition.

This operation accesses a collection of data values from the DDSDataReader and 'removes' them from the DDSDataReader. The behavior is identical to FooDataReader::take_instance, except that all returned samples satisfy the specified condition. In other words, on success, all returned samples belong to belong the single specified instance whose handle is a_handle, and for which the specified DDSReadCondition evaluates to TRUE.

The operation has the same behavior as FooDataReader::read_instance_w_condition, except that the samples are 'taken' from the DDSDataReader such that they are no longer accessible via subsequent 'read' or 'take' operations.

The behavior of the FooDataReader::take_instance_w_condition operation follows the same rules as the FooDataReader::read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to the FooDataReader::read, the FooDataReader::take_instance_w_condition operation may 'loan' elements to the output collections, which must then be returned by means of FooDataReader::return_loan.

Similar to the FooDataReader::read, this operation must be provided on the specialized class that is generated for the particular application data-type that is being taken.

If the DDSDataReader has no samples that meet the constraints, the method will fail with DDS_RETCODE_NO_DATA.

Parameters

received_data	<<inout>> user data type-specific FooSeq object where the received data samples will be returned.
info_seq	<<inout>> a DDS_SampleInfoSeq object where the received sample info will be returned.
max_samples	<<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for FooDataReader::take().
previous_handle	<<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned.
condition	<<in>> the DDSReadCondition to select samples of interest. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, or DDS_RETCODE_NO_DATA, DDS_RETCODE_NOT_ENABLED.

See also: FooDataReader::take_next_instance; DDS_LENGTH_UNLIMITED

◆ read_next_instance()

virtual DDS_ReturnCode_t FooDataReader::read_next_instance	(	FooSeq &	received_data,
		DDS_SampleInfoSeq &	info_seq,
		DDS_Long	max_samples,
		const DDS_InstanceHandle_t &	previous_handle,
		DDS_SampleStateMask	sample_states,
		DDS_ViewStateMask	view_states,
		DDS_InstanceStateMask	instance_states
	)

pure virtual

Access a collection of data samples from the DDSDataReader.

This operation accesses a collection of data values from the DDSDataReader where all the samples belong to a single instance. The behavior is similar to FooDataReader::read_instance, except that the actual instance is not directly specified. Rather, the samples will all belong to the 'next' instance with instance_handle 'greater' than the specified 'previous_handle' that has available samples.

This operation implies the existence of a total order 'greater-than' relationship between the instance handles. The specifics of this relationship are not all important and are implementation specific. The important thing is that, according to the middleware, all instances are ordered relative to each other. This ordering is between the instance handles; It should not depend on the state of the instance (e.g. whether it has data or not) and must be defined even for instance handles that do not correspond to instances currently managed by the DDSDataReader. For the purposes of the ordering, it should be 'as if' each instance handle was represented as unique integer.

The behavior of FooDataReader::read_next_instance is 'as if' the DDSDataReader invoked FooDataReader::read_instance, passing the smallest instance_handle among all the ones that: (a) are greater than previous_handle, and (b) have available samples (i.e. samples that meet the constraints imposed by the specified states).

The special value DDS_HANDLE_NIL is guaranteed to be 'less than' any valid instance_handle. So the use of the parameter value previous_handle == DDS_HANDLE_NIL will return the samples for the instance which has the smallest instance_handle among all the instances that contain available samples.

Note: The operation FooDataReader::read_next_instance is intended to be used in an application-driven iteration, where the application starts by passing previous_handle == DDS_HANDLE_NIL, examines the samples returned, and then uses the instance_handle returned in the DDS_SampleInfo as the value of the previous_handle argument to the next call to FooDataReader::read_next_instance. The iteration continues until FooDataReader::read_next_instance fails with DDS_RETCODE_NO_DATA. This application-driven iteration is required to ensure that all samples on the reader queue are read.

Note that it is possible to call the FooDataReader::read_next_instance operation with a previous_handle that does not correspond to an instance currently managed by the DDSDataReader. This is because as stated earlier the 'greater-than' relationship is defined even for handles not managed by the DDSDataReader. One practical situation where this may occur is when an application is iterating though all the instances, takes all the samples of a DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE instance, returns the loan (at which point the instance information may be removed, and thus the handle becomes invalid), and tries to read the next instance. The behavior of the FooDataReader::read_next_instance operation follows the same rules as the FooDataReader::read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to the FooDataReader::read, the FooDataReader::read_instance operation may 'loan' elements to the output collections, which must then be returned by means of FooDataReader::return_loan.

Similar to the FooDataReader::read, this operation must be provided on the specialized class that is generated for the particular application data-type that is being taken.

If the DDSDataReader has no samples that meet the constraints, the method will fail with DDS_RETCODE_NO_DATA.

Parameters

received_data	<<inout>> user data type-specific FooSeq object where the received data samples will be returned.
info_seq	<<inout>> a DDS_SampleInfoSeq object where the received sample info will be returned.
max_samples	<<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for FooDataReader::take().
previous_handle	<<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned.
sample_states	<<in>> data samples matching ones of these `sample_states` are returned.
view_states	<<in>> data samples matching ones of these `view_state` are returned.
instance_states	<<in>> data samples matching ones of these `instance_state` are returned.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.

See also: FooDataReader::read; DDS_LENGTH_UNLIMITED

◆ take_next_instance()

virtual DDS_ReturnCode_t FooDataReader::take_next_instance	(	FooSeq &	received_data,
		DDS_SampleInfoSeq &	info_seq,
		DDS_Long	max_samples,
		const DDS_InstanceHandle_t &	previous_handle,
		DDS_SampleStateMask	sample_states,
		DDS_ViewStateMask	view_states,
		DDS_InstanceStateMask	instance_states
	)

pure virtual

Access a collection of data samples from the DDSDataReader.

This operation accesses a collection of data values from the DDSDataReader and 'removes' them from the DDSDataReader.

This operation has the same behavior as FooDataReader::read_next_instance, except that the samples are 'taken' from the DDSDataReader such that they are no longer accessible via subsequent 'read' or 'take' operations.

Note: Like FooDataReader::read_next_instance, this operation is intended to be used in an application-driven iteration until all samples on the reader queue are taken. The iteration continues until FooDataReader::take_next_instance fails with the value DDS_RETCODE_NO_DATA .

Similar to the operation FooDataReader::read_next_instance, it is possible to call FooDataReader::take_next_instance with a previous_handle that does not correspond to an instance currently managed by the DDSDataReader.

The behavior of the FooDataReader::take_next_instance operation follows the same rules as the FooDataReader::read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to the FooDataReader::read, the FooDataReader::take_next_instance operation may 'loan' elements to the output collections, which must then be returned by means of FooDataReader::return_loan.

Similar to the FooDataReader::read, this operation must be provided on the specialized class that is generated for the particular application data-type that is being taken.

If the DDSDataReader has no samples that meet the constraints, the method will fail with DDS_RETCODE_NO_DATA.

Parameters

received_data	<<inout>> user data type-specific FooSeq object where the received data samples will be returned.
info_seq	<<inout>> a DDS_SampleInfoSeq object where the received sample info will be returned.
max_samples	<<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for FooDataReader::take().
previous_handle	<<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned.
sample_states	<<in>> data samples matching ones of these `sample_states` are returned.
view_states	<<in>> data samples matching ones of these `view_state` are returned.
instance_states	<<in>> data samples matching ones of these `instance_state` are returned.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.

See also: FooDataReader::take; DDS_LENGTH_UNLIMITED

◆ read_next_instance_w_condition()

virtual DDS_ReturnCode_t FooDataReader::read_next_instance_w_condition	(	FooSeq &	received_data,
		DDS_SampleInfoSeq &	info_seq,
		DDS_Long	max_samples,
		const DDS_InstanceHandle_t &	previous_handle,
		DDSReadCondition *	condition
	)

pure virtual

Accesses via FooDataReader::read_next_instance the samples that match the criteria specified in the DDSReadCondition.

This operation accesses a collection of data values from the DDSDataReader. The behavior is identical to FooDataReader::read_next_instance, except that all returned samples satisfy the specified condition. In other words, on success, all returned samples belong to the same instance, and the instance is the instance with 'smallest' instance_handle among the ones that verify: (a) instance_handle >= previous_handle, and (b) have samples for which the specified DDSReadCondition evaluates to TRUE.

Similar to the operation FooDataReader::read_next_instance, it is possible to call FooDataReader::read_next_instance_w_condition with a previous_handle that does not correspond to an instance currently managed by the DDSDataReader.

The behavior of the FooDataReader::read_next_instance_w_condition operation follows the same rules as the FooDataReader::read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to the FooDataReader::read, the FooDataReader::read_next_instance_w_condition operation may 'loan' elements to the output collections, which must then be returned by means of FooDataReader::return_loan.

Similar to the FooDataReader::read, this operation must be provided on the specialized class that is generated for the particular application data-type that is being taken.

If the DDSDataReader has no samples that meet the constraints, the method will fail with DDS_RETCODE_NO_DATA.

Parameters

received_data	<<inout>> user data type-specific FooSeq object where the received data samples will be returned.
info_seq	<<inout>> a DDS_SampleInfoSeq object where the received sample info will be returned.
max_samples	<<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for FooDataReader::take().
previous_handle	<<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned.
condition	<<in>> the DDSReadCondition to select samples of interest. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.

See also: FooDataReader::read_next_instance; DDS_LENGTH_UNLIMITED

◆ take_next_instance_w_condition()

virtual DDS_ReturnCode_t FooDataReader::take_next_instance_w_condition	(	FooSeq &	received_data,
		DDS_SampleInfoSeq &	info_seq,
		DDS_Long	max_samples,
		const DDS_InstanceHandle_t &	previous_handle,
		DDSReadCondition *	condition
	)

pure virtual

Accesses via FooDataReader::take_next_instance the samples that match the criteria specified in the DDSReadCondition.

This operation accesses a collection of data values from the DDSDataReader and 'removes' them from the DDSDataReader.

The operation has the same behavior as FooDataReader::read_next_instance_w_condition, except that the samples are 'taken' from the DDSDataReader such that they are no longer accessible via subsequent 'read' or 'take' operations.

Similar to the operation FooDataReader::read_next_instance, it is possible to call FooDataReader::take_next_instance_w_condition with a previous_handle that does not correspond to an instance currently managed by the DDSDataReader.

The behavior of the FooDataReader::take_next_instance_w_condition operation follows the same rules as the FooDataReader::read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to FooDataReader::read, the FooDataReader::take_next_instance_w_condition operation may 'loan' elements to the output collections, which must then be returned by means of FooDataReader::return_loan.

Similar to the FooDataReader::read, this operation must be provided on the specialized class that is generated for the particular application data-type that is being taken.

If the DDSDataReader has no samples that meet the constraints, the method will fail with DDS_RETCODE_NO_DATA.

Parameters

received_data	<<inout>> user data type-specific FooSeq object where the received data samples will be returned.
info_seq	<<inout>> a DDS_SampleInfoSeq object where the received sample info will be returned.
max_samples	<<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for FooDataReader::take().
previous_handle	<<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned.
condition	<<in>> the DDSReadCondition to select samples of interest. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, or DDS_RETCODE_NO_DATA, DDS_RETCODE_NOT_ENABLED.

See also: FooDataReader::take_next_instance; DDS_LENGTH_UNLIMITED

◆ return_loan()

virtual DDS_ReturnCode_t FooDataReader::return_loan	(	FooSeq &	received_data,
		DDS_SampleInfoSeq &	info_seq
	)

pure virtual

Indicates to the DDSDataReader that the application is done accessing the collection of received_data and info_seq obtained by some earlier invocation of read or take on the DDSDataReader.

This operation indicates to the DDSDataReader that the application is done accessing the collection of received_data and info_seq obtained by some earlier invocation of read or take on the DDSDataReader.

The received_data and info_seq must belong to a single related "pair"; that is, they should correspond to a pair returned from a single call to read or take. The received_data and info_seq must also have been obtained from the same DDSDataReader to which they are returned. If either of these conditions is not met, the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

The operation FooDataReader::return_loan allows implementations of the read and take operations to "loan" buffers from the DDSDataReader to the application and in this manner provide "zerocopy" access to the data. During the loan, the DDSDataReader will guarantee that the data and sample-information are not modified.

It is not necessary for an application to return the loans immediately after the read or take calls. However, as these buffers correspond to internal resources inside the DDSDataReader, the application should not retain them indefinitely.

The use of FooDataReader::return_loan is only necessary if the read or take calls "loaned" buffers to the application. This only occurs if the received_data and info_Seq collections had max_len=0 at the time read or take was called.

The application may also examine the "owns" property of the collection to determine where there is an outstanding loan. However, calling FooDataReader::return_loan on a collection that does not have a loan is safe and has no side effects.

If the collections had a loan, upon completion of FooDataReader::return_loan, the collections will have max_len=0.

Similar to read, this operation must be provided on the specialized class that is generated for the particular application data-type that is being taken.

Parameters

received_data <<in>> user data type-specific FooSeq object where the received data samples was obtained from earlier invocation of read or take on the DDSDataReader.

Parameters

info_seq <<in>> a DDS_SampleInfoSeq object where the received sample info was obtained from earlier invocation of read or take on the DDSDataReader.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_NOT_ENABLED.

◆ get_key_value()

virtual DDS_ReturnCode_t FooDataReader::get_key_value	(	Foo &	key_holder,
		const DDS_InstanceHandle_t	handle
	)

pure virtual

Retrieve the instance key that corresponds to an instance handle.

Useful for keyed data types.

The operation will only fill the fields that form the key inside the key_holder instance. If the type has no keys, this method has no effect and exits with no error.

For keyed data types, this operation may fail with DDS_RETCODE_BAD_PARAMETER if the handle does not correspond to an existing data-object known to the DDSDataReader.

Parameters

key_holder	<<inout>> a user data type specific key holder, whose `key` fields are filled by this operation. If Foo has no key, this method has no effect.
handle	<<in>> the `instance` whose key is to be retrieved. If Foo has a key, `handle` must represent an existing instance of type Foo known to the DDSDataReader. Otherwise, this method will fail with DDS_RETCODE_BAD_PARAMETER.

If Foo has a key and handle is DDS_HANDLE_NIL, this method will fail with DDS_RETCODE_BAD_PARAMETER.

If Foo has a key and handle represents an instance of another type or an instance of type Foo that has been unregistered, this method will fail with DDS_RETCODE_BAD_PARAMETER. If Foo has no key, this method has no effect.

Exceptions

One	of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

See also: FooDataWriter::get_key_value

◆ lookup_instance()

virtual DDS_InstanceHandle_t FooDataReader::lookup_instance ( const Foo & key_holder )

pure virtual

Retrieves the instance handle that corresponds to an instance key_holder.

Useful for keyed data types.

This operation takes as a parameter an instance and returns a handle that can be used in subsequent operations that accept an instance handle as an argument. The instance parameter is only used for the purpose of examining the fields that define the key. If the instance is unknown to the DataReader, or if for any other reason the Service is unable to provide an instance handle, the Service will return the special value DDS_HANDLE_NIL.

Parameters

key_holder <<in>> a user data type specific key holder.

Returns: the instance handle associated with this instance. If Foo has no key, this method has no effect and returns DDS_HANDLE_NIL

◆ is_data_consistent()

virtual DDS_ReturnCode_t FooDataReader::is_data_consistent	(	DDS_Boolean &	is_data_consistent,
		const TData *	sample,
		const DDS_SampleInfo *	sample_info
	)

pure virtual

When using Zero Copy transfer over shared memory, checks if the sample has been overwritten by the DataWriter.

When a sample is received via Zero Copy transfer over shared memory, the sample can be reused by the DataWriter once it is removed from the DataWriter's send queue. Since there is no synchronization between the DataReader and the DataWriter, the sample could be overwritten by the DataWriter before it is processed by the DataReader. The FooDataReader::is_data_consistent operation can be used after processing the sample to check if it was overwritten by the DataWriter.

A precondition for using this operation is to set DDS_DataWriterShmemRefTransferModeSettings::enable_data_consistency_check to true.

Warning: This operation cannot be used when the data type is annotated with @language_binding(FLAT_DATA). Reading a FlatData sample delivered with Zero Copy transfer over shared memory while the DataWriter is overwriting it is undefined behavior. An application-level synchronization mechanism is required in this case.

Parameters

is_data_consistent	<<inout>> Set to true if the sample is consistent (i.e., the sample has not been overwritten by the DataWriter)
sample	<<in>> Sample to be validated
sample_info	<<in>> DDS_SampleInfo object received with the sample

Exceptions

One	of the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET.

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ narrow()

◆ read()

◆ take()

◆ read_w_condition()

◆ take_w_condition()

◆ read_next_sample()

◆ take_next_sample()

◆ read_instance()

◆ take_instance()

◆ read_instance_w_condition()

◆ take_instance_w_condition()

◆ read_next_instance()

◆ take_next_instance()

◆ read_next_instance_w_condition()

◆ take_next_instance_w_condition()

◆ return_loan()

◆ get_key_value()

◆ lookup_instance()

◆ is_data_consistent()