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

#include <dds_cpp_subscription.hxx>

Inheritance diagram for DDSDataReader:

List of all members.

Public Member Functions
virtual DDSEntity *	as_entity ()=0
	<<cert>> Accesses the DDSDataReader's supertype instance.
virtual DDSTopicDescription *	get_topicdescription ()=0
	<<cert>> Returns the DDSTopicDescription associated with the DDSDataReader.
virtual DDSSubscriber *	get_subscriber ()=0
	<<cert>> Returns the DDSSubscriber to which the DDSDataReader belongs.
virtual DDS_ReturnCode_t	set_qos (const DDS_DataReaderQos &qos)=0
	Sets the reader QoS.
virtual DDS_ReturnCode_t	get_qos (DDS_DataReaderQos &qos)=0
	Gets the reader QoS.
virtual DDS_ReturnCode_t	set_listener (const DDSDataReaderListener *listener, DDS_StatusMask mask)=0
	Sets the reader listener.
virtual DDSDataReaderListener *	get_listener ()=0
	Get the reader listener.
virtual DDS_ReturnCode_t	read_untyped (DDS_UntypedSampleSeq *received_data, DDS_SampleInfoSeq &info_seq, DDS_Long max_samples, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)=0
	<<cert>> Access a collection of data samples from the DDSDataReader.
virtual DDS_ReturnCode_t	take_untyped (DDS_UntypedSampleSeq *received_data, DDS_SampleInfoSeq &info_seq, DDS_Long max_samples, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)=0
	<<cert>> Access a collection of data-samples from the DDSDataReader.
virtual DDS_ReturnCode_t	read_instance_untyped (DDS_UntypedSampleSeq *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
	<<cert>> Access a collection of data samples from the DDSDataReader, all of which belong to the same instance .
virtual DDS_ReturnCode_t	take_instance_untyped (DDS_UntypedSampleSeq *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
	<<cert>> Access a collection of data samples from the DDSDataReader, all of which belong to the same instance .
virtual DDS_ReturnCode_t	read_next_sample_untyped (void *received_data, DDS_SampleInfo &sample_info)=0
	<<cert>> Copies the next not-previously-accessed data value from the DDSDataReader.
virtual DDS_ReturnCode_t	take_next_sample_untyped (void *received_data, DDS_SampleInfo &sample_info)=0
	<<cert>> Copies the next not-previously-accessed data value from the DDSDataReader.
virtual DDS_InstanceHandle_t	lookup_instance_untyped (const void *key_holder)=0
	<<cert>> Retrieve the DDS_InstanceHandle_t identifying a specific instance.
virtual DDS_ReturnCode_t	is_data_consistent_untyped (DDS_Boolean &is_data_consistent, const void *sample, const DDS_SampleInfo &sample_info)=0
	Checks if the sample has been overwritten by the DataWriter.
virtual DDS_ReturnCode_t	return_loan_untyped (DDS_UntypedSampleSeq *received_data, DDS_SampleInfoSeq &info_seq)=0
	<<cert>> 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.
virtual DDS_ReturnCode_t	get_subscription_matched_status (DDS_SubscriptionMatchedStatus &status)=0
	<<cert>> Accesses the DDS_SUBSCRIPTION_MATCHED_STATUS communication status.
virtual DDS_ReturnCode_t	get_liveliness_changed_status (DDS_LivelinessChangedStatus &status)=0
	<<cert>> Accesses the DDS_LIVELINESS_CHANGED_STATUS communication status.
virtual DDS_ReturnCode_t	get_sample_rejected_status (DDS_SampleRejectedStatus &status)=0
	<<cert>> Accesses the DDS_SAMPLE_REJECTED_STATUS communication status.
virtual DDS_ReturnCode_t	get_sample_lost_status (DDS_SampleLostStatus &status)=0
	<<cert>> Accesses the DDS_SAMPLE_LOST_STATUS communication status.
virtual DDS_ReturnCode_t	get_requested_deadline_missed_status (DDS_RequestedDeadlineMissedStatus &status)=0
	<<cert>> Accesses the DDS_REQUESTED_DEADLINE_MISSED_STATUS communication status.
virtual DDS_ReturnCode_t	get_requested_incompatible_qos_status (DDS_RequestedIncompatibleQosStatus &status)=0
	<<cert>> Accesses the DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS communication status.
virtual DDS_ReturnCode_t	get_instance_replaced_missed_status (DDS_DataReaderInstanceReplacedStatus &status)=0
	<<cert>> Accesses the DDS_INSTANCE_REPLACED_STATUS communication status.
Public Member Functions inherited from DDSEntity
DDS_ReturnCode_t	enable ()
	<<cert>> Enables the DDSEntity.
DDSStatusCondition *	get_statuscondition ()
	<<cert>> Return the DDSStatusCondition associated with a particular DDSEntity.
DDS_StatusMask	get_status_changes ()
	<<cert>> Retrieves the list of communication statuses in the DDSEntity that are triggered.
DDS_InstanceHandle_t	get_instance_handle ()
	<<cert>> Allows access to the DDS_InstanceHandle_t associated with the DDSEntity.

Detailed Description

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

QoS:: DDS_DataReaderQos

Status:: DDS_DATA_AVAILABLE_STATUS;
DDS_LIVELINESS_CHANGED_STATUS, DDS_LivelinessChangedStatus;
DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS, DDS_RequestedIncompatibleQosStatus;
DDS_SUBSCRIPTION_MATCHED_STATUS, DDS_SubscriptionMatchedStatus;
DDS_INSTANCE_REPLACED_STATUS, DDS_DataReaderInstanceReplacedStatus;

Listener:: DDSDataReaderListener

A DDSDataReader refers to exactly one DDSTopicDescription (a DDSTopic) 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.

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

The base-class operations DDSDataReader::set_qos, DDSDataReader::get_qos, DDSDataReader::set_listener, DDSDataReader::get_listener, and DDSEntity::enable

Member Function Documentation

virtual DDSEntity* DDSDataReader::as_entity ( )

pure virtual

<<cert>> Accesses the DDSDataReader's supertype instance.

virtual DDSTopicDescription* DDSDataReader::get_topicdescription ( )

pure virtual

<<cert>> Returns the DDSTopicDescription associated with the DDSDataReader.

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

Returns:: DDSTopicDescription associated with the DDSDataReader.

virtual DDSSubscriber* DDSDataReader::get_subscriber ( )

pure virtual

<<cert>> Returns the DDSSubscriber to which the DDSDataReader belongs.

Returns:: DDSSubscriber to which the DDSDataReader belongs.

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

pure virtual

Sets the reader QoS.

This operation modifies the QoS of the DDSDataReader.

The DDS_DataReaderQos::deadline

can be changed. The other policies are immutable.

Parameters:

qos <<in>> The DDS_DataReaderQos to be set to. Policies must be consistent. Policies cannot be changed after DDSDataReader is enabled. The special value DDS_DATAREADER_QOS_DEFAULT can be used to indicate that the QoS of the DDSDataReader should be changed to match the current default DDS_DataReaderQos set in the DDSSubscriber.

Returns:: One of the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY, or DDS_RETCODE_INCONSISTENT_POLICY.

See also:: DDS_DataReaderQos for rules on consistency among QoS; set_qos (abstract); DDSDataReader::set_qos

virtual DDS_ReturnCode_t DDSDataReader::get_qos ( DDS_DataReaderQos & qos )

pure virtual

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.

Returns:: One of the Standard Return Codes

See also:: get_qos (abstract)

virtual DDS_ReturnCode_t DDSDataReader::set_listener	(	const DDSDataReaderListener *	listener,
		DDS_StatusMask	mask
	)

pure virtual

Sets the reader listener.

Parameters:

listener	<<in>> DDSDataReaderListener to set to
mask	<<in>> DDS_StatusMask associated with the DDSDataReaderListener.

Returns:: One of the Standard Return Codes

See also:: set_listener (abstract)

virtual DDSDataReaderListener* DDSDataReader::get_listener ( )

pure virtual

Get the reader listener.

Returns:: DDSDataReaderListener of the DDSDataReader.

virtual DDS_ReturnCode_t DDSDataReader::read_untyped	(	DDS_UntypedSampleSeq *	received_data,
		DDS_SampleInfoSeq &	info_seq,
		DDS_Long	max_samples,
		DDS_SampleStateMask	sample_states,
		DDS_ViewStateMask	view_states,
		DDS_InstanceStateMask	instance_states
	)

pure virtual

<<cert>> Access a collection of data samples from the DDSDataReader.

This operation offers the same functionality and API as DDSDataReader::take_untyped 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 DDSDataReader::take_untyped() 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.

Important: If the samples "returned" by this method are loaned from RTI Connext DDS Micro (see DDSDataReader::take_untyped 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 untyped pointer where the received data samples will be returned. Must be a valid non-NULL pointer. The method will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
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.
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.

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

See also:: DDSDataReader::take_untyped,; DDS_LENGTH_UNLIMITED

virtual DDS_ReturnCode_t DDSDataReader::take_untyped	(	DDS_UntypedSampleSeq *	received_data,
		DDS_SampleInfoSeq &	info_seq,
		DDS_Long	max_samples,
		DDS_SampleStateMask	sample_states,
		DDS_ViewStateMask	view_states,
		DDS_InstanceStateMask	instance_states
	)

pure virtual

<<cert>> Access a collection of data-samples from the DDSDataReader.

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

This operation may fail with DDS_RETCODE_ERROR if 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 per instance.

The maximum number of samples returned is limited by DDS_ResourceLimitsQosPolicy::max_samples.

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 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 insuffificient 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 DDS Micro 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 DDSDataReader::take_untyped completes, received_data and info_seq will be of the same length and contain the received data.

If the sequences are empty (maximum size equal 0) when the DDSDataReader::take_untyped 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 DDSDataReader::return_loan_untyped operation.

Note: While you must call DDSDataReader::return_loan_untyped at some point, you do not have to do so before the next DDSDataReader::take_untyped 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 0) when the DDSDataReader::take_untyped is called, samples are copied to received_data and info_seq. The application will not need to call FooDataReader::return_loan.

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.

SEQUENCES USAGE IN TAKE AND READ

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 DDSDataReader::return_loan_untyped to return the loan once it is no longer using the received_data in the collection. When DDSDataReader::return_loan_untyped 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 DDSDataReader::return_loan_untyped, 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 . If the DDSDataReader has no samples that meet the constraints, the operations fails with DDS_RETCODE_NO_DATA.

Parameters:

received_data <<inout>> User data untyped pointer where the received data samples will be returned.

Parameters:

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

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

See also:: DDSDataReader::read_untyped

virtual DDS_ReturnCode_t DDSDataReader::read_instance_untyped	(	DDS_UntypedSampleSeq *	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

<<cert>> Access a collection of data samples from the DDSDataReader, all of which belong to the same instance .

Parameters:

received_data	<<inout>> User data untyped pointer where the received data samples will be returned. Must be a valid non-NULL pointer. The method will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
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.
a_handle	<<in>> Instance for which data samples should be read
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.

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

See also:: DDSDataReader::read_untyped,; DDS_LENGTH_UNLIMITED

virtual DDS_ReturnCode_t DDSDataReader::take_instance_untyped	(	DDS_UntypedSampleSeq *	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

<<cert>> Access a collection of data samples from the DDSDataReader, all of which belong to the same instance .

Parameters:

received_data	<<inout>> User data untyped pointer where the received data samples will be returned. Must be a valid non-NULL pointer. The method will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
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.
a_handle	<<in>> Instance for which data samples should be read
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.

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

See also:: DDSDataReader::take_untyped,; DDS_LENGTH_UNLIMITED

virtual DDS_ReturnCode_t DDSDataReader::read_next_sample_untyped	(	void *	received_data,
		DDS_SampleInfo &	sample_info
	)

pure virtual

<<cert>> 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 DDSDataReader::read_untyped operation.

The DDSDataReader::read_next_sample_untyped operation is semantically equivalent to the DDSDataReader::read_untyped 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 DDSDataReader::read_next_sample_untyped 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.

Parameters:

received_data	<<inout>> user data type-specific data 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.

Returns:: One of the Standard Return Codes, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.

See also:: DDSDataReader::read_untyped

virtual DDS_ReturnCode_t DDSDataReader::take_next_sample_untyped	(	void *	received_data,
		DDS_SampleInfo &	sample_info
	)

pure virtual

<<cert>> 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 DDSDataReader::read_next_sample_untyped except for the fact that the sample is removed from the DDSDataReader.

The DDSDataReader::take_next_sample_untyped operation is semantically equivalent to the DDSDataReader::take_untyped 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 DDSDataReader::take_next_sample_untyped 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.

Parameters:

received_data	<<inout>> user data type-specific Data 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.

Returns:: One of the Standard Return Codes, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.

See also:: DDSDataReader::take_untyped

virtual DDS_InstanceHandle_t DDSDataReader::lookup_instance_untyped ( const void * key_holder )

pure virtual

<<cert>> Retrieve the DDS_InstanceHandle_t identifying a specific instance.

Parameters:

key_holder <<in>> A data sample containing the desired values for key attributes.

Returns:: The DDS_InstanceHandle_t for the selected instance or DDS_HANDLE_NIL if the instance was not found or an error occurred.

virtual DDS_ReturnCode_t DDSDataReader::is_data_consistent_untyped	(	DDS_Boolean &	is_data_consistent,
		const void *	sample,
		const DDS_SampleInfo &	sample_info
	)

pure virtual

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.

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

Returns:: One of the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET.

virtual DDS_ReturnCode_t DDSDataReader::return_loan_untyped	(	DDS_UntypedSampleSeq *	received_data,
		DDS_SampleInfoSeq &	info_seq
	)

pure virtual

<<cert>> 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 DDSDataReader::return_loan_untyped 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 DDSDataReader::return_loan_untyped 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 DDSDataReader::return_loan_untyped 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 DDSDataReader::return_loan_untyped, the collections will have max_len=0.

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.

Returns:: One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_NOT_ENABLED.

virtual DDS_ReturnCode_t DDSDataReader::get_subscription_matched_status ( DDS_SubscriptionMatchedStatus & status )

pure virtual

<<cert>> Accesses the DDS_SUBSCRIPTION_MATCHED_STATUS communication status.

Parameters:

status <<inout>> DDS_SubscriptionMatchedStatus to be filled in.

Returns:: One of the Standard Return Codes

virtual DDS_ReturnCode_t DDSDataReader::get_liveliness_changed_status ( DDS_LivelinessChangedStatus & status )

pure virtual

<<cert>> Accesses the DDS_LIVELINESS_CHANGED_STATUS communication status.

Parameters:

status <<inout>> DDS_LivelinessChangedStatus to be filled in.

Returns:: One of the Standard Return Codes

virtual DDS_ReturnCode_t DDSDataReader::get_sample_rejected_status ( DDS_SampleRejectedStatus & status )

pure virtual

<<cert>> Accesses the DDS_SAMPLE_REJECTED_STATUS communication status.

Parameters:

status <<inout>> DDS_SampleRejectedStatus to be filled in.

Returns:: One of the Standard Return Codes

virtual DDS_ReturnCode_t DDSDataReader::get_sample_lost_status ( DDS_SampleLostStatus & status )

pure virtual

<<cert>> Accesses the DDS_SAMPLE_LOST_STATUS communication status.

Parameters:

status <<inout>> DDS_SampleLostStatus to be filled in.

Returns:: One of the Standard Return Codes

virtual DDS_ReturnCode_t DDSDataReader::get_requested_deadline_missed_status ( DDS_RequestedDeadlineMissedStatus & status )

pure virtual

<<cert>> Accesses the DDS_REQUESTED_DEADLINE_MISSED_STATUS communication status.

Parameters:

status <<inout>> DDS_RequestedDeadlineMissedStatus to be filled in.

Returns:: One of the Standard Return Codes

virtual DDS_ReturnCode_t DDSDataReader::get_requested_incompatible_qos_status ( DDS_RequestedIncompatibleQosStatus & status )

pure virtual

<<cert>> Accesses the DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS communication status.

Parameters:

status <<inout>> DDS_RequestedIncompatibleQosStatus to be filled in.

Returns:: One of the Standard Return Codes

virtual DDS_ReturnCode_t DDSDataReader::get_instance_replaced_missed_status ( DDS_DataReaderInstanceReplacedStatus & status )

pure virtual

<<cert>> Accesses the DDS_INSTANCE_REPLACED_STATUS communication status.

Parameters:

status <<inout>> DDS_DataReaderInstanceReplacedStatus to be filled in.

Returns:: One of the Standard Return Codes

Public Member Functions

Detailed Description

Member Function Documentation

SEQUENCES USAGE IN TAKE AND READ