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

Inheritance diagram for FooDataReader:

Public Member Functions
void	read (FooSeq received_data, SampleInfoSeq info_seq, int max_samples, int sample_states, int view_states, int instance_states)
	Access a collection of data samples from the com.rti.dds.subscription.DataReader.

void	take (FooSeq received_data, SampleInfoSeq info_seq, int max_samples, int sample_states, int view_states, int instance_states)
	Access a collection of data-samples from the com.rti.dds.subscription.DataReader.

void	read_w_condition (FooSeq received_data, SampleInfoSeq info_seq, int max_samples, ReadCondition condition)
	Accesses via com.rti.ndds.example.FooDataReader.read the samples that match the criteria specified in the com.rti.dds.subscription.ReadCondition.

void	take_w_condition (FooSeq received_data, SampleInfoSeq info_seq, int max_samples, ReadCondition condition)
	Analogous to com.rti.ndds.example.FooDataReader.read_w_condition except it accesses samples via the com.rti.ndds.example.FooDataReader.take operation.

void	read_next_sample (Foo received_data, SampleInfo sample_info)
	Copies the next not-previously-accessed data value from the com.rti.dds.subscription.DataReader.

void	take_next_sample (Foo received_data, SampleInfo sample_info)
	Copies the next not-previously-accessed data value from the com.rti.dds.subscription.DataReader.

void	read_instance (FooSeq received_data, SampleInfoSeq info_seq, int max_samples, InstanceHandle_t a_handle, int sample_states, int view_states, int instance_states)
	Access a collection of data samples from the com.rti.dds.subscription.DataReader.

void	take_instance (FooSeq received_data, SampleInfoSeq info_seq, int max_samples, InstanceHandle_t a_handle, int sample_states, int view_states, int instance_states)
	Access a collection of data samples from the com.rti.dds.subscription.DataReader.

void	read_next_instance (FooSeq received_data, SampleInfoSeq info_seq, int max_samples, InstanceHandle_t previous_handle, int sample_states, int view_states, int instance_states)
	Access a collection of data samples from the com.rti.dds.subscription.DataReader.

void	take_next_instance (FooSeq received_data, SampleInfoSeq info_seq, int max_samples, InstanceHandle_t previous_handle, int sample_states, int view_states, int instance_states)
	Access a collection of data samples from the com.rti.dds.subscription.DataReader.

void	read_next_instance_w_condition (FooSeq received_data, SampleInfoSeq info_seq, int max_samples, InstanceHandle_t previous_handle, ReadCondition condition)
	Accesses via com.rti.ndds.example.FooDataReader.read_next_instance the samples that match the criteria specified in the com.rti.dds.subscription.ReadCondition.

void	take_next_instance_w_condition (FooSeq received_data, SampleInfoSeq info_seq, int max_samples, InstanceHandle_t previous_handle, ReadCondition condition)
	Accesses via com.rti.ndds.example.FooDataReader.take_next_instance the samples that match the criteria specified in the com.rti.dds.subscription.ReadCondition.

void	return_loan (FooSeq received_data, SampleInfoSeq info_seq)
	Indicates to the com.rti.dds.subscription.DataReader 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 com.rti.dds.subscription.DataReader.

void	get_key_value (Foo key_holder, InstanceHandle_t handle)
	Retrieve the instance `key` that corresponds to an instance `handle`.

InstanceHandle_t	lookup_instance (Foo key_holder)
	Retrieves the instance `handle` that corresponds to an instance `key_holder`.

Public Member Functions inherited from DataReader
ReadCondition	create_readcondition (int sample_states, int view_states, int instance_states)
	Creates a com.rti.dds.subscription.ReadCondition.

QueryCondition	create_querycondition (int sample_states, int view_states, int instance_states, String query_expression, StringSeq query_parameters)
	Creates a com.rti.dds.subscription.QueryCondition.

void	delete_readcondition (ReadCondition condition)
	Deletes a com.rti.dds.subscription.ReadCondition or com.rti.dds.subscription.QueryCondition attached to the com.rti.dds.subscription.DataReader.

void	set_qos (DataReaderQos qos)
	Sets the reader QoS.

void	set_qos_with_profile (String library_name, String profile_name)
	<<eXtension>> Change the QoS of this reader using the input XML QoS profile.

void	get_qos (DataReaderQos qos)
	Gets the reader QoS.

void	set_listener (DataReaderListener l, int mask)
	Sets the reader listener.

DataReaderListener	get_listener ()
	Get the reader listener.

void	call_listenerT (int mask)
	Calls the reader listener.

void	get_sample_rejected_status (SampleRejectedStatus status)
	Accesses the com.rti.dds.infrastructure.StatusKind.StatusKind.SAMPLE_REJECTED_STATUS communication status.

void	get_liveliness_changed_status (LivelinessChangedStatus status)
	Accesses the com.rti.dds.infrastructure.StatusKind.StatusKind.LIVELINESS_CHANGED_STATUS communication status.

void	get_requested_deadline_missed_status (RequestedDeadlineMissedStatus status)
	Accesses the com.rti.dds.infrastructure.StatusKind.StatusKind.REQUESTED_DEADLINE_MISSED_STATUS communication status.

void	get_requested_incompatible_qos_status (RequestedIncompatibleQosStatus status)
	Accesses the com.rti.dds.infrastructure.StatusKind.StatusKind.REQUESTED_INCOMPATIBLE_QOS_STATUS communication status.

void	get_sample_lost_status (SampleLostStatus status)
	Accesses the com.rti.dds.infrastructure.StatusKind.StatusKind.SAMPLE_LOST_STATUS_STATUS communication status.

void	get_subscription_matched_status (SubscriptionMatchedStatus status)
	Accesses the com.rti.dds.infrastructure.StatusKind.StatusKind.SUBSCRIPTION_MATCHED_STATUS communication status.

void	get_datareader_cache_status (DataReaderCacheStatus status)
	<<eXtension>> Get the datareader cache status for this reader.

void	get_datareader_protocol_status (DataReaderProtocolStatus status)
	<<eXtension>> Get the datareader protocol status for this reader.

void	get_matched_publication_datareader_protocol_status (DataReaderProtocolStatus status, InstanceHandle_t publication_handle)
	<<eXtension>> Get the datareader protocol status for this reader, per matched publication identified by the publication_handle.

void	get_matched_publications (InstanceHandleSeq publication_handles)
	Retrieve the list of publications currently "associated" with this com.rti.dds.subscription.DataReader.

void	get_matched_publication_data (PublicationBuiltinTopicData publication_data, InstanceHandle_t publication_handle)
	This operation retrieves the information on a publication that is currently "associated" with the com.rti.dds.subscription.DataReader.

TopicDescription	get_topicdescription ()
	Returns the com.rti.dds.topic.TopicDescription associated with the com.rti.dds.subscription.DataReader.

Subscriber	get_subscriber ()
	Returns the com.rti.dds.subscription.Subscriber to which the com.rti.dds.subscription.DataReader belongs.

void	delete_contained_entities ()
	Deletes all the entities that were created by means of the "create" operations on the com.rti.dds.subscription.DataReader.

void	wait_for_historical_data (Duration_t max_wait)
	Waits until all "historical" data is received for com.rti.dds.subscription.DataReader entities that have a non-VOLATILE Durability Qos kind.

void	acknowledge_sample (SampleInfo sample_info)
	Acknowledge a single sample explicitly.

void	acknowledge_all ()
	Acknowledge all previously accessed samples.

void	acknowledge_sample (SampleInfo sample_info, AckResponseData_t response_data)
	[Not supported.] Acknowledge a single sample explicitly

void	acknowledge_all (AckResponseData_t response_data)
	[Not supported.] Acknowledge all previously accessed samples

void	read_untyped (List received_data, SampleInfoSeq info_seq, int max_samples, int sample_states, int view_states, int instance_states)
	Read data samples, if any are available.

void	take_untyped (List received_data, SampleInfoSeq info_seq, int max_samples, int sample_states, int view_states, int instance_states)
	Take data samples, if any are available.

void	read_w_condition_untyped (List received_data, SampleInfoSeq info_seq, int max_samples, ReadCondition read_condition)
	Read data samples, if any are available.

void	take_w_condition_untyped (List received_data, SampleInfoSeq info_seq, int max_samples, ReadCondition read_condition)
	Take data samples, if any are available.

void	read_next_sample_untyped (Object received_data, SampleInfo sample_info)
	Read data samples, if any are available.

void	take_next_sample_untyped (Object received_data, SampleInfo sample_info)
	Take data samples, if any are available.

void	read_instance_untyped (List received_data, SampleInfoSeq info_seq, int max_samples, InstanceHandle_t a_handle, int sample_states, int view_states, int instance_states)
	Read data samples, if any are available.

void	take_instance_untyped (List received_data, SampleInfoSeq info_seq, int max_samples, InstanceHandle_t a_handle, int sample_states, int view_states, int instance_states)
	Take data samples, if any are available.

void	read_instance_w_condition_untyped (List received_data, SampleInfoSeq info_seq, int max_samples, InstanceHandle_t a_handle, ReadCondition read_condition)
	Read data samples, if any are available.

void	take_instance_w_condition_untyped (List received_data, SampleInfoSeq info_seq, int max_samples, InstanceHandle_t a_handle, ReadCondition read_condition)
	Take data samples, if any are available.

void	read_next_instance_untyped (List received_data, SampleInfoSeq info_seq, int max_samples, InstanceHandle_t a_handle, int sample_states, int view_states, int instance_states)
	Read data samples, if any are available.

void	take_next_instance_untyped (List received_data, SampleInfoSeq info_seq, int max_samples, InstanceHandle_t a_handle, int sample_states, int view_states, int instance_states)
	Take data samples, if any are available.

void	read_next_instance_w_condition_untyped (List received_data, SampleInfoSeq info_seq, int max_samples, InstanceHandle_t a_handle, ReadCondition read_condition)
	Read data samples, if any are available.

void	take_next_instance_w_condition_untyped (List received_data, SampleInfoSeq info_seq, int max_samples, InstanceHandle_t a_handle, ReadCondition read_condition)
	Take data samples, if any are available.

void	return_loan_untyped (List received_data, SampleInfoSeq info_seq)
	Return loaned sample data and meta-data.

void	get_key_value_untyped (Object key_holder, InstanceHandle_t handle)
	Fill in the key fields of the given data sample.

InstanceHandle_t	lookup_instance_untyped (Object key_value)

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: com.rti.dds.subscription.DataReader; com.rti.ndds.example.Foo; com.rti.ndds.example.FooDataWriter; rtiddsgen

Member Function Documentation

void read	(	FooSeq	received_data,
		SampleInfoSeq	info_seq,
		int	max_samples,
		int	sample_states,
		int	view_states,
		int	instance_states
	)

Access a collection of data samples from the com.rti.dds.subscription.DataReader.

This operation offers the same functionality and API as com.rti.ndds.example.FooDataReader.take except that the samples returned remain in the com.rti.dds.subscription.DataReader such that they can be retrieved again by means of a read or take operation.

Please refer to the documentation of com.rti.ndds.example.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 com.rti.dds.subscription.SampleStateKind.SampleStateKind.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 com.rti.dds.subscription.ViewStateKind.ViewStateKind.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 (see com.rti.ndds.example.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 com.rti.dds.infrastructure.com.rti.dds.util.Sequence object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
info_seq	<<inout>> A com.rti.dds.subscription.SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL com.rti.dds.subscription.SampleInfoSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
max_samples	<<in>> The maximum number of samples to be returned. If the special value com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for com.rti.ndds.example.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, com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET, com.rti.dds.infrastructure.RETCODE_NO_DATA or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

See Also: com.rti.ndds.example.FooDataReader.read_w_condition, com.rti.ndds.example.FooDataReader.take, com.rti.ndds.example.FooDataReader.take_w_condition; com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED

void take	(	FooSeq	received_data,
		SampleInfoSeq	info_seq,
		int	max_samples,
		int	sample_states,
		int	view_states,
		int	instance_states
	)

Access a collection of data-samples from the com.rti.dds.subscription.DataReader.

The operation will return the list of samples received by the com.rti.dds.subscription.DataReader since the last com.rti.ndds.example.FooDataReader.take operation that match the specified com.rti.dds.subscription.SampleStateMask, com.rti.dds.subscription.ViewStateMask and com.rti.dds.subscription.InstanceStateMask.

This operation may fail with com.rti.dds.infrastructure.RETCODE_ERROR if com.rti.dds.infrastructure.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 com.rti.dds.infrastructure.HistoryQosPolicy, com.rti.dds.infrastructure.ResourceLimitsQosPolicy, com.rti.dds.infrastructure.DataReaderResourceLimitsQosPolicy and the characteristics of the data-type that is associated with the com.rti.dds.subscription.DataReader:

In the case where the com.rti.dds.infrastructure.HistoryQosPolicy.kind is com.rti.dds.infrastructure.HistoryQosPolicyKind.HistoryQosPolicyKind.KEEP_LAST_HISTORY_QOS, the call will return at most com.rti.dds.infrastructure.HistoryQosPolicy.depth samples per instance.

The maximum number of samples returned is limited by com.rti.dds.infrastructure.ResourceLimitsQosPolicy.max_samples, and by com.rti.dds.infrastructure.DataReaderResourceLimitsQosPolicy.max_samples_per_read.

For multiple instances, the number of samples returned is additionally limited by the product (com.rti.dds.infrastructure.ResourceLimitsQosPolicy.max_samples_per_instance * com.rti.dds.infrastructure.ResourceLimitsQosPolicy.max_instances)

If com.rti.dds.infrastructure.DataReaderResourceLimitsQosPolicy.max_infos is limited, the number of samples returned may also be limited if insufficient com.rti.dds.subscription.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 com.rti.dds.subscription.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 com.rti.dds.topic.Topic associated with the com.rti.dds.subscription.DataReader is bound to a data-type that has no key definition, then there will be at most one instance in the com.rti.dds.subscription.DataReader. 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 com.rti.dds.subscription.ViewStateKind.ViewStateKind.NOT_NEW_VIEW_STATE. It will not affect the instance_state of the sample's instance.

After com.rti.ndds.example.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 com.rti.ndds.example.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 com.rti.dds.subscription.DataReader. 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 com.rti.dds.subscription.DataReader by calling the com.rti.ndds.example.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 com.rti.dds.subscription.SampleInfo objects after the call to com.rti.ndds.example.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 com.rti.ndds.example.FooDataReader.return_loan at some point, you do not have to do so before the next com.rti.ndds.example.FooDataReader.take call. However, failure to return the loan will eventually deplete the com.rti.dds.subscription.DataReader 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 com.rti.dds.subscription.DataReader is specified by the com.rti.dds.infrastructure.ResourceLimitsQosPolicy and the com.rti.dds.infrastructure.DataReaderResourceLimitsQosPolicy.

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

The order of the samples returned to the caller depends on the com.rti.dds.infrastructure.PresentationQosPolicy.

If com.rti.dds.infrastructure.PresentationQosPolicy.access_scope is com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.INSTANCE_PRESENTATION_QOS, the returned collection is a list where samples belonging to the same data instance are consecutive.

If com.rti.dds.infrastructure.PresentationQosPolicy.access_scope is com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.TOPIC_PRESENTATION_QOS and com.rti.dds.infrastructure.PresentationQosPolicy.ordered_access is set to com.rti.dds.infrastructure.false, then returned collection is a list where samples belonging to the same data instance are consecutive.

If com.rti.dds.infrastructure.PresentationQosPolicy.access_scope is com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.TOPIC_PRESENTATION_QOS and com.rti.dds.infrastructure.PresentationQosPolicy.ordered_access is set to com.rti.dds.infrastructure.true, then the returned collection is a list were the relative order of samples is preserved also accross different instances. Note that samples belonging to the same instance may or may not be consecutive. This is because to preserve order it may be necessary to mix samples from different instances.

If com.rti.dds.infrastructure.PresentationQosPolicy.access_scope is com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.GROUP_PRESENTATION_QOS and com.rti.dds.infrastructure.PresentationQosPolicy.ordered_access is set to com.rti.dds.infrastructure.false, then returned collection is a list where samples belonging to the same data instance are consecutive. [Not supported (optional)]

If com.rti.dds.infrastructure.PresentationQosPolicy.access_scope is com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.GROUP_PRESENTATION_QOS and com.rti.dds.infrastructure.PresentationQosPolicy.ordered_access is set to com.rti.dds.infrastructure.true, then the returned collection contains at most one sample. The difference in this case is due to the fact that is required that the application is able to read samples belonging to different com.rti.dds.subscription.DataReader objects in a specific order. [Not supported (optional)]

In any case, the relative order between the samples of one instance is consistent with the DESTINATION_ORDER policy:

If com.rti.dds.infrastructure.DestinationOrderQosPolicy.kind is com.rti.dds.infrastructure.DestinationOrderQosPolicyKind.DestinationOrderQosPolicyKind.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 com.rti.dds.infrastructure.DestinationOrderQosPolicy.kind is com.rti.dds.infrastructure.DestinationOrderQosPolicyKind.DestinationOrderQosPolicyKind.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 com.rti.dds.subscription.DataReader has no samples that meet the constraints, the method will fail with com.rti.dds.infrastructure.RETCODE_NO_DATA.

In addition to the collection of samples, the read and take operations also use a collection of com.rti.dds.subscription.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:

the current-length (len, see com.rti.dds.infrastructure.com.rti.dds.util.Sequence.Sequence.size())
the maximum length (max_len, see com.rti.dds.infrastructure.com.rti.dds.util.Sequence.Sequence.getMaximum)

The initial values of the 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 len and max_len properties for the two collections must be identical. Otherwise read/take will fail with com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.
On successful output, the values of 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 com.rti.dds.subscription.DataReader. On output, 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 com.rti.dds.publication.DataWriter using com.rti.ndds.example.FooDataReader.return_loan.
If the initial max_len>0 then the read or take operation will fail with com.rti.dds.infrastructure.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 then the read or take operation will copy the received_data values and com.rti.dds.subscription.SampleInfo values into the elements already inside the collections. On output, 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 com.rti.dds.infrastructure.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 com.rti.dds.subscription.DataReader, 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 com.rti.dds.subscription.DataReader. If this is the case, the application will need to use com.rti.ndds.example.FooDataReader.return_loan to return the loan once it is no longer using the received_data in the collection. When com.rti.ndds.example.FooDataReader.return_loan completes, the collection will have 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 However, in many cases it may be simpler to always call com.rti.ndds.example.FooDataReader.return_loan, as this operation is harmless (i.e., it leaves all elements unchanged) if the collection does not have a loan.

On output, the collection of com.rti.ndds.example.Foo values and the collection of com.rti.dds.subscription.SampleInfo structures are of the same length and are in a one-to-one correspondence. Each com.rti.dds.subscription.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 com.rti.dds.subscription.SampleInfo is com.rti.dds.subscription.InstanceStateKind.InstanceStateKind.NOT_ALIVE_DISPOSED_INSTANCE_STATE or com.rti.dds.subscription.InstanceStateKind.InstanceStateKind.NOT_ALIVE_NO_WRITERS_INSTANCE_STATE, then the last sample for that instance in the collection (that is, the one whose com.rti.dds.subscription.SampleInfo has sample_rank==0) does not contain valid data.

Samples that contain no data do not count towards the limits imposed by the com.rti.dds.infrastructure.ResourceLimitsQosPolicy. The act of reading/taking a sample sets its sample_state to com.rti.dds.subscription.SampleStateKind.SampleStateKind.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 com.rti.dds.subscription.ViewStateKind.ViewStateKind.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 (com.rti.ndds.example.Foo). If the com.rti.dds.subscription.DataReader has no samples that meet the constraints, the operations fails with com.rti.dds.infrastructure.RETCODE_NO_DATA.

For an example on how take can be used, please refer to the receive example.

Parameters

received_data <<inout>> User data type-specific com.rti.dds.infrastructure.com.rti.dds.util.Sequence object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.

Parameters

info_seq	<<inout>> A com.rti.dds.subscription.SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL com.rti.dds.subscription.SampleInfoSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
max_samples	<<in>> The maximum number of samples to be returned. If the special value com.rti.dds.infrastructure.ResourceLimitsQosPolicy.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, com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET, com.rti.dds.infrastructure.RETCODE_NO_DATA or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

See Also: com.rti.ndds.example.FooDataReader.read; com.rti.ndds.example.FooDataReader.read_w_condition, com.rti.ndds.example.FooDataReader.take_w_condition; com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED

void read_w_condition	(	FooSeq	received_data,
		SampleInfoSeq	info_seq,
		int	max_samples,
		ReadCondition	condition
	)

Accesses via com.rti.ndds.example.FooDataReader.read the samples that match the criteria specified in the com.rti.dds.subscription.ReadCondition.

This operation is especially useful in combination with com.rti.dds.subscription.QueryCondition to filter data samples based on the content.

The specified com.rti.dds.subscription.ReadCondition must be attached to the com.rti.dds.subscription.DataReader; otherwise the operation will fail with com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.

In case the com.rti.dds.subscription.ReadCondition is a plain com.rti.dds.subscription.ReadCondition and not the specialized com.rti.dds.subscription.QueryCondition, the operation is equivalent to calling com.rti.ndds.example.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 com.rti.dds.subscription.ReadCondition.

The samples are accessed with the same semantics as com.rti.ndds.example.FooDataReader.read.

If the com.rti.dds.subscription.DataReader has no samples that meet the constraints, the operation will fail with com.rti.dds.infrastructure.RETCODE_NO_DATA.

Parameters

received_data	<<inout>> user data type-specific com.rti.dds.infrastructure.com.rti.dds.util.Sequence object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
info_seq	<<inout>> a com.rti.dds.subscription.SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL com.rti.dds.subscription.SampleInfoSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
max_samples	<<in>> The maximum number of samples to be returned. If the special value com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for com.rti.ndds.example.FooDataReader.take().
condition	<<in>> the com.rti.dds.subscription.ReadCondition to select samples of interest. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET, com.rti.dds.infrastructure.RETCODE_NO_DATA or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

See Also: com.rti.ndds.example.FooDataReader.read; com.rti.ndds.example.FooDataReader.take, com.rti.ndds.example.FooDataReader.take_w_condition; com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED

void take_w_condition	(	FooSeq	received_data,
		SampleInfoSeq	info_seq,
		int	max_samples,
		ReadCondition	condition
	)

Analogous to com.rti.ndds.example.FooDataReader.read_w_condition except it accesses samples via the com.rti.ndds.example.FooDataReader.take operation.

This operation is analogous to com.rti.ndds.example.FooDataReader.read_w_condition except that it accesses samples via the com.rti.ndds.example.FooDataReader.take operation.

The specified com.rti.dds.subscription.ReadCondition must be attached to the com.rti.dds.subscription.DataReader; otherwise the operation will fail with com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.

The samples are accessed with the same semantics as com.rti.ndds.example.FooDataReader.take.

This operation is especially useful in combination with com.rti.dds.subscription.QueryCondition to filter data samples based on the content.

If the com.rti.dds.subscription.DataReader has no samples that meet the constraints, the method will fail with com.rti.dds.infrastructure.RETCODE_NO_DATA.

Parameters

received_data	<<inout>> user data type-specific com.rti.dds.infrastructure.com.rti.dds.util.Sequence object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
info_seq	<<inout>> a com.rti.dds.subscription.SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL com.rti.dds.subscription.SampleInfoSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
max_samples	<<in>> The maximum number of samples to be returned. If the special value com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for com.rti.ndds.example.FooDataReader.take().
condition	<<in>> the com.rti.dds.subscription.ReadCondition to select samples of interest. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET, com.rti.dds.infrastructure.RETCODE_NO_DATA or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

See Also: com.rti.ndds.example.FooDataReader.read_w_condition, com.rti.ndds.example.FooDataReader.read; com.rti.ndds.example.FooDataReader.take; com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED

void read_next_sample	(	Foo	received_data,
		SampleInfo	sample_info
	)

Copies the next not-previously-accessed data value from the com.rti.dds.subscription.DataReader.

This operation copies the next not-previously-accessed data value from the com.rti.dds.subscription.DataReader. This operation also copies the corresponding com.rti.dds.subscription.SampleInfo. The implied order among the samples stored in the com.rti.dds.subscription.DataReader is the same as for the com.rti.ndds.example.FooDataReader.read operation.

The com.rti.ndds.example.FooDataReader.read_next_sample operation is semantically equivalent to the com.rti.ndds.example.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 com.rti.ndds.example.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 com.rti.dds.subscription.DataReader, the operation will fail with com.rti.dds.infrastructure.RETCODE_NO_DATA and nothing is copied.

Parameters

received_data	<<inout>> user data type-specific com.rti.ndds.example.Foo object where the next received data sample will be returned. The received_data must have been fully allocated. Otherwise, this operation may fail. Must be a valid non-NULL Foo. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
sample_info	<<inout>> a com.rti.dds.subscription.SampleInfo object where the next received sample info will be returned. Must be a valid non-NULL com.rti.dds.subscription.SampleInfo. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.

Exceptions

One	of the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_NO_DATA or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

See Also: com.rti.ndds.example.FooDataReader.read

void take_next_sample	(	Foo	received_data,
		SampleInfo	sample_info
	)

Copies the next not-previously-accessed data value from the com.rti.dds.subscription.DataReader.

This operation copies the next not-previously-accessed data value from the com.rti.dds.subscription.DataReader and 'removes' it from the com.rti.dds.subscription.DataReader so that it is no longer accessible. This operation also copies the corresponding com.rti.dds.subscription.SampleInfo. This operation is analogous to the com.rti.ndds.example.FooDataReader.read_next_sample except for the fact that the sample is removed from the com.rti.dds.subscription.DataReader.

The com.rti.ndds.example.FooDataReader.take_next_sample operation is semantically equivalent to the com.rti.ndds.example.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 com.rti.ndds.example.FooDataReader.read_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 com.rti.dds.subscription.DataReader, the operation will fail with com.rti.dds.infrastructure.RETCODE_NO_DATA and nothing is copied.

Parameters

received_data	<<inout>> user data type-specific com.rti.ndds.example.Foo object where the next received data sample will be returned. The received_data must have been fully allocated. Otherwise, this operation may fail. Must be a valid non-NULL Foo. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
sample_info	<<inout>> a com.rti.dds.subscription.SampleInfo object where the next received sample info will be returned. Must be a valid non-NULL com.rti.dds.subscription.SampleInfo. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.

Exceptions

One	of the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_NO_DATA or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

See Also: com.rti.ndds.example.FooDataReader.take

void read_instance	(	FooSeq	received_data,
		SampleInfoSeq	info_seq,
		int	max_samples,
		InstanceHandle_t	a_handle,
		int	sample_states,
		int	view_states,
		int	instance_states
	)

Access a collection of data samples from the com.rti.dds.subscription.DataReader.

This operation accesses a collection of data values from the com.rti.dds.subscription.DataReader. The behavior is identical to com.rti.ndds.example.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 com.rti.dds.subscription.SampleInfo verifies com.rti.dds.subscription.SampleInfo.instance_handle == a_handle.

The com.rti.ndds.example.FooDataReader.read_instance operation is semantically equivalent to the com.rti.ndds.example.FooDataReader.read operation, except in building the collection, the com.rti.dds.subscription.DataReader 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 com.rti.ndds.example.FooDataReader.read_instance operation follows the same rules as the com.rti.ndds.example.FooDataReader.read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to the com.rti.ndds.example.FooDataReader.read, the com.rti.ndds.example.FooDataReader.read_instance operation may 'loan' elements to the output collections, which must then be returned by means of com.rti.ndds.example.FooDataReader.return_loan.

Similar to the com.rti.ndds.example.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 com.rti.dds.subscription.DataReader has no samples that meet the constraints, the method will fail with com.rti.dds.infrastructure.RETCODE_NO_DATA.

This operation may fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if the com.rti.dds.infrastructure.InstanceHandle_t a_handle does not correspond to an existing data-object known to the com.rti.dds.subscription.DataReader.

Parameters

received_data	<<inout>> user data type-specific com.rti.dds.infrastructure.com.rti.dds.util.Sequence object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
info_seq	<<inout>> a com.rti.dds.subscription.SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL com.rti.dds.subscription.SampleInfoSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
max_samples	<<in>> The maximum number of samples to be returned. If the special value com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for com.rti.ndds.example.FooDataReader.take().
a_handle	<<in>> The specified instance to return samples for. Must be a valid non-NULL com.rti.dds.infrastructure.InstanceHandle_t. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if the `handle` does not correspond to an existing data-object known to the com.rti.dds.subscription.DataReader.
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, com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET, com.rti.dds.infrastructure.RETCODE_NO_DATA or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

See Also: com.rti.ndds.example.FooDataReader.read; com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED

void take_instance	(	FooSeq	received_data,
		SampleInfoSeq	info_seq,
		int	max_samples,
		InstanceHandle_t	a_handle,
		int	sample_states,
		int	view_states,
		int	instance_states
	)

Access a collection of data samples from the com.rti.dds.subscription.DataReader.

This operation accesses a collection of data values from the com.rti.dds.subscription.DataReader. The behavior is identical to com.rti.ndds.example.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 com.rti.ndds.example.FooDataReader.take operation, except in building the collection, the com.rti.dds.subscription.DataReader 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 com.rti.ndds.example.FooDataReader.take_instance operation follows the same rules as the com.rti.ndds.example.FooDataReader.read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to the com.rti.ndds.example.FooDataReader.read, the com.rti.ndds.example.FooDataReader.take_instance operation may 'loan' elements to the output collections, which must then be returned by means of com.rti.ndds.example.FooDataReader.return_loan.

Similar to the com.rti.ndds.example.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 com.rti.dds.subscription.DataReader has no samples that meet the constraints, the method fails with com.rti.dds.infrastructure.RETCODE_NO_DATA.

This operation may fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if the com.rti.dds.infrastructure.InstanceHandle_t a_handle does not correspond to an existing data-object known to the com.rti.dds.subscription.DataReader.

Parameters

received_data	<<inout>> user data type-specific com.rti.dds.infrastructure.com.rti.dds.util.Sequence object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
info_seq	<<inout>> a com.rti.dds.subscription.SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL com.rti.dds.subscription.SampleInfoSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
max_samples	<<in>> The maximum number of samples to be returned. If the special value com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for com.rti.ndds.example.FooDataReader.take().
a_handle	<<in>> The specified instance to return samples for. Must be a valid non-NULL com.rti.dds.infrastructure.InstanceHandle_t. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if the `handle` does not correspond to an existing data-object known to the com.rti.dds.subscription.DataReader.
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, com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET, com.rti.dds.infrastructure.RETCODE_NO_DATA or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

See Also: com.rti.ndds.example.FooDataReader.take; com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED

void read_next_instance	(	FooSeq	received_data,
		SampleInfoSeq	info_seq,
		int	max_samples,
		InstanceHandle_t	previous_handle,
		int	sample_states,
		int	view_states,
		int	instance_states
	)

Access a collection of data samples from the com.rti.dds.subscription.DataReader.

This operation accesses a collection of data values from the com.rti.dds.subscription.DataReader where all the samples belong to a single instance. The behavior is similar to com.rti.ndds.example.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 com.rti.dds.subscription.DataReader. For the purposes of the ordering, it should be 'as if' each instance handle was represented as unique integer.

The behavior of com.rti.ndds.example.FooDataReader.read_next_instance is 'as if' the com.rti.dds.subscription.DataReader invoked com.rti.ndds.example.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 com.rti.dds.infrastructure.InstanceHandle_t.InstanceHandle_t.HANDLE_NIL is guaranteed to be 'less than' any valid instance_handle. So the use of the parameter value previous_handle == com.rti.dds.infrastructure.InstanceHandle_t.InstanceHandle_t.HANDLE_NIL will return the samples for the instance which has the smallest instance_handle among all the instances that contain available samples.

The operation com.rti.ndds.example.FooDataReader.read_next_instance is intended to be used in an application-driven iteration, where the application starts by passing previous_handle == com.rti.dds.infrastructure.InstanceHandle_t.InstanceHandle_t.HANDLE_NIL, examines the samples returned, and then uses the instance_handle returned in the com.rti.dds.subscription.SampleInfo as the value of the previous_handle argument to the next call to com.rti.ndds.example.FooDataReader.read_next_instance. The iteration continues until com.rti.ndds.example.FooDataReader.read_next_instance fails with the value com.rti.dds.infrastructure.RETCODE_NO_DATA.

Note that it is possible to call the com.rti.ndds.example.FooDataReader.read_next_instance operation with a previous_handle that does not correspond to an instance currently managed by the com.rti.dds.subscription.DataReader. This is because as stated earlier the 'greater-than' relationship is defined even for handles not managed by the com.rti.dds.subscription.DataReader. One practical situation where this may occur is when an application is iterating though all the instances, takes all the samples of a com.rti.dds.subscription.InstanceStateKind.InstanceStateKind.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 com.rti.ndds.example.FooDataReader.read_next_instance operation follows the same rules as the com.rti.ndds.example.FooDataReader.read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to the com.rti.ndds.example.FooDataReader.read, the com.rti.ndds.example.FooDataReader.read_instance operation may 'loan' elements to the output collections, which must then be returned by means of com.rti.ndds.example.FooDataReader.return_loan.

Similar to the com.rti.ndds.example.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 com.rti.dds.subscription.DataReader has no samples that meet the constraints, the method will fail with com.rti.dds.infrastructure.RETCODE_NO_DATA.

Parameters

received_data	<<inout>> user data type-specific com.rti.dds.infrastructure.com.rti.dds.util.Sequence object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
info_seq	<<inout>> a com.rti.dds.subscription.SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL com.rti.dds.subscription.SampleInfoSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
max_samples	<<in>> The maximum number of samples to be returned. If the special value com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for com.rti.ndds.example.FooDataReader.take().
previous_handle	<<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned. Must be a valid non-NULL com.rti.dds.infrastructure.InstanceHandle_t. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
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, com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET com.rti.dds.infrastructure.RETCODE_NO_DATA or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

See Also: com.rti.ndds.example.FooDataReader.read; com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED

void take_next_instance	(	FooSeq	received_data,
		SampleInfoSeq	info_seq,
		int	max_samples,
		InstanceHandle_t	previous_handle,
		int	sample_states,
		int	view_states,
		int	instance_states
	)

Access a collection of data samples from the com.rti.dds.subscription.DataReader.

This operation accesses a collection of data values from the com.rti.dds.subscription.DataReader and 'removes' them from the com.rti.dds.subscription.DataReader.

This operation has the same behavior as com.rti.ndds.example.FooDataReader.read_next_instance, except that the samples are 'taken' from the com.rti.dds.subscription.DataReader such that they are no longer accessible via subsequent 'read' or 'take' operations.

Similar to the operation com.rti.ndds.example.FooDataReader.read_next_instance, it is possible to call com.rti.ndds.example.FooDataReader.take_next_instance with a previous_handle that does not correspond to an instance currently managed by the com.rti.dds.subscription.DataReader.

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

Similar to the com.rti.ndds.example.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 com.rti.dds.subscription.DataReader has no samples that meet the constraints, the method will fail with com.rti.dds.infrastructure.RETCODE_NO_DATA.

Parameters

received_data	<<inout>> user data type-specific com.rti.dds.infrastructure.com.rti.dds.util.Sequence object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
info_seq	<<inout>> a com.rti.dds.subscription.SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL com.rti.dds.subscription.SampleInfoSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
max_samples	<<in>> The maximum number of samples to be returned. If the special value com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for com.rti.ndds.example.FooDataReader.take().
previous_handle	<<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned. Must be a valid non-NULL com.rti.dds.infrastructure.InstanceHandle_t. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
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, com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET, com.rti.dds.infrastructure.RETCODE_NO_DATA or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

See Also: com.rti.ndds.example.FooDataReader.take; com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED

void read_next_instance_w_condition	(	FooSeq	received_data,
		SampleInfoSeq	info_seq,
		int	max_samples,
		InstanceHandle_t	previous_handle,
		ReadCondition	condition
	)

Accesses via com.rti.ndds.example.FooDataReader.read_next_instance the samples that match the criteria specified in the com.rti.dds.subscription.ReadCondition.

This operation accesses a collection of data values from the com.rti.dds.subscription.DataReader. The behavior is identical to com.rti.ndds.example.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 com.rti.dds.subscription.ReadCondition evaluates to TRUE.

Similar to the operation com.rti.ndds.example.FooDataReader.read_next_instance, it is possible to call com.rti.ndds.example.FooDataReader.read_next_instance_w_condition with a previous_handle that does not correspond to an instance currently managed by the com.rti.dds.subscription.DataReader.

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

Similar to the com.rti.ndds.example.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 com.rti.dds.subscription.DataReader has no samples that meet the constraints, the method will fail with com.rti.dds.infrastructure.RETCODE_NO_DATA.

Parameters

received_data	<<inout>> user data type-specific com.rti.dds.infrastructure.com.rti.dds.util.Sequence object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
info_seq	<<inout>> a com.rti.dds.subscription.SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL com.rti.dds.subscription.SampleInfoSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
max_samples	<<in>> The maximum number of samples to be returned. If the special value com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for com.rti.ndds.example.FooDataReader.take().
previous_handle	<<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned. Must be a valid non-NULL com.rti.dds.infrastructure.InstanceHandle_t. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
condition	<<in>> the com.rti.dds.subscription.ReadCondition to select samples of interest. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET com.rti.dds.infrastructure.RETCODE_NO_DATA or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

See Also: com.rti.ndds.example.FooDataReader.read_next_instance; com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED

void take_next_instance_w_condition	(	FooSeq	received_data,
		SampleInfoSeq	info_seq,
		int	max_samples,
		InstanceHandle_t	previous_handle,
		ReadCondition	condition
	)

Accesses via com.rti.ndds.example.FooDataReader.take_next_instance the samples that match the criteria specified in the com.rti.dds.subscription.ReadCondition.

This operation accesses a collection of data values from the com.rti.dds.subscription.DataReader and 'removes' them from the com.rti.dds.subscription.DataReader.

The operation has the same behavior as com.rti.ndds.example.FooDataReader.read_next_instance_w_condition, except that the samples are 'taken' from the com.rti.dds.subscription.DataReader such that they are no longer accessible via subsequent 'read' or 'take' operations.

Similar to the operation com.rti.ndds.example.FooDataReader.read_next_instance, it is possible to call com.rti.ndds.example.FooDataReader.take_next_instance_w_condition with a previous_handle that does not correspond to an instance currently managed by the com.rti.dds.subscription.DataReader.

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

Similar to the com.rti.ndds.example.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 com.rti.dds.subscription.DataReader has no samples that meet the constraints, the method will fail with com.rti.dds.infrastructure.RETCODE_NO_DATA.

Parameters

received_data	<<inout>> user data type-specific com.rti.dds.infrastructure.com.rti.dds.util.Sequence object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
info_seq	<<inout>> a com.rti.dds.subscription.SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL com.rti.dds.subscription.SampleInfoSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
max_samples	<<in>> The maximum number of samples to be returned. If the special value com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for com.rti.ndds.example.FooDataReader.take().
previous_handle	<<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned. Must be a valid non-NULL com.rti.dds.infrastructure.InstanceHandle_t. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.
condition	<<in>> the com.rti.dds.subscription.ReadCondition to select samples of interest. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET, or com.rti.dds.infrastructure.RETCODE_NO_DATA, com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

See Also: com.rti.ndds.example.FooDataReader.take_next_instance; com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED

void return_loan	(	FooSeq	received_data,
		SampleInfoSeq	info_seq
	)

Indicates to the com.rti.dds.subscription.DataReader 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 com.rti.dds.subscription.DataReader.

This operation indicates to the com.rti.dds.subscription.DataReader 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 com.rti.dds.subscription.DataReader.

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 com.rti.dds.subscription.DataReader to which they are returned. If either of these conditions is not met, the operation will fail with com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.

The operation com.rti.ndds.example.FooDataReader.return_loan allows implementations of the read and take operations to "loan" buffers from the com.rti.dds.subscription.DataReader to the application and in this manner provide "zerocopy" access to the data. During the loan, the com.rti.dds.subscription.DataReader 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 com.rti.dds.subscription.DataReader, the application should not retain them indefinitely.

The use of com.rti.ndds.example.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.

If the collections had a loan, upon completion of com.rti.ndds.example.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 com.rti.dds.infrastructure.com.rti.dds.util.Sequence object where the received data samples was obtained from earlier invocation of read or take on the com.rti.dds.subscription.DataReader. Must be a valid non-NULL FooSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.

Parameters

info_seq <<in>> a com.rti.dds.subscription.SampleInfoSeq object where the received sample info was obtained from earlier invocation of read or take on the com.rti.dds.subscription.DataReader. Must be a valid non-NULL com.rti.dds.subscription.SampleInfoSeq. The method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if it is NULL.

Exceptions

One	of the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

void get_key_value	(	Foo	key_holder,
		InstanceHandle_t	handle
	)

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.

For keyed data types, this operation may fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if the handle does not correspond to an existing data-object known to the com.rti.dds.subscription.DataReader.

Parameters

key_holder <<inout>> a user data type specific key holder, whose key fields are filled by this operation. If com.rti.ndds.example.Foo has no key, this method has no effect. This method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if key_holder is NULL.

handle <<in>> the instance whose key is to be retrieved. If com.rti.ndds.example.Foo has a key, handle must represent an existing instance of type com.rti.ndds.example.Foo known to the com.rti.dds.subscription.DataReader. Otherwise, this method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER. If com.rti.ndds.example.Foo has a key and handle is com.rti.dds.infrastructure.InstanceHandle_t.InstanceHandle_t.HANDLE_NIL, this method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER. If com.rti.ndds.example.Foo has a key and handle represents an instance of another type or an instance of type com.rti.ndds.example.Foo that has been unregistered, this method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER. If com.rti.ndds.example.Foo has no key, this method has no effect. This method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if handle is NULL.

Exceptions

One	of the Standard Return Codes or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

See Also: com.rti.ndds.example.FooDataWriter.get_key_value

InstanceHandle_t lookup_instance ( Foo key_holder )

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. This operation does not register the instance in question. If the instance has not been previously registered, or if for any other reason the Service is unable to provide an instance handle, the Service will return the special value HANDLE_NIL.

Parameters

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

Returns: the instance handle associated with this instance. If com.rti.ndds.example.Foo has no key, this method has no effect and returns com.rti.dds.infrastructure.InstanceHandle_t.InstanceHandle_t.HANDLE_NIL

Public Member Functions

Detailed Description

Member Function Documentation

SEQUENCES USAGE IN TAKE AND READ