RTI Connext DDS Micro  Version 2.4.11
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
DataReader

DDS_DataReader entity and associated elements More...

Data Structures

struct  FooDataReader
 <<interface>> <<generic>> User data type-specific data reader. More...
struct  DDS_RequestedDeadlineMissedStatus
 <<cert>> DDS_REQUESTED_DEADLINE_MISSED_STATUS More...
struct  DDS_LivelinessChangedStatus
 <<cert>> DDS_LIVELINESS_CHANGED_STATUS More...
struct  DDS_RequestedIncompatibleQosStatus
 <<cert>> DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS More...
struct  DDS_SampleRejectedStatus
 DDS_SAMPLE_REJECTED_STATUS More...
struct  DDS_DataReaderInstanceReplacedStatus
 <<eXtension>> <<cert>> DDS_INSTANCE_REPLACED_STATUS. More...
struct  DDS_SubscriptionMatchedStatus
 <<cert>> DDS_SUBSCRIPTION_MATCHED_STATUS More...
struct  DDS_SampleLostStatus
 <<cert>> DDS_SAMPLE_LOST_STATUS More...
struct  DDS_DataReaderQos
 <<cert>> QoS policies supported by a DDS_DataReader entity. More...
struct  DDS_DataReaderListener
 <<interface>> <<cert>> DDS_Listener for reader status. More...

Macros

#define DDS_RequestedDeadlineMissedStatus_INITIALIZER
 <<cert>> Initializer for new status instances.
#define DDS_LivelinessChangedStatus_INITIALIZER
 <<cert>> Initializer for new status instances.
#define DDS_RequestedIncompatibleQosStatus_INITIALIZER
 <<cert>> Initializer for new status instances.
#define DDS_SampleRejectedStatus_INITIALIZER
 <<cert>> Initializer for new status instances.
#define DDS_DataReaderInstanceReplacedStatus_INITIALIZER
 <<cert>> Initializer for new status instances.
#define DDS_SubscriptionMatchedStatus_INITIALIZER
 <<cert>> Initializer for new status instances.
#define DDS_SampleLostStatus_INITIALIZER
 <<cert>> Initializer for new status instances.
#define DDS_DataReaderQos_INITIALIZER
 <<cert>> Initializer for new QoS instances.
#define DDS_DataReaderListener_INITIALIZER
 <<cert>> Initializer for new DDS_DataReaderListener.

Typedefs

typedef struct DDS_DataReaderImpl DDS_DataReader
 <<interface>> <<cert>> Allows the application to: (1) declare the data it wishes to receive (i.e. make a subscription) and (2) access the data received by the attached DDS_Subscriber.
typedef void(* DDS_DataReaderListener_RequestedDeadlineMissedCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_RequestedDeadlineMissedStatus *status)
 <<cert>> Prototype of a DDS_DataReaderListener requested_deadline_missed function.
typedef void(* DDS_DataReaderListener_LivelinessChangedCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_LivelinessChangedStatus *status)
 <<cert>> Prototype of a DDS_DataReaderListener liveliness_changed function.
typedef void(* DDS_DataReaderListener_RequestedIncompatibleQosCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_RequestedIncompatibleQosStatus *status)
 <<cert>> Prototype of a DDS_DataReaderListener requested_incompatible_QoS function.
typedef void(* DDS_DataReaderListener_SampleRejectedCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_SampleRejectedStatus *status)
 <<cert>> Prototype of a DDS_DataReaderListener sample_rejected function.
typedef void(* DDS_DataReaderListener_DataAvailableCallback )(void *listener_data, DDS_DataReader *reader)
 <<cert>> Prototype of a DDS_DataReaderListener data_available function.
typedef void(* DDS_DataReaderListener_SubscriptionMatchedCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_SubscriptionMatchedStatus *status)
 <<cert>> Prototype of a DDS_DataReaderListener subscription_match function.
typedef void(* DDS_DataReaderListener_SampleLostCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_SampleLostStatus *status)
 <<cert>> Prototype of a DDS_DataReaderListener subscription_lost function.
typedef void(* DDS_DataReaderListener_InstanceReplacedCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_DataReaderInstanceReplacedStatus *status)
 <<cert>> Prototype of a DDS_DataReaderListener instance_replaced function.
typedef DDS_Boolean(* DDS_DataReaderListener_BeforeSampleDeserializeCallback )(void *listener_data, DDS_DataReader *reader, struct NDDS_Type_Plugin *plugin, struct CDR_Stream_t *stream, DDS_Boolean *dropped)
 <<cert>> Prototype of a DDS_DataReaderListener before_sample_deserialize function.
typedef DDS_Boolean(* DDS_DataReaderListener_BeforeSampleCommitCallback )(void *listener_data, DDS_DataReader *reader, const void *const sample, DDS_Boolean *dropped)
 <<cert>> Prototype of a DDS_DataReaderListener before_sample_commit function.

Enumerations

enum  DDS_SampleRejectedStatusKind {
  DDS_NOT_REJECTED, DDS_REJECTED_BY_INSTANCES_LIMIT, DDS_REJECTED_BY_SAMPLES_LIMIT, DDS_REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT,
  DDS_REJECTED_BY_REMOTE_WRITERS_LIMIT, DDS_REJECTED_BY_SAMPLES_PER_REMOTE_WRITER_LIMIT
}
 Kinds of reasons for rejecting a sample. More...
enum  DDS_SampleLostStatusKind {
  DDS_SAMPLE_LOST_NOT_LOST, DDS_SAMPLE_LOST_BY_DATAWRITER, DDS_SAMPLE_LOST_BY_MAX_SAMPLES_LIMIT, DDS_SAMPLE_LOST_BY_HISTORY_DEPTH_LIMIT,
  DDS_SAMPLE_LOST_BY_META_SAMPLE_LIMIT, DDS_SAMPLE_LOST_BY_NOT_READ_ON_CACHE_DELETION
}
 Kinds of reasons a sample was lost. More...

Functions

FooDataReaderFooDataReader_narrow (DDS_DataReader *reader)
 Narrow the given DDS_DataReader pointer to a FooDataReader pointer.
DDS_DataReaderFooDataReader_as_datareader (FooDataReader *reader)
 Widen the given FooDataReader pointer to a DDS_DataReader pointer.
DDS_ReturnCode_t FooDataReader_read (FooDataReader *self, struct FooSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_samples, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
 Access a collection of data samples from the DDS_DataReader.
DDS_ReturnCode_t FooDataReader_take (FooDataReader *self, struct FooSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_samples, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
 Access a collection of data-samples from the DDS_DataReader.
DDS_ReturnCode_t FooDataReader_read_next_sample (FooDataReader *self, struct Foo *received_data, struct DDS_SampleInfo *sample_info)
 Copies the next not-previously-accessed data value from the DDS_DataReader.
DDS_ReturnCode_t FooDataReader_take_next_sample (FooDataReader *self, struct Foo *received_data, struct DDS_SampleInfo *sample_info)
 Copies the next not-previously-accessed data value from the DDS_DataReader.
DDS_ReturnCode_t FooDataReader_read_instance (FooDataReader *self, struct FooSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_samples, const DDS_InstanceHandle_t *a_handle, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
 Access a collection of data samples from the DDS_DataReader.
DDS_ReturnCode_t FooDataReader_take_instance (FooDataReader *self, struct FooSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_samples, const DDS_InstanceHandle_t *a_handle, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
 Access a collection of data samples from the DDS_DataReader.
DDS_ReturnCode_t FooDataReader_return_loan (FooDataReader *self, FooSeq *received_data, struct DDS_SampleInfoSeq *info_seq)
 Indicates to the DDS_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 DDS_DataReader.
DDS_InstanceHandle_t FooDataReader_lookup_instance (FooDataReader *self, const Foo *key_holder)
 Retrieve the instance handle that corresponds to an instance key_holder.
DDS_ReturnCode_t DDS_DataReaderQos_initialize (struct DDS_DataReaderQos *self)
 Initializer for new QoS instances.
DDS_ReturnCode_t DDS_DataReaderQos_copy (struct DDS_DataReaderQos *self, const struct DDS_DataReaderQos *source)
 Copy the contents of the given QoS into this QoS.
DDS_ReturnCode_t DDS_DataReaderQos_finalize (struct DDS_DataReaderQos *self)
 Free any dynamic memory allocated by the policies in this DDS_DataReaderQos.
DDS_EntityDDS_DataReader_as_entity (DDS_DataReader *dataReader)
 <<cert>> Accesses the DDS_DataReader's supertype instance.
DDS_ReturnCode_t DDS_DataReader_enable (DDS_Entity *self)
 Enables a DDS_DataReader instance.
DDS_ReturnCode_t DDS_DataReader_get_matched_publications (DDS_DataReader *self, struct DDS_InstanceHandleSeq *publication_handles)
 Retrieve the list of publications currently "associated" with this DDS_DataReader.
DDS_ReturnCode_t DDS_DataReader_get_matched_publication_data (DDS_DataReader *self, struct DDS_PublicationBuiltinTopicData *publication_data, const DDS_InstanceHandle_t *publication_handle)
 This operation retrieves the information on a publication that is currently "associated" with the DDS_DataReader.
DDS_TopicDescriptionDDS_DataReader_get_topicdescription (DDS_DataReader *self)
 <<cert>> Returns the DDS_TopicDescription associated with the DDS_DataReader.
DDS_SubscriberDDS_DataReader_get_subscriber (DDS_DataReader *self)
 <<cert>> Returns the DDS_Subscriber to which the DDS_DataReader belongs.
DDS_ReturnCode_t DDS_DataReader_get_sample_rejected_status (DDS_DataReader *self, struct DDS_SampleRejectedStatus *status)
 <<cert>> Accesses the DDS_SAMPLE_REJECTED_STATUS communication status.
DDS_ReturnCode_t DDS_DataReader_get_liveliness_changed_status (DDS_DataReader *self, struct DDS_LivelinessChangedStatus *status)
 <<cert>> Accesses the DDS_LIVELINESS_CHANGED_STATUS communication status.
DDS_ReturnCode_t DDS_DataReader_get_requested_deadline_missed_status (DDS_DataReader *self, struct DDS_RequestedDeadlineMissedStatus *status)
 <<cert>> Accesses the DDS_REQUESTED_DEADLINE_MISSED_STATUS communication status.
DDS_ReturnCode_t DDS_DataReader_get_requested_incompatible_qos_status (DDS_DataReader *self, struct DDS_RequestedIncompatibleQosStatus *status)
 <<cert>> Accesses the DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS communication status.
DDS_ReturnCode_t DDS_DataReader_get_subscription_matched_status (DDS_DataReader *self, struct DDS_SubscriptionMatchedStatus *status)
 <<cert>> Accesses the DDS_SUBSCRIPTION_MATCHED_STATUS communication status.
DDS_ReturnCode_t DDS_DataReader_get_sample_lost_status (DDS_DataReader *self, struct DDS_SampleLostStatus *status)
 <<cert>> Accesses the DDS_SAMPLE_LOST_STATUS communication status.
DDS_ReturnCode_t DDS_DataReader_get_instance_replaced_status (DDS_DataReader *self, struct DDS_DataReaderInstanceReplacedStatus *status)
 <<cert>> Accesses the DDS_INSTANCE_REPLACED_STATUS communication status.
DDS_ReturnCode_t DDS_DataReader_set_qos (DDS_DataReader *self, const struct DDS_DataReaderQos *qos)
 Sets the reader QoS.
DDS_ReturnCode_t DDS_DataReader_get_qos (DDS_DataReader *self, struct DDS_DataReaderQos *qos)
 Gets the reader QoS.
DDS_ReturnCode_t DDS_DataReader_set_listener (DDS_DataReader *self, const struct DDS_DataReaderListener *l, DDS_StatusMask mask)
 Sets the reader listener.
struct DDS_DataReaderListener DDS_DataReader_get_listener (DDS_DataReader *self)
 Get the reader listener.
DDS_ReturnCode_t DDS_DataReader_read (DDS_DataReader *self, struct DDS_UntypedSampleSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_samples, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
 <<cert>> Access a collection of data samples from the DDS_DataReader.
DDS_ReturnCode_t DDS_DataReader_take (DDS_DataReader *self, struct DDS_UntypedSampleSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_samples, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
 <<cert>> Access a collection of data-samples from the DDS_DataReader.
DDS_ReturnCode_t DDS_DataReader_read_next_sample (DDS_DataReader *self, void *received_data, struct DDS_SampleInfo *sample_info)
 <<cert>> Copies the next not-previously-accessed data value from the DDS_DataReader.
DDS_ReturnCode_t DDS_DataReader_take_next_sample (DDS_DataReader *self, void *received_data, struct DDS_SampleInfo *sample_info)
 <<cert>> Copies the next not-previously-accessed data value from the DDS_DataReader.
DDS_ReturnCode_t DDS_DataReader_read_instance (DDS_DataReader *self, struct DDS_UntypedSampleSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_samples, const DDS_InstanceHandle_t *a_handle, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
 <<cert>> Access a collection of data samples from the DDS_DataReader, all of which belong to the same instance .
DDS_ReturnCode_t DDS_DataReader_take_instance (DDS_DataReader *self, struct DDS_UntypedSampleSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_samples, const DDS_InstanceHandle_t *a_handle, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
 <<cert>> Access a collection of data samples from the DDS_DataReader, all of which belong to the same instance .
DDS_ReturnCode_t DDS_DataReader_return_loan (DDS_DataReader *self, struct DDS_UntypedSampleSeq *received_data, struct DDS_SampleInfoSeq *info_seq)
 <<cert>> Indicates to the DDS_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 DDS_DataReader.
DDS_InstanceHandle_t DDS_DataReader_lookup_instance (DDS_DataReader *self, const void *key_holder)
 <<cert>> Retrieve the DDS_InstanceHandle_t identifying a specific instance.

Detailed Description

DDS_DataReader entity and associated elements


Macro Definition Documentation

#define DDS_RequestedDeadlineMissedStatus_INITIALIZER

<<cert>> Initializer for new status instances.

New DDS_RequestedDeadlineMissedStatus instances that are stored on the stack should be initialized with this value before they are passed to any methods. This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory. The simplest way to create a status structure is to initialize it on the stack at the time of its creation.

#define DDS_LivelinessChangedStatus_INITIALIZER

<<cert>> Initializer for new status instances.

New DDS_LivelinessChangedStatus instances that are stored on the stack should be initialized with this value before they are passed to any function . This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory. The simplest way to create a status structure is to initialize it on the stack at the time of its creation.

#define DDS_RequestedIncompatibleQosStatus_INITIALIZER

<<cert>> Initializer for new status instances.

New DDS_RequestedIncompatibleQosStatus instances that are stored on the stack should be initialized with this value before they are passed to any function . This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory. The simplest way to create a status structure is to initialize it on the stack at the time of its creation.

#define DDS_SampleRejectedStatus_INITIALIZER

<<cert>> Initializer for new status instances.

New DDS_SampleRejectedStatus instances that are stored on the stack should be initialized with this value before they are passed to any function . This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory. The simplest way to create a status structure is to initialize it on the stack at the time of its creation.

#define DDS_DataReaderInstanceReplacedStatus_INITIALIZER

<<cert>> Initializer for new status instances.

New DDS_DataReaderInstanceReplacedStatus instances that are stored on the stack should be initialized with this value before they are passed to any methods. This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory. The simplest way to create a status structure is to initialize it on the stack at the time of its creation.

#define DDS_SubscriptionMatchedStatus_INITIALIZER

<<cert>> Initializer for new status instances.

New DDS_SubscriptionMatchedStatus instances that are stored on the stack should be initialized with this value before they are passed to any function . This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory. The simplest way to create a status structure is to initialize it on the stack at the time of its creation.

#define DDS_SampleLostStatus_INITIALIZER

<<cert>> Initializer for new status instances.

New DDS_SampleLostStatus instances that are stored on the stack should be initialized with this value before they are passed to any function . This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory. The simplest way to create a status structure is to initialize it on the stack at the time of its creation.

#define DDS_DataReaderQos_INITIALIZER

<<cert>> Initializer for new QoS instances.

New DDS_DataReaderQos instances that are stored in the stack should be initialized with this value before they are passed to any function . This step ensures that those contained QoS policies that use dynamic memory are properly initialized. The simplest way to create a new QoS structure is to initialize it on the stack at the time of its creation:

See also:
DDS_DataReaderQos_finalize
#define DDS_DataReaderListener_INITIALIZER

<<cert>> Initializer for new DDS_DataReaderListener.

All the new instances allocated in the stack should be initialized to this value.No memory is allocated.


Typedef Documentation

typedef struct DDS_DataReaderImpl DDS_DataReader

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

QoS:
DDS_DataReaderQos
Status:
DDS_DATA_AVAILABLE_STATUS;
DDS_LIVELINESS_CHANGED_STATUS, DDS_LivelinessChangedStatus;
DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS, DDS_RequestedIncompatibleQosStatus;
DDS_SUBSCRIPTION_MATCHED_STATUS, DDS_SubscriptionMatchedStatus;
DDS_INSTANCE_REPLACED_STATUS, DDS_DataReaderInstanceReplacedStatus;
Listener:
DDS_DataReaderListener A DDS_DataReader refers to exactly one DDS_TopicDescription (a DDS_Topic) that identifies the data to be read. The subscription has a unique resulting type. The data-reader may give access to several instances of the resulting type, which can be distinguished from each other by their key. The following operations may be called even if the DDS_DataReader is not enabled. Other operations will fail with the value DDS_RETCODE_NOT_ENABLED if called on a disabled DDS_DataReader:
typedef void(* DDS_DataReaderListener_RequestedDeadlineMissedCallback)(void *listener_data, DDS_DataReader *reader, const struct DDS_RequestedDeadlineMissedStatus *status)

<<cert>> Prototype of a DDS_DataReaderListener requested_deadline_missed function.

typedef void(* DDS_DataReaderListener_LivelinessChangedCallback)(void *listener_data, DDS_DataReader *reader, const struct DDS_LivelinessChangedStatus *status)

<<cert>> Prototype of a DDS_DataReaderListener liveliness_changed function.

typedef void(* DDS_DataReaderListener_RequestedIncompatibleQosCallback)(void *listener_data, DDS_DataReader *reader, const struct DDS_RequestedIncompatibleQosStatus *status)

<<cert>> Prototype of a DDS_DataReaderListener requested_incompatible_QoS function.

typedef void(* DDS_DataReaderListener_SampleRejectedCallback)(void *listener_data, DDS_DataReader *reader, const struct DDS_SampleRejectedStatus *status)

<<cert>> Prototype of a DDS_DataReaderListener sample_rejected function.

typedef void(* DDS_DataReaderListener_DataAvailableCallback)(void *listener_data, DDS_DataReader *reader)

<<cert>> Prototype of a DDS_DataReaderListener data_available function.

typedef void(* DDS_DataReaderListener_SubscriptionMatchedCallback)(void *listener_data, DDS_DataReader *reader, const struct DDS_SubscriptionMatchedStatus *status)

<<cert>> Prototype of a DDS_DataReaderListener subscription_match function.

typedef void(* DDS_DataReaderListener_SampleLostCallback)(void *listener_data, DDS_DataReader *reader, const struct DDS_SampleLostStatus *status)

<<cert>> Prototype of a DDS_DataReaderListener subscription_lost function.

typedef void(* DDS_DataReaderListener_InstanceReplacedCallback)(void *listener_data, DDS_DataReader *reader, const struct DDS_DataReaderInstanceReplacedStatus *status)

<<cert>> Prototype of a DDS_DataReaderListener instance_replaced function.

typedef DDS_Boolean(* DDS_DataReaderListener_BeforeSampleDeserializeCallback)(void *listener_data, DDS_DataReader *reader, struct NDDS_Type_Plugin *plugin, struct CDR_Stream_t *stream, DDS_Boolean *dropped)

<<cert>> Prototype of a DDS_DataReaderListener before_sample_deserialize function.

typedef DDS_Boolean(* DDS_DataReaderListener_BeforeSampleCommitCallback)(void *listener_data, DDS_DataReader *reader, const void *const sample, DDS_Boolean *dropped)

<<cert>> Prototype of a DDS_DataReaderListener before_sample_commit function.


Enumeration Type Documentation

Kinds of reasons for rejecting a sample.

Enumerator:
DDS_NOT_REJECTED 

Samples are never rejected.

See also:
DDS_ResourceLimitsQosPolicy
DDS_REJECTED_BY_INSTANCES_LIMIT 

A resource limit on the number of instances was reached.

See also:
DDS_ResourceLimitsQosPolicy
DDS_REJECTED_BY_SAMPLES_LIMIT 

A resource limit on the number of samples was reached.

See also:
DDS_ResourceLimitsQosPolicy
DDS_REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT 

A resource limit on the number of samples per instance was reached.

See also:
DDS_ResourceLimitsQosPolicy
DDS_REJECTED_BY_REMOTE_WRITERS_LIMIT 

A resource limit on the number of remote writers from which a DDS_DataReader may read was reached.

This constant is an extension to the DDS standard.

See also:
DDS_DataReaderResourceLimitsQosPolicy
DDS_REJECTED_BY_SAMPLES_PER_REMOTE_WRITER_LIMIT 

A resource limit on the number of samples from a given remote writer that a DDS_DataReader may store was reached.

This constant is an extension to the DDS standard.

See also:
DDS_DataReaderResourceLimitsQosPolicy

Kinds of reasons a sample was lost.

Enumerator:
DDS_SAMPLE_LOST_NOT_LOST 

Samples was not lost, normal removal.

See also:
DDS_ResourceLimitsQosPolicy
DDS_SAMPLE_LOST_BY_DATAWRITER 

Samples was lost was by the datawriter, it was never received by the datareader.

See also:
DDS_ResourceLimitsQosPolicy
DDS_SAMPLE_LOST_BY_MAX_SAMPLES_LIMIT 

A sample was received by the datareader but lost because the max_samples resource was exceeded and not samples could be freed to receive it.

See also:
DDS_ResourceLimitsQosPolicy
DDS_SAMPLE_LOST_BY_HISTORY_DEPTH_LIMIT 

A sample was received by the datareader but lost because the max depth was reached for the instance and no samples could be removed from the history. For example if all the samples in the datareader cache is loanded by the application they cannot be removed.

See also:
DDS_ResourceLimitsQosPolicy
DDS_SAMPLE_LOST_BY_META_SAMPLE_LIMIT 

A meta sample was received by the datareader but lost because the meta sample for the instance was loaned by the application and could not be reused.

See also:
DDS_ResourceLimitsQosPolicy
DDS_SAMPLE_LOST_BY_NOT_READ_ON_CACHE_DELETION 

The datareader has samples in the cache that had not been seen by the application and was lost when the datareader was deleted.

See also:
DDS_ResourceLimitsQosPolicy

Function Documentation

FooDataReader* FooDataReader_narrow ( DDS_DataReader reader)

Narrow the given DDS_DataReader pointer to a FooDataReader pointer.

Parameters:
reader<<in>> Cannot be NULL.
DDS_DataReader* FooDataReader_as_datareader ( FooDataReader reader)

Widen the given FooDataReader pointer to a DDS_DataReader pointer.

Parameters:
reader<<in>> Cannot be NULL.
DDS_ReturnCode_t FooDataReader_read ( FooDataReader self,
struct FooSeq received_data,
struct DDS_SampleInfoSeq info_seq,
DDS_Long  max_samples,
DDS_SampleStateMask  sample_states,
DDS_ViewStateMask  view_states,
DDS_InstanceStateMask  instance_states 
)

Access a collection of data samples from the DDS_DataReader.

This operation offers the same functionality and API as FooDataReader_take except that the samples returned remain in the DDS_DataReader such that they can be retrieved again by means of a read or take operation. Please refer to the documentation of FooDataReader_take() for details on the number of samples returned within the received_data and info_seq as well as the order in which the samples appear in these sequences. The act of reading a sample changes its sample_state to DDS_READ_SAMPLE_STATE. If the sample belongs to the most recent generation of the instance, it will also set the view_state of the instance to be DDS_NOT_NEW_VIEW_STATE. It will not affect the instance_state of the instance. Important: If the samples "returned" by this function are loaned from RTI Connext Micro (see FooDataReader_take for more information on memory loaning), it is important that their contents not be changed. Because the memory in which the data is stored belongs to the middleware, any modifications made to the data will be seen the next time the same samples are read or taken; the samples will no longer reflect the state that was received from the network.

Parameters:
self<<in>> Cannot be NULL.
received_data<<inout>> User data type-specific FooSeq object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
info_seq<<inout>> A DDS_SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS_SampleInfoSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
max_samples<<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available.
sample_states<<in>> Data samples matching one of these sample_states are returned.
view_states<<in>> Data samples matching one of these view_state are returned.
instance_states<<in>> Data samples matching ones of these instance_state are returned.
Returns:
One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.
See also:
FooDataReader_take,
DDS_LENGTH_UNLIMITED
DDS_ReturnCode_t FooDataReader_take ( FooDataReader self,
struct FooSeq received_data,
struct DDS_SampleInfoSeq info_seq,
DDS_Long  max_samples,
DDS_SampleStateMask  sample_states,
DDS_ViewStateMask  view_states,
DDS_InstanceStateMask  instance_states 
)

Access a collection of data-samples from the DDS_DataReader.

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

  • In the case where the DDS_HistoryQosPolicy::kind is DDS_KEEP_LAST_HISTORY_QOS (currently the only supported configuration), the call will return at most DDS_HistoryQosPolicy::depth samples per instance.
  • The maximum number of samples returned is limited by DDS_ResourceLimitsQosPolicy::max_samples
  • For multiple instances, the number of samples returned is additionally limited by the product (DDS_ResourceLimitsQosPolicy::max_samples_per_instance * DDS_ResourceLimitsQosPolicy::max_instances ) If the read or take succeeds and the number of samples returned has been limited (by means of a maximum limit, as listed above, or insufficient DDS_SampleInfo resources), the call will complete successfully and provide those samples the reader is able to return. The user may need to make additional calls, or return outstanding loaned buffers in the case of insuffificient resources, in order to access remaining samples. Note that in the case where the DDS_Topic associated with the DDS_DataReader is bound to a data-type that has no key definition, then there will be at most one instance in the DDS_DataReader. So the per-sample limits will apply. The act of taking a sample removes it from RTI Connext Micro so it cannot be read or taken again. If the sample belongs to the most recent generation of the instance, it will also set the view_state of the sample's instance to DDS_NOT_NEW_VIEW_STATE. It will not affect the instance_state of the sample's instance. After 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 equal 0) when the FooDataReader_take is called, the samples returned in the received_data and the corresponding info_seq are 'loaned' to the application from buffers provided by the DDS_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 DDS_DataReader by calling the FooDataReader_return_loan operation. Note: While you must call FooDataReader_return_loan at some point, you do not have to do so before the next FooDataReader_take call. However, failure to return the loan will eventually deplete the DDS_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 DDS_DataReader is specified by the DDS_ResourceLimitsQosPolicy. If the sequences are not empty (maximum size not equal 0) when the FooDataReader_take is called, samples are copied to received_data and info_seq. The application will not need to call FooDataReader_return_loan. The samples returned to the caller is a list where samples belonging to the same data instance are consecutive (i.e. instance access scope). Samples belonging to the same instance will appear in the relative order in which there were received (i.e. reception timestamp destination order, where earlier samples are ahead of later samples). If the DDS_DataReader has no samples that meet the constraints, the function will fail with DDS_RETCODE_NO_DATA. In addition to the collection of samples, the read and take operations also use a collection of DDS_SampleInfo structures.

SEQUENCES USAGE IN TAKE AND READ

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

  • whether the collection container owns the memory of the elements within (owns, see FooSeq_has_ownership)
  • the current-length (len, see FooSeq_get_length)
  • the maximum length (max_len, see FooSeq_get_maximum) The initial values of the owns, len and max_len properties for the received_data and info_seq collections govern the behavior of the read and take operations as specified by the following rules:
    1. The values of owns, len and max_len properties for the two collections must be identical. Otherwise read/take will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
    2. On successful output, the values of owns, len and max_len will be the same for both collections.
    3. If the initial max_len==0, then the received_data and info_seq collections will be filled with elements that are loaned by the DDS_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 DDS_DataWriter using FooDataReader_return_loan.
    4. If the initial max_len>0 and owns==FALSE, then the read or take operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET. This avoids the potential hard-to-detect memory leaks caused by an application forgetting to return the loan.
    5. If initial max_len>0 and owns==TRUE, then the read or take operation will copy the received_data values and DDS_SampleInfo values into the elements already inside the collections. On output, owns will be TRUE, len will be set to the number of values copied and max_len will remain unchanged. The use of this variant forces a copy but the application can control where the copy is placed and the application will not need to return the loan. The number of samples copied depends on the relative values of max_len and max_samples:
      • If max_samples == LENGTH_UNLIMITED, then at most max_len values will be copied. The use of this variant lets the application limit the number of samples returned to what the sequence can accommodate.
      • If max_samples <= max_len, then at most max_samples values will be copied. The use of this variant lets the application limit the number of samples returned to fewer that what the sequence can accommodate.
      • If max_samples > max_len, then the read or take operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET. This avoids the potential confusion where the application expects to be able to access up to max_samples, but that number can never be returned, even if they are available in the DDS_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 DDS_DataReader. If this is the case, the application will need to use FooDataReader_return_loan to return the loan once it is no longer using the received_data in the collection. When FooDataReader_return_loan completes, the collection will have owns=FALSE and max_len=0. The application can determine whether it is necessary to return the loan or not based on how the state of the collections when the read/take operation was called or by accessing the owns property. However, in many cases it may be simpler to always call FooDataReader_return_loan, as this operation is harmless (i.e., it leaves all elements unchanged) if the collection does not have a loan. To avoid potential memory leaks, the implementation of the Foo and DDS_SampleInfo collections should disallow changing the length of a collection for which owns==FALSE. Furthermore, deleting a collection for which owns==FALSE should be considered an error. On output, the collection of Foo values and the collection of DDS_SampleInfo structures are of the same length and are in a one-to-one correspondence. Each DDS_SampleInfo provides information, such as the source_timestamp, the sample_state, view_state, and instance_state, etc., about the corresponding sample. Some elements in the returned collection may not have valid data. If the instance_state in the DDS_SampleInfo is DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE or DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE, then the last sample for that instance in the collection (that is, the one whose DDS_SampleInfo has sample_rank==0) does not contain valid data. Samples that contain no data do not count towards the limits imposed by the DDS_ResourceLimitsQosPolicy. The act of reading/taking a sample sets its sample_state to DDS_READ_SAMPLE_STATE. If the sample belongs to the most recent generation of the instance, it will also set the view_state of the instance to DDS_NOT_NEW_VIEW_STATE. It will not affect the instance_state of the instance. This operation must be provided on the specialized class that is generated for the particular application data-type that is being read (Foo). If the DDS_DataReader has no samples that meet the constraints, the operations fails with DDS_RETCODE_NO_DATA.
    Parameters:
    received_data<<inout>> User data type-specific FooSeq object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
    self<<in>> Cannot be NULL.
    info_seq<<inout>> A DDS_SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS_SampleInfoSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
    max_samples<<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available.
    sample_states<<in>> Data samples matching one of these sample_states are returned.
    view_states<<in>> Data samples matching one of these view_state are returned.
    instance_states<<in>> Data samples matching one of these instance_state are returned.
    Returns:
    One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.
    See also:
    FooDataReader_read
    DDS_LENGTH_UNLIMITED
DDS_ReturnCode_t FooDataReader_read_next_sample ( FooDataReader self,
struct Foo *  received_data,
struct DDS_SampleInfo sample_info 
)

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

This operation copies the next not-previously-accessed data value from the DDS_DataReader. This operation also copies the corresponding DDS_SampleInfo. The implied order among the samples stored in the DDS_DataReader is the same as for the FooDataReader_read operation. The FooDataReader_read_next_sample operation is semantically equivalent to the FooDataReader_read operation, where the input data sequences has max_len=1, the sample_states=NOT_READ, the view_states=ANY_VIEW_STATE, and the instance_states=ANY_INSTANCE_STATE. The FooDataReader_read_next_sample operation provides a simplified API to 'read' samples, avoiding the need for the application to manage sequences and specify states. If there is no unread data in the DDS_DataReader, the operation will fail with DDS_RETCODE_NO_DATA and nothing is copied.

Parameters:
self<<in>> Cannot be NULL.
received_data<<inout>> user data type-specific Foo object where the next received data sample will be returned. The received_data must have been fully allocated. Otherwise, this operation may fail. Must be a valid non-NULL Foo. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
sample_info<<inout>> a DDS_SampleInfo object where the next received sample info will be returned. Must be a valid non-NULL DDS_SampleInfo. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
Returns:
One of the Standard Return Codes, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.
See also:
FooDataReader_read
DDS_ReturnCode_t FooDataReader_take_next_sample ( FooDataReader self,
struct Foo *  received_data,
struct DDS_SampleInfo sample_info 
)

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

This operation copies the next not-previously-accessed data value from the DDS_DataReader and 'removes' it from the DDS_DataReader so that it is no longer accessible. This operation also copies the corresponding DDS_SampleInfo. This operation is analogous to the FooDataReader_read_next_sample except for the fact that the sample is removed from the DDS_DataReader. The FooDataReader_take_next_sample operation is semantically equivalent to the FooDataReader_take operation, where the input data sequences has max_len=1, the sample_states=NOT_READ, the view_states=ANY_VIEW_STATE, and the instance_states=ANY_INSTANCE_STATE. The FooDataReader_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 DDS_DataReader, the operation will fail with DDS_RETCODE_NO_DATA and nothing is copied.

Parameters:
self<<in>> Cannot be NULL.
received_data<<inout>> user data type-specific Foo object where the next received data sample will be returned. The received_data must have been fully allocated. Otherwise, this operation may fail. Must be a valid non-NULL Foo. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
sample_info<<inout>> a DDS_SampleInfo object where the next received sample info will be returned. Must be a valid non-NULL DDS_SampleInfo. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
Returns:
One of the Standard Return Codes, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.
See also:
FooDataReader_take
DDS_ReturnCode_t FooDataReader_read_instance ( FooDataReader self,
struct FooSeq received_data,
struct DDS_SampleInfoSeq info_seq,
DDS_Long  max_samples,
const DDS_InstanceHandle_t a_handle,
DDS_SampleStateMask  sample_states,
DDS_ViewStateMask  view_states,
DDS_InstanceStateMask  instance_states 
)

Access a collection of data samples from the DDS_DataReader.

This operation accesses a collection of data values from the DDS_DataReader. The behavior is identical to FooDataReader_read, except that all samples returned belong to the single specified instance whose handle is a_handle. Upon successful completion, the data collection will contain samples all belonging to the same instance. The corresponding DDS_SampleInfo verifies DDS_SampleInfo::instance_handle == a_handle. The FooDataReader_read_instance operation is semantically equivalent to the FooDataReader_read operation, except in building the collection, the DDS_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 FooDataReader_read_instance operation follows the same rules as the FooDataReader_read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to the FooDataReader_read, the FooDataReader_read_instance operation may 'loan' elements to the output collections, which must then be returned by means of FooDataReader_return_loan. Similar to the FooDataReader_read, this operation must be provided on the specialized class that is generated for the particular application data-type that is being taken. If the DDS_DataReader has no samples that meet the constraints, the function will fail with DDS_RETCODE_NO_DATA. This operation may fail with DDS_RETCODE_BAD_PARAMETER if the DDS_InstanceHandle_t a_handle does not correspond to an existing data-object known to the DDS_DataReader.

Parameters:
self<<in>> Cannot be NULL.
received_data<<inout>> user data type-specific FooSeq object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
info_seq<<inout>> a DDS_SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS_SampleInfoSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
max_samples<<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available.
a_handle<<in>> The specified instance to return samples for. Must be a valid non-NULL DDS_InstanceHandle_t. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL The function will fail with DDS_RETCODE_BAD_PARAMETER if the handle does not correspond to an existing data-object known to the DDS_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
Returns:
One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.
See also:
FooDataReader_read
DDS_LENGTH_UNLIMITED
DDS_ReturnCode_t FooDataReader_take_instance ( FooDataReader self,
struct FooSeq received_data,
struct DDS_SampleInfoSeq info_seq,
DDS_Long  max_samples,
const DDS_InstanceHandle_t a_handle,
DDS_SampleStateMask  sample_states,
DDS_ViewStateMask  view_states,
DDS_InstanceStateMask  instance_states 
)

Access a collection of data samples from the DDS_DataReader.

This operation accesses a collection of data values from the DDS_DataReader. The behavior is identical to FooDataReader_take, except for that all samples returned belong to the single specified instance whose handle is a_handle. The semantics are the same for the FooDataReader_take operation, except in building the collection, the DDS_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 FooDataReader_take_instance operation follows the same rules as the FooDataReader_read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to the FooDataReader_read, the FooDataReader_take_instance operation may 'loan' elements to the output collections, which must then be returned by means of FooDataReader_return_loan. Similar to the FooDataReader_read, this operation must be provided on the specialized class that is generated for the particular application data-type that is being taken. If the DDS_DataReader has no samples that meet the constraints, the function fails with DDS_RETCODE_NO_DATA. This operation may fail with DDS_RETCODE_BAD_PARAMETER if the DDS_InstanceHandle_t a_handle does not correspond to an existing data-object known to the DDS_DataReader.

Parameters:
self<<in>> Cannot be NULL.
received_data<<inout>> user data type-specific FooSeq object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
info_seq<<inout>> a DDS_SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS_SampleInfoSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
max_samples<<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available.
a_handle<<in>> The specified instance to return samples for. Must be a valid non-NULL DDS_InstanceHandle_t. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. The function will fail with DDS_RETCODE_BAD_PARAMETER if the handle does not correspond to an existing data-object known to the DDS_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
Returns:
One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.
See also:
FooDataReader_take
DDS_LENGTH_UNLIMITED
DDS_ReturnCode_t FooDataReader_return_loan ( FooDataReader self,
FooSeq received_data,
struct DDS_SampleInfoSeq info_seq 
)

Indicates to the DDS_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 DDS_DataReader.

This operation indicates to the DDS_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 DDS_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 DDS_DataReader to which they are returned. If either of these conditions is not met, the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET. The operation FooDataReader_return_loan allows implementations of the read and take operations to "loan" buffers from the DDS_DataReader to the application and in this manner provide "zerocopy" access to the data. During the loan, the DDS_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 DDS_DataReader, the application should not retain them indefinitely. The use of FooDataReader_return_loan is only necessary if the read or take calls "loaned" buffers to the application. This only occurs if the received_data and info_Seq collections had max_len=0 at the time read or take was called. The application may also examine the "owns" property of the collection to determine where there is an outstanding loan. However, calling FooDataReader_return_loan on a collection that does not have a loan is safe and has no side effects. If the collections had a loan, upon completion of FooDataReader_return_loan, the collections will have max_len=0. Similar to read, this operation must be provided on the specialized class that is generated for the particular application data-type that is being taken.

Parameters:
received_data<<in>> user data type-specific FooSeq object where the received data samples was obtained from earlier invocation of read or take on the DDS_DataReader. Must be a valid non-NULL FooSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
self<<in>> Cannot be NULL.
info_seq<<in>> a DDS_SampleInfoSeq object where the received sample info was obtained from earlier invocation of read or take on the DDS_DataReader. Must be a valid non-NULL DDS_SampleInfoSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
Returns:
One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_NOT_ENABLED.
DDS_InstanceHandle_t FooDataReader_lookup_instance ( FooDataReader self,
const Foo *  key_holder 
)

Retrieve 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:
self<<in>> Cannot be NULL.
key_holder<<in>> a user data type specific key holder.
Returns:
the instance handle associated with this instance. If Foo has no key, this function has no effect and returns DDS_HANDLE_NIL
DDS_ReturnCode_t DDS_DataReaderQos_initialize ( struct DDS_DataReaderQos self)

Initializer for new QoS instances.

New DDS_DataReaderQos instances on the heap should be initialized with this function before they are passed to any function . This step ensures that those contained QoS policies that use dynamic memory are properly initialized. This function does not allocate memory.

Parameters:
self<<in>> Cannot be NULL.
See also:
DDS_DataReaderQos_INITIALIZER
DDS_DataReaderQos_finalize
DDS_ReturnCode_t DDS_DataReaderQos_copy ( struct DDS_DataReaderQos self,
const struct DDS_DataReaderQos source 
)

Copy the contents of the given QoS into this QoS.

DDS_DataReaderQos instances can use dynamic memory because of the sequences contained in some QoS policies. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.

Parameters:
self<<in>> Cannot be NULL.
source<<in>>. Status to be copied from.
DDS_ReturnCode_t DDS_DataReaderQos_finalize ( struct DDS_DataReaderQos self)

Free any dynamic memory allocated by the policies in this DDS_DataReaderQos.

Some QoS policies may use dynamic memory (regardless of whether the QoS itself is in dynamic memory). This function frees that memory but otherwise leaves this QoS unchanged. It should be called on all instances before they are freed (or, in the case of stack-based instances, before they go out of scope). This function does not leave this object in an invalid state. It is permissable to clear a QoS and then subsequently allocate new dynamic memory in one or more of its QoS policies. Note that if this QoS instance is stored in heap memory, calling this function will not call free() on it; the user is responsible for explicitly freeing any heap-based QoS instance after calling this function .

Parameters:
self<<in>> Cannot be NULL.
DDS_Entity* DDS_DataReader_as_entity ( DDS_DataReader dataReader)

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

Parameters:
dataReader<<in>> Cannot be NULL.
DDS_ReturnCode_t DDS_DataReader_enable ( DDS_Entity self)

Enables a DDS_DataReader instance.

Parameters:
self<<in>> Cannot be NULL.
Returns:
One of the Standard Return Codes
See also:
DDS_Entity_enable
DDS_ReturnCode_t DDS_DataReader_get_matched_publications ( DDS_DataReader self,
struct DDS_InstanceHandleSeq *  publication_handles 
)

Retrieve the list of publications currently "associated" with this DDS_DataReader.

Matching publications are those in the same domain that have a matching DDS_Topic, and compatible QoS common partition. The handles returned in the publication_handles' list are the ones that are used by the DDS implementation to locally identify the corresponding matched DDS_DataWriter entities. These handles match the ones that appear in the instance_handle field of the DDS_SampleInfo when reading the DDS_PUBLICATION_TOPIC_NAME builtin topic

Parameters:
self<<in>> Cannot be NULL.
publication_handlesinout. The sequence will be grown if the sequence has ownership and the system has the corresponding resources. Use a sequence without ownership to avoid dynamic memory allocation. If the sequence is too small to store all the matches and the system can not resize the sequence, this function will fail with DDS_RETCODE_OUT_OF_RESOURCES. The maximum number of matches possible is configured with DDS_DomainParticipantResourceLimitsQosPolicy. You can use a zero-maximum sequence without ownership to quickly check whether there are any matches without allocating any memory. Cannot be NULL..
Returns:
One of the Standard Return Codes, or DDS_RETCODE_OUT_OF_RESOURCES if the sequence is too small and the system can not resize it, or DDS_RETCODE_NOT_ENABLED
DDS_ReturnCode_t DDS_DataReader_get_matched_publication_data ( DDS_DataReader self,
struct DDS_PublicationBuiltinTopicData publication_data,
const DDS_InstanceHandle_t publication_handle 
)

This operation retrieves the information on a publication that is currently "associated" with the DDS_DataReader.

Publication with a matching DDS_Topic, compatible QoS and common partition. The publication_handle must correspond to a publication currently associated with the DDS_DataReader. Otherwise, the operation will fail with DDS_RETCODE_BAD_PARAMETER. Use the operation DDS_DataReader_get_matched_publications to find the publications that are currently matched with the DDS_DataReader.

Parameters:
self<<in>> Cannot be NULL.
publication_data<<inout>>. The information to be filled in on the associated publication. Cannot be NULL.
publication_handle<<in>>. Handle to a specific publication associated with the DDS_DataWriter. Cannot be NULL.. Must correspond to a publication currently associated with the DDS_DataReader.
Returns:
One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED
DDS_TopicDescription* DDS_DataReader_get_topicdescription ( DDS_DataReader self)

<<cert>> Returns the DDS_TopicDescription associated with the DDS_DataReader.

Returns that same DDS_TopicDescription that was used to create the DDS_DataReader.

Parameters:
self<<in>> Cannot be NULL.
Returns:
DDS_TopicDescription associated with the DDS_DataReader.
DDS_Subscriber* DDS_DataReader_get_subscriber ( DDS_DataReader self)

<<cert>> Returns the DDS_Subscriber to which the DDS_DataReader belongs.

Parameters:
self<<in>> Cannot be NULL.
Returns:
DDS_Subscriber to which the DDS_DataReader belongs.
DDS_ReturnCode_t DDS_DataReader_get_sample_rejected_status ( DDS_DataReader self,
struct DDS_SampleRejectedStatus status 
)

<<cert>> Accesses the DDS_SAMPLE_REJECTED_STATUS communication status.

Parameters:
self<<in>> Cannot be NULL.
status<<inout>> DDS_SampleRejectedStatus to be filled in. Cannot be NULL.
Returns:
One of the Standard Return Codes
DDS_ReturnCode_t DDS_DataReader_get_liveliness_changed_status ( DDS_DataReader self,
struct DDS_LivelinessChangedStatus status 
)

<<cert>> Accesses the DDS_LIVELINESS_CHANGED_STATUS communication status.

Parameters:
self<<in>> Cannot be NULL.
status<<inout>> DDS_LivelinessChangedStatus to be filled in. Cannot be NULL.
Returns:
One of the Standard Return Codes
DDS_ReturnCode_t DDS_DataReader_get_requested_deadline_missed_status ( DDS_DataReader self,
struct DDS_RequestedDeadlineMissedStatus status 
)

<<cert>> Accesses the DDS_REQUESTED_DEADLINE_MISSED_STATUS communication status.

Parameters:
self<<in>> Cannot be NULL.
status<<inout>> DDS_RequestedDeadlineMissedStatus to be filled in. Cannot be NULL.
Returns:
One of the Standard Return Codes
DDS_ReturnCode_t DDS_DataReader_get_requested_incompatible_qos_status ( DDS_DataReader self,
struct DDS_RequestedIncompatibleQosStatus status 
)

<<cert>> Accesses the DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS communication status.

Parameters:
self<<in>> Cannot be NULL.
status<<inout>> DDS_RequestedIncompatibleQosStatus to be filled in. Cannot be NULL.
Returns:
One of the Standard Return Codes
DDS_ReturnCode_t DDS_DataReader_get_subscription_matched_status ( DDS_DataReader self,
struct DDS_SubscriptionMatchedStatus status 
)

<<cert>> Accesses the DDS_SUBSCRIPTION_MATCHED_STATUS communication status.

Parameters:
self<<in>> Cannot be NULL.
status<<inout>> DDS_SubscriptionMatchedStatus to be filled in. Cannot be NULL.
Returns:
One of the Standard Return Codes
DDS_ReturnCode_t DDS_DataReader_get_sample_lost_status ( DDS_DataReader self,
struct DDS_SampleLostStatus status 
)

<<cert>> Accesses the DDS_SAMPLE_LOST_STATUS communication status.

Parameters:
self<<in>> Cannot be NULL.
status<<inout>> DDS_SampleLostStatus to be filled in. Cannot be NULL.
Returns:
One of the Standard Return Codes
DDS_ReturnCode_t DDS_DataReader_get_instance_replaced_status ( DDS_DataReader self,
struct DDS_DataReaderInstanceReplacedStatus status 
)

<<cert>> Accesses the DDS_INSTANCE_REPLACED_STATUS communication status.

Parameters:
self<<in>> Cannot be NULL.
status<<inout>> DDS_DataReaderInstanceReplacedStatus to be filled in. Cannot be NULL.
Returns:
One of the Standard Return Codes
DDS_ReturnCode_t DDS_DataReader_set_qos ( DDS_DataReader self,
const struct DDS_DataReaderQos qos 
)

Sets the reader QoS.

This operation modifies the QoS of the DDS_DataReader. The DDS_DataReaderQos::deadline can be changed. The other policies are immutable.

Parameters:
self<<in>> Cannot be NULL.
qos<<in>> The DDS_DataReaderQos to be set to. Policies must be consistent. Policies cannot be changed after DDS_DataReader is enabled. The special value DDS_DATAREADER_QOS_DEFAULT can be used to indicate that the QoS of the DDS_DataReader should be changed to match the current default DDS_DataReaderQos set in the DDS_Subscriber. Cannot be NULL.
Returns:
One of the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY, or DDS_RETCODE_INCONSISTENT_POLICY.
See also:
DDS_DataReaderQos for rules on consistency among QoS
set_qos (abstract)
DDS_DataReader_set_qos
DDS_ReturnCode_t DDS_DataReader_get_qos ( DDS_DataReader self,
struct DDS_DataReaderQos qos 
)

Gets the reader QoS.

This function may potentially allocate memory depending on the sequences contained in some QoS policies.

Parameters:
self<<in>> Cannot be NULL.
qos<<inout>> The DDS_DataReaderQos to be filled up. Cannot be NULL.
Returns:
One of the Standard Return Codes
See also:
get_qos (abstract)
DDS_ReturnCode_t DDS_DataReader_set_listener ( DDS_DataReader self,
const struct DDS_DataReaderListener l,
DDS_StatusMask  mask 
)

Sets the reader listener.

Parameters:
self<<in>> Cannot be NULL.
l<<in>> DDS_DataReaderListener to set to
mask<<in>> DDS_StatusMask associated with the DDS_DataReaderListener. The callback function on the listener cannot be NULL if the corresponding status is turned on in the mask.
Returns:
One of the Standard Return Codes
See also:
set_listener (abstract)
struct DDS_DataReaderListener DDS_DataReader_get_listener ( DDS_DataReader self)
read

Get the reader listener.

Parameters:
self<<in>> Cannot be NULL.
Returns:
DDS_DataReaderListener of the DDS_DataReader.
DDS_ReturnCode_t DDS_DataReader_read ( DDS_DataReader self,
struct DDS_UntypedSampleSeq *  received_data,
struct DDS_SampleInfoSeq info_seq,
DDS_Long  max_samples,
DDS_SampleStateMask  sample_states,
DDS_ViewStateMask  view_states,
DDS_InstanceStateMask  instance_states 
)

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

This operation offers the same functionality and API as DDS_DataReader_take except that the samples returned remain in the DDS_DataReader such that they can be retrieved again by means of a read or take operation. Please refer to the documentation of DDS_DataReader_take() for details on the number of samples returned within the received_data and info_seq as well as the order in which the samples appear in these sequences. The act of reading a sample changes its sample_state to DDS_READ_SAMPLE_STATE. If the sample belongs to the most recent generation of the instance, it will also set the view_state of the instance to be DDS_NOT_NEW_VIEW_STATE. It will not affect the instance_state of the instance. Important: If the samples "returned" by this function are loaned from RTI Connext Micro (see DDS_DataReader_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:
self<<in>> Cannot be NULL.
received_data<<inout>> User data untyped pointer where the received data samples will be returned. Must be a valid non-NULL pointer. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
info_seq<<inout>> A DDS_SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS_SampleInfoSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
max_samples<<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available.
sample_states<<in>> Data samples matching one of these sample_states are returned.
view_states<<in>> Data samples matching one of these view_state are returned.
instance_states<<in>> Data samples matching ones of these instance_state are returned.
Returns:
One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.
See also:
DDS_DataReader_take,
DDS_LENGTH_UNLIMITED
DDS_ReturnCode_t DDS_DataReader_take ( DDS_DataReader self,
struct DDS_UntypedSampleSeq *  received_data,
struct DDS_SampleInfoSeq info_seq,
DDS_Long  max_samples,
DDS_SampleStateMask  sample_states,
DDS_ViewStateMask  view_states,
DDS_InstanceStateMask  instance_states 
)

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

The operation will return the list of samples received by the DDS_DataReader since the last DDS_DataReader_take operation that match the specified DDS_SampleStateMask, DDS_ViewStateMask and DDS_InstanceStateMask. This operation may fail with DDS_RETCODE_ERROR if DDS_DataReaderResourceLimitsQosPolicy::max_outstanding_reads limit has been exceeded. The actual number of samples returned depends on the information that has been received by the middleware as well as the DDS_HistoryQosPolicy, DDS_ResourceLimitsQosPolicy, DDS_DataReaderResourceLimitsQosPolicy and the characteristics of the data-type that is associated with the DDS_DataReader:

SEQUENCES USAGE IN TAKE AND READ

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

  • whether the collection container owns the memory of the elements within (owns, see FooSeq_has_ownership)
  • the current-length (len, see FooSeq_get_length)
  • the maximum length (max_len, see FooSeq_get_maximum) The initial values of the owns, len and max_len properties for the received_data and info_seq collections govern the behavior of the read and take operations as specified by the following rules:
    1. The values of owns, len and max_len properties for the two collections must be identical. Otherwise read/take will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
    2. On successful output, the values of owns, len and max_len will be the same for both collections.
    3. If the initial max_len==0, then the received_data and info_seq collections will be filled with elements that are loaned by the DDS_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 DDS_DataWriter using FooDataReader_return_loan.
    4. If the initial max_len>0 and owns==FALSE, then the read or take operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET. This avoids the potential hard-to-detect memory leaks caused by an application forgetting to return the loan.
    5. If initial max_len>0 and owns==TRUE, then the read or take operation will copy the received_data values and DDS_SampleInfo values into the elements already inside the collections. On output, owns will be TRUE, len will be set to the number of values copied and max_len will remain unchanged. The use of this variant forces a copy but the application can control where the copy is placed and the application will not need to return the loan. The number of samples copied depends on the relative values of max_len and max_samples:
      • If max_samples == LENGTH_UNLIMITED, then at most max_len values will be copied. The use of this variant lets the application limit the number of samples returned to what the sequence can accommodate.
      • If max_samples <= max_len, then at most max_samples values will be copied. The use of this variant lets the application limit the number of samples returned to fewer that what the sequence can accommodate.
      • If max_samples > max_len, then the read or take operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET. This avoids the potential confusion where the application expects to be able to access up to max_samples, but that number can never be returned, even if they are available in the DDS_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 DDS_DataReader. If this is the case, the application will need to use DDS_DataReader_return_loan to return the loan once it is no longer using the received_data in the collection. When DDS_DataReader_return_loan completes, the collection will have owns=FALSE and max_len=0. The application can determine whether it is necessary to return the loan or not based on how the state of the collections when the read/take operation was called or by accessing the owns property. However, in many cases it may be simpler to always call DDS_DataReader_return_loan, as this operation is harmless (i.e., it leaves all elements unchanged) if the collection does not have a loan. To avoid potential memory leaks, the implementation of the Foo and DDS_SampleInfo collections should disallow changing the length of a collection for which owns==FALSE. Furthermore, deleting a collection for which owns==FALSE should be considered an error. On output, the collection of Foo values and the collection of DDS_SampleInfo structures are of the same length and are in a one-to-one correspondence. Each DDS_SampleInfo provides information, such as the source_timestamp, the sample_state, view_state, and instance_state, etc., about the corresponding sample. Some elements in the returned collection may not have valid data. If the instance_state in the DDS_SampleInfo is DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE or DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE, then the last sample for that instance in the collection (that is, the one whose DDS_SampleInfo has sample_rank==0) does not contain valid data. Samples that contain no data do not count towards the limits imposed by the DDS_ResourceLimitsQosPolicy. The act of reading/taking a sample sets its sample_state to DDS_READ_SAMPLE_STATE. If the sample belongs to the most recent generation of the instance, it will also set the view_state of the instance to DDS_NOT_NEW_VIEW_STATE. It will not affect the instance_state of the instance. This operation must be provided on the specialized class that is generated for the particular application data-type that is being read . If the DDS_DataReader has no samples that meet the constraints, the operations fails with DDS_RETCODE_NO_DATA.
    Parameters:
    received_data<<inout>> User data untyped pointer where the received data samples will be returned. Must be a valid non-NULL FooSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
    self<<in>> Cannot be NULL.
    info_seq<<inout>> A DDS_SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS_SampleInfoSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
    max_samples<<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available.
    sample_states<<in>> Data samples matching one of these sample_states are returned.
    view_states<<in>> Data samples matching one of these view_state are returned.
    instance_states<<in>> Data samples matching one of these instance_state are returned.
    Returns:
    One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.
    See also:
    DDS_DataReader_read
DDS_ReturnCode_t DDS_DataReader_read_next_sample ( DDS_DataReader self,
void *  received_data,
struct DDS_SampleInfo sample_info 
)

<<cert>> Copies the next not-previously-accessed data value from the DDS_DataReader.

This operation copies the next not-previously-accessed data value from the DDS_DataReader. This operation also copies the corresponding DDS_SampleInfo. The implied order among the samples stored in the DDS_DataReader is the same as for the DDS_DataReader_read operation. The DDS_DataReader_read_next_sample operation is semantically equivalent to the DDS_DataReader_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 DDS_DataReader_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 DDS_DataReader, the operation will fail with DDS_RETCODE_NO_DATA and nothing is copied.

Parameters:
self<<in>> Cannot be NULL.
received_data<<inout>> user data type-specific data object where the next received data sample will be returned. The received_data must have been fully allocated. Otherwise, this operation may fail. Must be a valid non-NULL Data. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
sample_info<<inout>> a DDS_SampleInfo object where the next received sample info will be returned. Must be a valid non-NULL DDS_SampleInfo. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
Returns:
One of the Standard Return Codes, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.
See also:
DDS_DataReader_read
DDS_ReturnCode_t DDS_DataReader_take_next_sample ( DDS_DataReader self,
void *  received_data,
struct DDS_SampleInfo sample_info 
)

<<cert>> Copies the next not-previously-accessed data value from the DDS_DataReader.

This operation copies the next not-previously-accessed data value from the DDS_DataReader and 'removes' it from the DDS_DataReader so that it is no longer accessible. This operation also copies the corresponding DDS_SampleInfo. This operation is analogous to the DDS_DataReader_read_next_sample except for the fact that the sample is removed from the DDS_DataReader. The DDS_DataReader_take_next_sample operation is semantically equivalent to the DDS_DataReader_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 DDS_DataReader_take_next_sample operation provides a simplified API to 'take' samples, avoiding the need for the application to manage sequences and specify states. If there is no unread data in the DDS_DataReader, the operation will fail with DDS_RETCODE_NO_DATA and nothing is copied.

Parameters:
self<<in>> Cannot be NULL.
received_data<<inout>> user data type-specific Data object where the next received data sample will be returned. The received_data must have been fully allocated. Otherwise, this operation may fail. Must be a valid non-NULL Data. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
sample_info<<inout>> a DDS_SampleInfo object where the next received sample info will be returned. Must be a valid non-NULL DDS_SampleInfo. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
Returns:
One of the Standard Return Codes, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.
See also:
DDS_DataReader_take
DDS_ReturnCode_t DDS_DataReader_read_instance ( DDS_DataReader self,
struct DDS_UntypedSampleSeq *  received_data,
struct DDS_SampleInfoSeq info_seq,
DDS_Long  max_samples,
const DDS_InstanceHandle_t a_handle,
DDS_SampleStateMask  sample_states,
DDS_ViewStateMask  view_states,
DDS_InstanceStateMask  instance_states 
)

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

Parameters:
self<<in>> Cannot be NULL.
received_data<<inout>> User data untyped pointer where the received data samples will be returned. Must be a valid non-NULL pointer. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
info_seq<<inout>> A DDS_SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS_SampleInfoSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
max_samples<<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available.
a_handle<<in>> Instance for which data samples should be read
sample_states<<in>> Data samples matching one of these sample_states are returned.
view_states<<in>> Data samples matching one of these view_state are returned.
instance_states<<in>> Data samples matching ones of these instance_state are returned.
Returns:
One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.
See also:
DDS_DataReader_read,
DDS_LENGTH_UNLIMITED
DDS_ReturnCode_t DDS_DataReader_take_instance ( DDS_DataReader self,
struct DDS_UntypedSampleSeq *  received_data,
struct DDS_SampleInfoSeq info_seq,
DDS_Long  max_samples,
const DDS_InstanceHandle_t a_handle,
DDS_SampleStateMask  sample_states,
DDS_ViewStateMask  view_states,
DDS_InstanceStateMask  instance_states 
)

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

Parameters:
self<<in>> Cannot be NULL.
received_data<<inout>> User data untyped pointer where the received data samples will be returned. Must be a valid non-NULL pointer. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
info_seq<<inout>> A DDS_SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS_SampleInfoSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
max_samples<<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available.
a_handle<<in>> Instance for which data samples should be read
sample_states<<in>> Data samples matching one of these sample_states are returned.
view_states<<in>> Data samples matching one of these view_state are returned.
instance_states<<in>> Data samples matching ones of these instance_state are returned.
Returns:
One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.
See also:
DDS_DataReader_take,
DDS_LENGTH_UNLIMITED
DDS_ReturnCode_t DDS_DataReader_return_loan ( DDS_DataReader self,
struct DDS_UntypedSampleSeq *  received_data,
struct DDS_SampleInfoSeq info_seq 
)

<<cert>> Indicates to the DDS_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 DDS_DataReader.

This operation indicates to the DDS_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 DDS_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 DDS_DataReader to which they are returned. If either of these conditions is not met, the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET. The operation DDS_DataReader_return_loan allows implementations of the read and take operations to "loan" buffers from the DDS_DataReader to the application and in this manner provide "zerocopy" access to the data. During the loan, the DDS_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 DDS_DataReader, the application should not retain them indefinitely. The use of DDS_DataReader_return_loan is only necessary if the read or take calls "loaned" buffers to the application. This only occurs if the received_data and info_Seq collections had max_len=0 at the time read or take was called. The application may also examine the "owns" property of the collection to determine where there is an outstanding loan. However, calling DDS_DataReader_return_loan on a collection that does not have a loan is safe and has no side effects. If the collections had a loan, upon completion of DDS_DataReader_return_loan, the collections will have max_len=0.

Parameters:
received_data<<in>> user data type-specific FooSeq object where the received data samples was obtained from earlier invocation of read or take on the DDS_DataReader. Must be a valid non-NULL FooSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
self<<in>> Cannot be NULL.
info_seq<<in>> a DDS_SampleInfoSeq object where the received sample info was obtained from earlier invocation of read or take on the DDS_DataReader. Must be a valid non-NULL DDS_SampleInfoSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
Returns:
One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_NOT_ENABLED.
DDS_InstanceHandle_t DDS_DataReader_lookup_instance ( DDS_DataReader self,
const void *  key_holder 
)

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

Parameters:
self<<in>> Cannot be NULL.
key_holder<<in>> A data sample containing the desired values for key attributes.
Returns:
The DDS_InstanceHandle_t for the selected instance or DDS_HANDLE_NIL if the instance was not found or an error occurred.

RTI Connext DDS Micro Version 2.4.11 Copyright © Mon Jul 23 2018 Real-Time Innovations, Inc