Fast DDS  Version 3.1.0
Fast DDS
Loading...
Searching...
No Matches
DataReader Class Reference

Class DataReader, contains the actual implementation of the behaviour of the Subscriber. More...

#include <DataReader.hpp>

Inheritance diagram for DataReader:

Public Member Functions

virtual ~DataReader ()
 Destructor.
 
FASTDDS_EXPORTED_API ReturnCode_t enable () override
 This operation enables the DataReader.
 
FASTDDS_EXPORTED_API bool wait_for_unread_message (const fastdds::dds::Duration_t &timeout)
 Method to block the current thread until an unread message is available.
 
FASTDDS_EXPORTED_API ReturnCode_t wait_for_historical_data (const fastdds::dds::Duration_t &max_wait) const
 NOT YET IMPLEMENTED.
 
FASTDDS_EXPORTED_API ReturnCode_t return_loan (LoanableCollection &data_values, SampleInfoSeq &sample_infos)
 This operation indicates to the DataReader that the application is done accessing the collection of data_values and sample_infos obtained by some earlier invocation of read or take on the DataReader.
 
FASTDDS_EXPORTED_API ReturnCode_t get_key_value (void *key_holder, const InstanceHandle_t &handle)
 NOT YET IMPLEMENTED.
 
FASTDDS_EXPORTED_API InstanceHandle_t lookup_instance (const void *instance) const
 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.
 
FASTDDS_EXPORTED_API ReturnCode_t get_first_untaken_info (SampleInfo *info)
 Returns information about the first untaken sample.
 
FASTDDS_EXPORTED_API uint64_t get_unread_count () const
 Get the number of samples pending to be read.
 
FASTDDS_EXPORTED_API uint64_t get_unread_count (bool mark_as_read) const
 Get the number of samples pending to be read.
 
FASTDDS_EXPORTED_API const fastdds::rtps::GUID_tguid ()
 Get associated GUID.
 
FASTDDS_EXPORTED_API const fastdds::rtps::GUID_tguid () const
 Get associated GUID.
 
FASTDDS_EXPORTED_API InstanceHandle_t get_instance_handle () const
 Getter for the associated InstanceHandle.
 
FASTDDS_EXPORTED_API TypeSupport type ()
 Getter for the data type.
 
FASTDDS_EXPORTED_API const TopicDescriptionget_topicdescription () const
 Get TopicDescription.
 
FASTDDS_EXPORTED_API ReturnCode_t get_requested_deadline_missed_status (RequestedDeadlineMissedStatus &status)
 Get the requested deadline missed status.
 
FASTDDS_EXPORTED_API ReturnCode_t get_requested_incompatible_qos_status (RequestedIncompatibleQosStatus &status)
 Get the requested incompatible qos status.
 
FASTDDS_EXPORTED_API ReturnCode_t set_qos (const DataReaderQos &qos)
 Setter for the DataReaderQos.
 
FASTDDS_EXPORTED_API const DataReaderQosget_qos () const
 Getter for the DataReaderQos.
 
FASTDDS_EXPORTED_API ReturnCode_t get_qos (DataReaderQos &qos) const
 Getter for the DataReaderQos.
 
FASTDDS_EXPORTED_API ReturnCode_t set_listener (DataReaderListener *listener)
 Modifies the DataReaderListener, sets the mask to StatusMask::all().
 
FASTDDS_EXPORTED_API ReturnCode_t set_listener (DataReaderListener *listener, const StatusMask &mask)
 Modifies the DataReaderListener.
 
FASTDDS_EXPORTED_API const DataReaderListenerget_listener () const
 Getter for the DataReaderListener.
 
FASTDDS_EXPORTED_API ReturnCode_t get_liveliness_changed_status (LivelinessChangedStatus &status) const
 Get the liveliness changed status.
 
FASTDDS_EXPORTED_API ReturnCode_t get_sample_lost_status (SampleLostStatus &status) const
 Get the SAMPLE_LOST communication status.
 
FASTDDS_EXPORTED_API ReturnCode_t get_sample_rejected_status (SampleRejectedStatus &status) const
 Get the SAMPLE_REJECTED communication status.
 
FASTDDS_EXPORTED_API ReturnCode_t get_subscription_matched_status (SubscriptionMatchedStatus &status) const
 Returns the subscription matched status.
 
FASTDDS_EXPORTED_API ReturnCode_t get_matched_publication_data (PublicationBuiltinTopicData &publication_data, const fastdds::rtps::InstanceHandle_t &publication_handle) const
 Retrieves in a publication associated with the DataWriter.
 
FASTDDS_EXPORTED_API ReturnCode_t get_matched_publications (std::vector< InstanceHandle_t > &publication_handles) const
 Fills the given vector with the InstanceHandle_t of matched DataReaders.
 
FASTDDS_EXPORTED_API ReadConditioncreate_readcondition (SampleStateMask sample_states, ViewStateMask view_states, InstanceStateMask instance_states)
 This operation creates a ReadCondition.
 
FASTDDS_EXPORTED_API QueryCondition * create_querycondition (SampleStateMask sample_states, ViewStateMask view_states, InstanceStateMask instance_states, const std::string &query_expression, const std::vector< std::string > &query_parameters)
 This operation creates a QueryCondition.
 
FASTDDS_EXPORTED_API ReturnCode_t delete_readcondition (ReadCondition *a_condition)
 This operation deletes a ReadCondition attached to the DataReader.
 
FASTDDS_EXPORTED_API const Subscriberget_subscriber () const
 Getter for the Subscriber.
 
FASTDDS_EXPORTED_API ReturnCode_t delete_contained_entities ()
 This operation deletes all the entities that were created by means of the “create” operations on the DataReader.
 
FASTDDS_EXPORTED_API bool is_sample_valid (const void *data, const SampleInfo *info) const
 Checks whether a loaned sample is still valid or is corrupted.
 
FASTDDS_EXPORTED_API ReturnCode_t get_listening_locators (rtps::LocatorList &locators) const
 Get the list of locators on which this DataReader is listening.
 
FASTDDS_EXPORTED_API ReturnCode_t get_subscription_builtin_topic_data (SubscriptionBuiltinTopicData &subscription_data) const
 Retrieve the subscription data discovery information.
 
Read or take data methods.

Methods to read or take data from the History.

FASTDDS_EXPORTED_API ReturnCode_t read (LoanableCollection &data_values, SampleInfoSeq &sample_infos, int32_t max_samples=LENGTH_UNLIMITED, SampleStateMask sample_states=ANY_SAMPLE_STATE, ViewStateMask view_states=ANY_VIEW_STATE, InstanceStateMask instance_states=ANY_INSTANCE_STATE)
 Access a collection of data samples from the DataReader.
 
FASTDDS_EXPORTED_API ReturnCode_t read_w_condition (LoanableCollection &data_values, SampleInfoSeq &sample_infos, int32_t max_samples, ReadCondition *a_condition)
 This operation accesses via ‘read’ the samples that match the criteria specified in the ReadCondition.
 
FASTDDS_EXPORTED_API ReturnCode_t read_instance (LoanableCollection &data_values, SampleInfoSeq &sample_infos, int32_t max_samples=LENGTH_UNLIMITED, const InstanceHandle_t &a_handle=HANDLE_NIL, SampleStateMask sample_states=ANY_SAMPLE_STATE, ViewStateMask view_states=ANY_VIEW_STATE, InstanceStateMask instance_states=ANY_INSTANCE_STATE)
 Access a collection of data samples from the DataReader.
 
FASTDDS_EXPORTED_API ReturnCode_t read_next_instance (LoanableCollection &data_values, SampleInfoSeq &sample_infos, int32_t max_samples=LENGTH_UNLIMITED, const InstanceHandle_t &previous_handle=HANDLE_NIL, SampleStateMask sample_states=ANY_SAMPLE_STATE, ViewStateMask view_states=ANY_VIEW_STATE, InstanceStateMask instance_states=ANY_INSTANCE_STATE)
 Access a collection of data samples from the DataReader.
 
FASTDDS_EXPORTED_API ReturnCode_t read_next_instance_w_condition (LoanableCollection &data_values, SampleInfoSeq &sample_infos, int32_t max_samples, const InstanceHandle_t &previous_handle, ReadCondition *a_condition)
 This operation accesses a collection of Data values from the DataReader.
 
FASTDDS_EXPORTED_API ReturnCode_t read_next_sample (void *data, SampleInfo *info)
 This operation copies the next, non-previously accessed Data value from the DataReader; the operation also copies the corresponding SampleInfo.
 
FASTDDS_EXPORTED_API ReturnCode_t take (LoanableCollection &data_values, SampleInfoSeq &sample_infos, int32_t max_samples=LENGTH_UNLIMITED, SampleStateMask sample_states=ANY_SAMPLE_STATE, ViewStateMask view_states=ANY_VIEW_STATE, InstanceStateMask instance_states=ANY_INSTANCE_STATE)
 Access a collection of data samples from the DataReader.
 
FASTDDS_EXPORTED_API ReturnCode_t take_w_condition (LoanableCollection &data_values, SampleInfoSeq &sample_infos, int32_t max_samples, ReadCondition *a_condition)
 This operation is analogous to read_w_condition except it accesses samples via the ‘take’ operation.
 
FASTDDS_EXPORTED_API ReturnCode_t take_instance (LoanableCollection &data_values, SampleInfoSeq &sample_infos, int32_t max_samples=LENGTH_UNLIMITED, const InstanceHandle_t &a_handle=HANDLE_NIL, SampleStateMask sample_states=ANY_SAMPLE_STATE, ViewStateMask view_states=ANY_VIEW_STATE, InstanceStateMask instance_states=ANY_INSTANCE_STATE)
 Access a collection of data samples from the DataReader.
 
FASTDDS_EXPORTED_API ReturnCode_t take_next_instance (LoanableCollection &data_values, SampleInfoSeq &sample_infos, int32_t max_samples=LENGTH_UNLIMITED, const InstanceHandle_t &previous_handle=HANDLE_NIL, SampleStateMask sample_states=ANY_SAMPLE_STATE, ViewStateMask view_states=ANY_VIEW_STATE, InstanceStateMask instance_states=ANY_INSTANCE_STATE)
 Access a collection of data samples from the DataReader.
 
FASTDDS_EXPORTED_API ReturnCode_t take_next_instance_w_condition (LoanableCollection &data_values, SampleInfoSeq &sample_infos, int32_t max_samples, const InstanceHandle_t &previous_handle, ReadCondition *a_condition)
 This operation accesses a collection of Data values from the DataReader.
 
FASTDDS_EXPORTED_API ReturnCode_t take_next_sample (void *data, SampleInfo *info)
 This operation copies the next, non-previously accessed Data value from the DataReader and ‘removes’ it from the DataReader so it is no longer accessible.
 
- Public Member Functions inherited from DomainEntity
 DomainEntity (const StatusMask &mask=StatusMask::all())
 Constructor.
 
- Public Member Functions inherited from Entity
FASTDDS_EXPORTED_API Entity (const StatusMask &mask=StatusMask::all())
 Constructor.
 
void close ()
 This operation disables the Entity before closing it.
 
FASTDDS_EXPORTED_API const StatusMaskget_status_mask () const
 Retrieves the set of relevant statuses for the Entity.
 
FASTDDS_EXPORTED_API const StatusMaskget_status_changes () const
 Retrieves the set of triggered statuses in the Entity.
 
const InstanceHandle_tget_instance_handle () const
 Retrieves the instance handler that represents the Entity.
 
FASTDDS_EXPORTED_API bool is_enabled () const
 Checks if the Entity is enabled.
 
FASTDDS_EXPORTED_API bool operator== (const Entity &other) const
 
FASTDDS_EXPORTED_API StatusConditionget_statuscondition ()
 Allows access to the StatusCondition associated with the Entity.
 

Protected Member Functions

 DataReader (DataReaderImpl *impl, const StatusMask &mask=StatusMask::all())
 Create a data reader, assigning its pointer to the associated implementation.
 
 DataReader (Subscriber *s, TopicDescription *topic, const DataReaderQos &qos, DataReaderListener *listener=nullptr, const StatusMask &mask=StatusMask::all())
 
- Protected Member Functions inherited from Entity
FASTDDS_EXPORTED_API void set_instance_handle (const InstanceHandle_t &handle)
 Setter for the Instance Handle.
 

Protected Attributes

DataReaderImplimpl_
 
- Protected Attributes inherited from Entity
StatusMask status_mask_
 StatusMask with relevant statuses set to 1.
 
StatusCondition status_condition_
 Condition associated to the Entity.
 
InstanceHandle_t instance_handle_
 InstanceHandle associated to the Entity.
 
bool enable_
 Boolean that states if the Entity is enabled or disabled.
 

Friends

class DataReaderImpl
 
class SubscriberImpl
 
class ::dds::sub::DataReader
 

Detailed Description

Class DataReader, contains the actual implementation of the behaviour of the Subscriber.

Constructor & Destructor Documentation

◆ DataReader() [1/2]

DataReader ( DataReaderImpl impl,
const StatusMask mask = StatusMask::all() 
)
protected

Create a data reader, assigning its pointer to the associated implementation.

Don't use directly, create DataReader using create_datareader from Subscriber.

◆ DataReader() [2/2]

DataReader ( Subscriber s,
TopicDescription topic,
const DataReaderQos qos,
DataReaderListener listener = nullptr,
const StatusMask mask = StatusMask::all() 
)
protected

◆ ~DataReader()

virtual ~DataReader ( )
virtual

Destructor.

Member Function Documentation

◆ create_querycondition()

FASTDDS_EXPORTED_API QueryCondition * create_querycondition ( SampleStateMask  sample_states,
ViewStateMask  view_states,
InstanceStateMask  instance_states,
const std::string &  query_expression,
const std::vector< std::string > &  query_parameters 
)

This operation creates a QueryCondition.

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

Parameters
[in]sample_statesOnly data samples with sample_state matching one of these will trigger the created condition.
[in]view_statesOnly data samples with view_state matching one of these will trigger the created condition.
[in]instance_statesOnly data samples with instance_state matching one of these will trigger the created condition.
[in]query_expressionOnly data samples matching this query will trigger the created condition.
[in]query_parametersValue of the parameters on the query expression.
Returns
pointer to the created QueryCondition, nullptr in case of error.

◆ create_readcondition()

FASTDDS_EXPORTED_API ReadCondition * create_readcondition ( SampleStateMask  sample_states,
ViewStateMask  view_states,
InstanceStateMask  instance_states 
)

This operation creates a ReadCondition.

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

Parameters
[in]sample_statesOnly data samples with sample_state matching one of these will trigger the created condition.
[in]view_statesOnly data samples with view_state matching one of these will trigger the created condition.
[in]instance_statesOnly data samples with instance_state matching one of these will trigger the created condition.
Returns
pointer to the created ReadCondition, nullptr in case of error.

◆ delete_contained_entities()

FASTDDS_EXPORTED_API ReturnCode_t delete_contained_entities ( )

This operation deletes all the entities that were created by means of the “create” operations on the DataReader.

That is, it deletes all contained ReadCondition and QueryCondition objects.

The operation will return PRECONDITION_NOT_MET if the any of the contained entities is in a state where it cannot be deleted.

Returns
Any of the standard return codes.

◆ delete_readcondition()

FASTDDS_EXPORTED_API ReturnCode_t delete_readcondition ( ReadCondition a_condition)

This operation deletes a ReadCondition attached to the DataReader.

Parameters
a_conditionpointer to a ReadCondition belonging to the DataReader
Returns
RETCODE_OK

◆ enable()

FASTDDS_EXPORTED_API ReturnCode_t enable ( )
overridevirtual

This operation enables the DataReader.

Returns
RETCODE_OK is successfully enabled. RETCODE_PRECONDITION_NOT_MET if the Subscriber creating this DataReader is not enabled.

Reimplemented from Entity.

◆ get_first_untaken_info()

FASTDDS_EXPORTED_API ReturnCode_t get_first_untaken_info ( SampleInfo info)

Returns information about the first untaken sample.

This method is meant to be called prior to a read() or take() operation as it does not modify the status condition of the entity.

Parameters
[out]infoPointer to a SampleInfo_t structure to store first untaken sample information.
Returns
RETCODE_OK if sample info was returned. RETCODE_NO_DATA if there is no sample to take.

◆ get_instance_handle()

FASTDDS_EXPORTED_API InstanceHandle_t get_instance_handle ( ) const

Getter for the associated InstanceHandle.

Returns
Copy of the InstanceHandle

◆ get_key_value()

FASTDDS_EXPORTED_API ReturnCode_t get_key_value ( void *  key_holder,
const InstanceHandle_t handle 
)

NOT YET IMPLEMENTED.

This operation can be used to retrieve the instance key that corresponds to an instance_handle. The operation will only fill the fields that form the key inside the key_holder instance.

This operation may return BAD_PARAMETER if the InstanceHandle_t a_handle does not correspond to an existing data-object known to the DataReader. If the implementation is not able to check invalid handles then the result in this situation is unspecified.

Parameters
[in,out]key_holder
[in]handle
Returns
Any of the standard return codes.
Warning
Not supported yet. Currently returns RETCODE_UNSUPPORTED

◆ get_listener()

FASTDDS_EXPORTED_API const DataReaderListener * get_listener ( ) const

Getter for the DataReaderListener.

Returns
Pointer to the DataReaderListener

◆ get_listening_locators()

FASTDDS_EXPORTED_API ReturnCode_t get_listening_locators ( rtps::LocatorList locators) const

Get the list of locators on which this DataReader is listening.

Parameters
[out]locatorsLocatorList where the list of locators will be stored.
Returns
NOT_ENABLED if the reader has not been enabled.
OK if a list of locators is returned.

◆ get_liveliness_changed_status()

FASTDDS_EXPORTED_API ReturnCode_t get_liveliness_changed_status ( LivelinessChangedStatus status) const

Get the liveliness changed status.

Parameters
[out]statusLivelinessChangedStatus object where the status is returned.
Returns
RETCODE_OK

◆ get_matched_publication_data()

FASTDDS_EXPORTED_API ReturnCode_t get_matched_publication_data ( PublicationBuiltinTopicData publication_data,
const fastdds::rtps::InstanceHandle_t publication_handle 
) const

Retrieves in a publication associated with the DataWriter.

Parameters
[out]publication_datapublication data struct
publication_handleInstanceHandle_t of the publication
Returns
RETCODE_OK
Warning
Not supported yet. Currently returns RETCODE_UNSUPPORTED

◆ get_matched_publications()

FASTDDS_EXPORTED_API ReturnCode_t get_matched_publications ( std::vector< InstanceHandle_t > &  publication_handles) const

Fills the given vector with the InstanceHandle_t of matched DataReaders.

Parameters
[out]publication_handlesVector where the InstanceHandle_t are returned
Returns
RETCODE_OK
Warning
Not supported yet. Currently returns RETCODE_UNSUPPORTED

◆ get_qos() [1/2]

FASTDDS_EXPORTED_API const DataReaderQos & get_qos ( ) const

Getter for the DataReaderQos.

Returns
Pointer to the DataReaderQos.

◆ get_qos() [2/2]

FASTDDS_EXPORTED_API ReturnCode_t get_qos ( DataReaderQos qos) const

Getter for the DataReaderQos.

Parameters
[in]qosDataReaderQos where the qos is returned.
Returns
RETCODE_OK

◆ get_requested_deadline_missed_status()

FASTDDS_EXPORTED_API ReturnCode_t get_requested_deadline_missed_status ( RequestedDeadlineMissedStatus status)

Get the requested deadline missed status.

Returns
The deadline missed status.

◆ get_requested_incompatible_qos_status()

FASTDDS_EXPORTED_API ReturnCode_t get_requested_incompatible_qos_status ( RequestedIncompatibleQosStatus status)

Get the requested incompatible qos status.

Parameters
[out]statusRequested incompatible qos status.
Returns
RETCODE_OK

◆ get_sample_lost_status()

FASTDDS_EXPORTED_API ReturnCode_t get_sample_lost_status ( SampleLostStatus status) const

Get the SAMPLE_LOST communication status.

Parameters
[out]statusSampleLostStatus object where the status is returned.
Returns
RETCODE_OK

◆ get_sample_rejected_status()

FASTDDS_EXPORTED_API ReturnCode_t get_sample_rejected_status ( SampleRejectedStatus status) const

Get the SAMPLE_REJECTED communication status.

Parameters
[out]statusSampleRejectedStatus object where the status is returned.
Returns
RETCODE_OK

◆ get_subscriber()

FASTDDS_EXPORTED_API const Subscriber * get_subscriber ( ) const

Getter for the Subscriber.

Returns
Subscriber pointer

◆ get_subscription_builtin_topic_data()

FASTDDS_EXPORTED_API ReturnCode_t get_subscription_builtin_topic_data ( SubscriptionBuiltinTopicData subscription_data) const

Retrieve the subscription data discovery information.

Parameters
[out]subscription_dataThe subscription data discovery information.
Returns
NOT_ENABLED if the reader has not been enabled.
OK if the subscription data is returned.

◆ get_subscription_matched_status()

FASTDDS_EXPORTED_API ReturnCode_t get_subscription_matched_status ( SubscriptionMatchedStatus status) const

Returns the subscription matched status.

Parameters
[out]statussubscription matched status struct
Returns
RETCODE_OK

◆ get_topicdescription()

FASTDDS_EXPORTED_API const TopicDescription * get_topicdescription ( ) const

Get TopicDescription.

Returns
TopicDescription pointer.

◆ get_unread_count() [1/2]

FASTDDS_EXPORTED_API uint64_t get_unread_count ( ) const

Get the number of samples pending to be read.

The number includes samples that may not yet be available to be read or taken by the user, due to samples being received out of order.

Returns
the number of samples on the reader history that have never been read.

◆ get_unread_count() [2/2]

FASTDDS_EXPORTED_API uint64_t get_unread_count ( bool  mark_as_read) const

Get the number of samples pending to be read.

Parameters
mark_as_readWhether the unread samples should be marked as read or not.
Returns
the number of samples on the reader history that have never been read.

◆ guid() [1/2]

FASTDDS_EXPORTED_API const fastdds::rtps::GUID_t & guid ( )

Get associated GUID.

Returns
Associated GUID

◆ guid() [2/2]

FASTDDS_EXPORTED_API const fastdds::rtps::GUID_t & guid ( ) const

Get associated GUID.

Returns
Associated GUID

◆ is_sample_valid()

FASTDDS_EXPORTED_API bool is_sample_valid ( const void *  data,
const SampleInfo info 
) const

Checks whether a loaned sample is still valid or is corrupted.

Calling this method on a sample which has not been loaned, or one for which the loan has been returned yields undefined behavior.

Parameters
dataPointer to the sample data to check
infoPointer to the SampleInfo related to data
Returns
true if the sample is valid

◆ lookup_instance()

FASTDDS_EXPORTED_API InstanceHandle_t lookup_instance ( const void *  instance) const

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.

Parameters
[in]instanceData pointer to the sample
Returns
handle of the given instance.
HANDLE_NIL if instance is nullptr.
HANDLE_NIL if there is no instance on the DataReader's history with the same key as instance.

◆ read()

FASTDDS_EXPORTED_API ReturnCode_t read ( LoanableCollection data_values,
SampleInfoSeq sample_infos,
int32_t  max_samples = LENGTH_UNLIMITED,
SampleStateMask  sample_states = ANY_SAMPLE_STATE,
ViewStateMask  view_states = ANY_VIEW_STATE,
InstanceStateMask  instance_states = ANY_INSTANCE_STATE 
)

Access a collection of data samples from the DataReader.

This operation accesses a collection of Data values from the DataReader. The caller can limit the size of the returned collection with the max_samples parameter.

The properties of the data_values collection and the setting of the PresentationQosPolicy may impose further limits on the size of the returned ‘list.’

  1. If PresentationQosPolicy::access_scope is INSTANCE_PRESENTATION_QOS, then the returned collection is a 'list' where samples belonging to the same data-instance are consecutive.
  2. If PresentationQosPolicy::access_scope is TOPIC_PRESENTATION_QOS and PresentationQosPolicy::ordered_access is set to false, then the returned collection is a 'list' where samples belonging to the same data-instance are consecutive.
  3. If PresentationQosPolicy::access_scope is TOPIC_PRESENTATION_QOS and PresentationQosPolicy::ordered_access is set to true, then the returned collection is a 'list' where 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.
  4. If PresentationQosPolicy::access_scope is GROUP_PRESENTATION_QOS and PresentationQosPolicy::ordered_access is set to false, then the returned collection is a 'list' where samples belonging to the same data instance are consecutive.
  5. If PresentationQosPolicy::access_scope is GROUP_PRESENTATION_QOS and PresentationQosPolicy::ordered_access is set to true, then the returned collection contains at most one sample. The difference in this case is due to the fact that it is required that the application is able to read samples belonging to different DataReader objects in a specific order.

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

The actual number of samples returned depends on the information that has been received by the middleware as well as the HistoryQosPolicy, ResourceLimitsQosPolicy, and ReaderResourceLimitsQos:

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

In addition to the collection of samples, the read operation also uses a collection of SampleInfo structures (sample_infos).

The initial (input) properties of the data_values and sample_infos collections will determine the precise behavior of this operation. For the purposes of this description the collections are modeled as having three properties:

The initial (input) values of the len, max_len, and owns properties for the data_values and sample_infos collections govern the behavior of the read operation as specified by the following rules:

  1. The values of len, max_len, and owns for the two collections must be identical. Otherwise read will fail with RETCODE_PRECONDITION_NOT_MET.
  2. On successful output, the values of len, max_len, and owns will be the same for both collections.
  3. If the input max_len == 0 , then the data_values and sample_infos collections will be filled with elements that are 'loaned' by the DataReader. 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 DataReader using the return_loan operation.
  4. If the input max_len > 0 and the input owns == false , then the read operation will fail with RETCODE_PRECONDITION_NOT_MET. This avoids the potential hard-to-detect memory leaks caused by an application forgetting to return the loan.
  5. If input max_len > 0 and the input owns == true , then the read operation will copy the Data values and 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 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 operation will fail with 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 DataReader, because the output sequence cannot accommodate them.

As described above, upon return the data_values and sample_infos collections may contain elements 'loaned' from the DataReader. If this is the case, the application will need to use the return_loan operation to return the loan once it is no longer using the Data in the collection. Upon return from return_loan, the collection will have max_len == 0 and owns == false .

The application can determine whether it is necessary to return the loan or not based on the state of the collections when the read operation was called, or by accessing the owns property. However, in many cases it may be simpler to always call return_loan, as this operation is harmless (i.e., leaves all elements unchanged) if the collection does not have a loan.

On output, the collection of Data values and the collection of SampleInfo structures are of the same length and are in a one-to-one correspondence. Each 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 SampleInfo is NOT_ALIVE_DISPOSED_INSTANCE_STATE or NOT_ALIVE_NO_WRITERS_INSTANCE_STATE, then the last sample for that instance in the collection, that is, the one whose SampleInfo has sample_rank == 0 does not contain valid data. Samples that contain no data do not count towards the limits imposed by the ResourceLimitsQosPolicy.

The act of reading a sample changes its sample_state to 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 NOT_NEW_VIEW_STATE. It will not affect the instance_state of the instance.

If the DataReader has no samples that meet the constraints, the operations fails with RETCODE_NO_DATA.

Important: If the samples "returned" by this method are loaned from the middleware (see 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
[in,out]data_valuesA LoanableCollection object where the received data samples will be returned.
[in,out]sample_infosA SampleInfoSeq object where the received sample info will be returned.
[in]max_samplesThe maximum number of samples to be returned. If the special value LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described above.
[in]sample_statesOnly data samples with sample_state matching one of these will be returned.
[in]view_statesOnly data samples with view_state matching one of these will be returned.
[in]instance_statesOnly data samples with instance_state matching one of these will be returned.
Returns
Any of the standard return codes.

◆ read_instance()

FASTDDS_EXPORTED_API ReturnCode_t read_instance ( LoanableCollection data_values,
SampleInfoSeq sample_infos,
int32_t  max_samples = LENGTH_UNLIMITED,
const InstanceHandle_t a_handle = HANDLE_NIL,
SampleStateMask  sample_states = ANY_SAMPLE_STATE,
ViewStateMask  view_states = ANY_VIEW_STATE,
InstanceStateMask  instance_states = ANY_INSTANCE_STATE 
)

Access a collection of data samples from the DataReader.

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

This operation is semantically equivalent to the read operation, except in building the collection. The 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 this operation follows the same rules as the read operation regarding the pre-conditions and post-conditions for the data_values and sample_infos. Similar to read, this operation may 'loan' elements to the output collections, which must then be returned by means of return_loan.

If the DataReader has no samples that meet the constraints, the operations fails with RETCODE_NO_DATA.

Parameters
[in,out]data_valuesA LoanableCollection object where the received data samples will be returned.
[in,out]sample_infosA SampleInfoSeq object where the received sample info will be returned.
[in]max_samplesThe maximum number of samples to be returned. If the special value LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for read().
[in]a_handleThe specified instance to return samples for. The method will fail with RETCODE_BAD_PARAMETER if the handle does not correspond to an existing data-object known to the DataReader.
[in]sample_statesOnly data samples with sample_state matching one of these will be returned.
[in]view_statesOnly data samples with view_state matching one of these will be returned.
[in]instance_statesOnly data samples with instance_state matching one of these will be returned.
Returns
Any of the standard return codes.

◆ read_next_instance()

FASTDDS_EXPORTED_API ReturnCode_t read_next_instance ( LoanableCollection data_values,
SampleInfoSeq sample_infos,
int32_t  max_samples = LENGTH_UNLIMITED,
const InstanceHandle_t previous_handle = HANDLE_NIL,
SampleStateMask  sample_states = ANY_SAMPLE_STATE,
ViewStateMask  view_states = ANY_VIEW_STATE,
InstanceStateMask  instance_states = ANY_INSTANCE_STATE 
)

Access a collection of data samples from the DataReader.

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

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

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

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

If the DataReader has no samples that meet the constraints, the operations fails with RETCODE_NO_DATA.

Parameters
[in,out]data_valuesA LoanableCollection object where the received data samples will be returned.
[in,out]sample_infosA SampleInfoSeq object where the received sample info will be returned.
[in]max_samplesThe maximum number of samples to be returned. If the special value LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for read().
[in]previous_handleThe 'next smallest' instance with a value greater than this value that has available samples will be returned.
[in]sample_statesOnly data samples with sample_state matching one of these will be returned.
[in]view_statesOnly data samples with view_state matching one of these will be returned.
[in]instance_statesOnly data samples with instance_state matching one of these will be returned.
Returns
Any of the standard return codes.

◆ read_next_instance_w_condition()

FASTDDS_EXPORTED_API ReturnCode_t read_next_instance_w_condition ( LoanableCollection data_values,
SampleInfoSeq sample_infos,
int32_t  max_samples,
const InstanceHandle_t previous_handle,
ReadCondition a_condition 
)

This operation accesses a collection of Data values from the DataReader.

The behavior is identical to read_next_instance except that all samples returned 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 ReadCondition evaluates to TRUE.

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

The behavior of the read_next_instance_w_condition operation follows the same rules than the read operation regarding the pre-conditions and post-conditions for the data_values and sample_infos collections. Similar to read, the read_next_instance_w_condition operation may ‘loan’ elements to the output collections which must then be returned by means of return_loan.

If the DataReader has no samples that meet the constraints, the return value will be RETCODE_NO_DATA.

Parameters
[in,out]data_valuesA LoanableCollection object where the received data samples will be returned.
[in,out]sample_infosA SampleInfoSeq object where the received sample info will be returned.
[in]max_samplesThe maximum number of samples to be returned. If the special value LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for read().
[in]previous_handleThe 'next smallest' instance with a value greater than this value that has available samples will be returned.
[in]a_conditionA ReadCondition that returned data_values must pass
Returns
Any of the standard return codes.

◆ read_next_sample()

FASTDDS_EXPORTED_API ReturnCode_t read_next_sample ( void *  data,
SampleInfo info 
)

This operation copies the next, non-previously accessed Data value from the DataReader; the operation also copies the corresponding SampleInfo.

The implied order among the samples stored in the DataReader is the same as for the read operation.

The read_next_sample operation is semantically equivalent to the read operation where the input Data sequence has max_length = 1 , the sample_states = NOT_READ_SAMPLE_STATE , the view_states = ANY_VIEW_STATE , and the instance_states = ANY_INSTANCE_STATE .

The 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 DataReader, the operation will return RETCODE_NO_DATA and nothing is copied

Parameters
[out]dataData pointer to store the sample
[out]infoSampleInfo pointer to store the sample information
Returns
Any of the standard return codes.

◆ read_w_condition()

FASTDDS_EXPORTED_API ReturnCode_t read_w_condition ( LoanableCollection data_values,
SampleInfoSeq sample_infos,
int32_t  max_samples,
ReadCondition a_condition 
)

This operation accesses via ‘read’ the samples that match the criteria specified in the ReadCondition.

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

The specified ReadCondition must be attached to the DataReader; otherwise the operation will fail and return RETCODE_PRECONDITION_NOT_MET.

In case the ReadCondition is a ‘plain’ ReadCondition and not the specialized QueryCondition, the operation is equivalent to calling read and passing as sample_states, view_states and instance_states the value of the corresponding attributes in a_condition. Using this operation the application can avoid repeating the same parameters specified when creating the ReadCondition.

The samples are accessed with the same semantics as the read operation. If the DataReader has no samples that meet the constraints, the return value will be RETCODE_NO_DATA.

Parameters
[in,out]data_valuesA LoanableCollection object where the received data samples will be returned.
[in,out]sample_infosA SampleInfoSeq object where the received sample info will be returned.
[in]max_samplesThe maximum number of samples to be returned.
[in]a_conditionA ReadCondition that returned data_values must pass
Returns
Any of the standard return codes.

◆ return_loan()

FASTDDS_EXPORTED_API ReturnCode_t return_loan ( LoanableCollection data_values,
SampleInfoSeq sample_infos 
)

This operation indicates to the DataReader that the application is done accessing the collection of data_values and sample_infos obtained by some earlier invocation of read or take on the DataReader.

The data_values and sample_infos 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 data_values and sample_infos must also have been obtained from the same DataReader to which they are returned. If either of these conditions is not met, the operation will fail and return RETCODE_PRECONDITION_NOT_MET.

This operation allows implementations of the read and take operations to "loan" buffers from the DataReader to the application and in this manner provide "zero-copy" access to the data. During the loan, the 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 DataReader, the application should not retain them indefinitely.

The use of the return_loan operation is only necessary if the read or take calls "loaned" buffers to the application. This only occurs if the data_values and sample_infos collections had max_len == 0 at the time read or take was called. The application may also examine the has_ownership property of the collection to determine if there is an outstanding loan. However, calling return_loan on a collection that does not have a loan is safe, has no side effects, and returns RETCODE_OK.

If the collections had a loan, upon return from return_loan the collections will have max_len == 0 .

Parameters
[in,out]data_valuesA LoanableCollection object where the received data samples were obtained from an earlier invocation of read or take on this DataReader.
[in,out]sample_infosA SampleInfoSeq object where the received sample infos were obtained from an earlier invocation of read or take on this DataReader.
Returns
Any of the standard return codes.

◆ set_listener() [1/2]

FASTDDS_EXPORTED_API ReturnCode_t set_listener ( DataReaderListener listener)

Modifies the DataReaderListener, sets the mask to StatusMask::all().

Parameters
[in]listenernew value for the DataReaderListener.
Returns
RETCODE_OK

◆ set_listener() [2/2]

FASTDDS_EXPORTED_API ReturnCode_t set_listener ( DataReaderListener listener,
const StatusMask mask 
)

Modifies the DataReaderListener.

Parameters
[in]listenernew value for the DataReaderListener.
[in]maskStatusMask that holds statuses the listener responds to (default: all).
Returns
RETCODE_OK

◆ set_qos()

FASTDDS_EXPORTED_API ReturnCode_t set_qos ( const DataReaderQos qos)

Setter for the DataReaderQos.

Parameters
[in]qosnew value for the DataReaderQos.
Returns
RETCODE_IMMUTABLE_POLICY if any of the Qos cannot be changed, RETCODE_INCONSISTENT_POLICY if the Qos is not self consistent and RETCODE_OK if the qos is changed correctly.

◆ take()

FASTDDS_EXPORTED_API ReturnCode_t take ( LoanableCollection data_values,
SampleInfoSeq sample_infos,
int32_t  max_samples = LENGTH_UNLIMITED,
SampleStateMask  sample_states = ANY_SAMPLE_STATE,
ViewStateMask  view_states = ANY_VIEW_STATE,
InstanceStateMask  instance_states = ANY_INSTANCE_STATE 
)

Access a collection of data samples from the DataReader.

This operation accesses a collection of data-samples from the DataReader and a corresponding collection of SampleInfo structures, and 'removes' them from the DataReader. The operation will return either a 'list' of samples or else a single sample. This is controlled by the PresentationQosPolicy using the same logic as for the read operation.

The act of taking a sample removes it from the DataReader 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 instance to NOT_NEW. It will not affect the instance_state of the instance.

The behavior of the take operation follows the same rules than the read operation regarding the pre-conditions and post-conditions for the data_values and sample_infos collections. Similar to read, the take operation may 'loan' elements to the output collections which must then be returned by means of return_loan. The only difference with read is that, as stated, the samples returned by take will no longer be accessible to successive calls to read or take.

If the DataReader has no samples that meet the constraints, the operations fails with RETCODE_NO_DATA.

Parameters
[in,out]data_valuesA LoanableCollection object where the received data samples will be returned.
[in,out]sample_infosA SampleInfoSeq object where the received sample info will be returned.
[in]max_samplesThe maximum number of samples to be returned. If the special value LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for read().
[in]sample_statesOnly data samples with sample_state matching one of these will be returned.
[in]view_statesOnly data samples with view_state matching one of these will be returned.
[in]instance_statesOnly data samples with instance_state matching one of these will be returned.
Returns
Any of the standard return codes.

◆ take_instance()

FASTDDS_EXPORTED_API ReturnCode_t take_instance ( LoanableCollection data_values,
SampleInfoSeq sample_infos,
int32_t  max_samples = LENGTH_UNLIMITED,
const InstanceHandle_t a_handle = HANDLE_NIL,
SampleStateMask  sample_states = ANY_SAMPLE_STATE,
ViewStateMask  view_states = ANY_VIEW_STATE,
InstanceStateMask  instance_states = ANY_INSTANCE_STATE 
)

Access a collection of data samples from the DataReader.

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

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

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

If the DataReader has no samples that meet the constraints, the operations fails with RETCODE_NO_DATA.

Parameters
[in,out]data_valuesA LoanableCollection object where the received data samples will be returned.
[in,out]sample_infosA SampleInfoSeq object where the received sample info will be returned.
[in]max_samplesThe maximum number of samples to be returned. If the special value LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for read().
[in]a_handleThe specified instance to return samples for. The method will fail with RETCODE_BAD_PARAMETER if the handle does not correspond to an existing data-object known to the DataReader.
[in]sample_statesOnly data samples with sample_state matching one of these will be returned.
[in]view_statesOnly data samples with view_state matching one of these will be returned.
[in]instance_statesOnly data samples with instance_state matching one of these will be returned.
Returns
Any of the standard return codes.

◆ take_next_instance()

FASTDDS_EXPORTED_API ReturnCode_t take_next_instance ( LoanableCollection data_values,
SampleInfoSeq sample_infos,
int32_t  max_samples = LENGTH_UNLIMITED,
const InstanceHandle_t previous_handle = HANDLE_NIL,
SampleStateMask  sample_states = ANY_SAMPLE_STATE,
ViewStateMask  view_states = ANY_VIEW_STATE,
InstanceStateMask  instance_states = ANY_INSTANCE_STATE 
)

Access a collection of data samples from the DataReader.

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

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

Similar to the operation read_next_instance, it is possible to call this operation with a previous_handle that does not correspond to an instance currently managed by the DataReader.

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

If the DataReader has no samples that meet the constraints, the operations fails with RETCODE_NO_DATA.

Parameters
[in,out]data_valuesA LoanableCollection object where the received data samples will be returned.
[in,out]sample_infosA SampleInfoSeq object where the received sample info will be returned.
[in]max_samplesThe maximum number of samples to be returned. If the special value LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for read().
[in]previous_handleThe 'next smallest' instance with a value greater than this value that has available samples will be returned.
[in]sample_statesOnly data samples with sample_state matching one of these will be returned.
[in]view_statesOnly data samples with view_state matching one of these will be returned.
[in]instance_statesOnly data samples with instance_state matching one of these will be returned.
Returns
Any of the standard return codes.

◆ take_next_instance_w_condition()

FASTDDS_EXPORTED_API ReturnCode_t take_next_instance_w_condition ( LoanableCollection data_values,
SampleInfoSeq sample_infos,
int32_t  max_samples,
const InstanceHandle_t previous_handle,
ReadCondition a_condition 
)

This operation accesses a collection of Data values from the DataReader.

The behavior is identical to read_next_instance except that all samples returned 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 ReadCondition evaluates to TRUE.

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

The behavior of the read_next_instance_w_condition operation follows the same rules than the read operation regarding the pre-conditions and post-conditions for the data_values and sample_infos collections. Similar to read, the read_next_instance_w_condition operation may ‘loan’ elements to the output collections which must then be returned by means of return_loan.

If the DataReader has no samples that meet the constraints, the return value will be RETCODE_NO_DATA

Parameters
[in,out]data_valuesA LoanableCollection object where the received data samples will be returned.
[in,out]sample_infosA SampleInfoSeq object where the received sample info will be returned.
[in]max_samplesThe maximum number of samples to be returned. If the special value LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for read().
[in]previous_handleThe 'next smallest' instance with a value greater than this value that has available samples will be returned.
[in]a_conditionA ReadCondition that returned data_values must pass
Returns
Any of the standard return codes.

◆ take_next_sample()

FASTDDS_EXPORTED_API ReturnCode_t take_next_sample ( void *  data,
SampleInfo info 
)

This operation copies the next, non-previously accessed Data value from the DataReader and ‘removes’ it from the DataReader so it is no longer accessible.

The operation also copies the corresponding SampleInfo.

This operation is analogous to read_next_sample except for the fact that the sample is ‘removed’ from the DataReader.

This operation is semantically equivalent to the take operation where the input sequence has max_length = 1 , the sample_states = NOT_READ_SAMPLE_STATE , the view_states = ANY_VIEW_STATE , and the instance_states = ANY_INSTANCE_STATE .

This 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 DataReader, the operation will return RETCODE_NO_DATA and nothing is copied.

Parameters
[out]dataData pointer to store the sample
[out]infoSampleInfo pointer to store the sample information
Returns
Any of the standard return codes.

◆ take_w_condition()

FASTDDS_EXPORTED_API ReturnCode_t take_w_condition ( LoanableCollection data_values,
SampleInfoSeq sample_infos,
int32_t  max_samples,
ReadCondition a_condition 
)

This operation is analogous to read_w_condition except it accesses samples via the ‘take’ operation.

The specified ReadCondition must be attached to the DataReader; otherwise the operation will fail and return RETCODE_PRECONDITION_NOT_MET.

The samples are accessed with the same semantics as the take operation.

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

If the DataReader has no samples that meet the constraints, the return value will be RETCODE_NO_DATA.

Parameters
[in,out]data_valuesA LoanableCollection object where the received data samples will be returned.
[in,out]sample_infosA SampleInfoSeq object where the received sample info will be returned.
[in]max_samplesThe maximum number of samples to be returned. If the special value LENGTH_UNLIMITED is provided, as many samples will be returned as are.
[in]a_conditionA ReadCondition that returned data_values must pass
Returns
Any of the standard return codes.

◆ type()

FASTDDS_EXPORTED_API TypeSupport type ( )

Getter for the data type.

Returns
TypeSupport associated to the DataReader.

◆ wait_for_historical_data()

FASTDDS_EXPORTED_API ReturnCode_t wait_for_historical_data ( const fastdds::dds::Duration_t max_wait) const

NOT YET IMPLEMENTED.

Method to block the current thread until an unread message is available.

Parameters
[in]max_waitMax blocking time for this operation.
Returns
RETCODE_OK if there is new unread message, RETCODE_TIMEOUT if timeout
Warning
Not supported yet. Currently returns RETCODE_UNSUPPORTED

◆ wait_for_unread_message()

FASTDDS_EXPORTED_API bool wait_for_unread_message ( const fastdds::dds::Duration_t timeout)

Method to block the current thread until an unread message is available.

Parameters
[in]timeoutMax blocking time for this operation.
Returns
true if there is new unread message, false if timeout

Friends And Related Symbol Documentation

◆ ::dds::sub::DataReader

friend class ::dds::sub::DataReader
friend

◆ DataReaderImpl

friend class DataReaderImpl
friend

◆ SubscriberImpl

friend class SubscriberImpl
friend

Member Data Documentation

◆ impl_

DataReaderImpl* impl_
protected

The documentation for this class was generated from the following file: