RTI Connext Traditional C++ API  Version 7.0.0

DDSDataReader entity and associated elements More...

Modules

 Read Conditions
 DDSReadCondition and associated elements
 
 Query Conditions
 DDSQueryCondition and associated elements
 
 Topic Queries
 DDSTopicQuery and associated elements.
 

Classes

struct  DDS_RequestedDeadlineMissedStatus
 DDS_REQUESTED_DEADLINE_MISSED_STATUS More...
 
struct  DDS_LivelinessChangedStatus
 DDS_LIVELINESS_CHANGED_STATUS More...
 
struct  DDS_RequestedIncompatibleQosStatus
 DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS More...
 
struct  DDS_SampleLostStatus
 DDS_SAMPLE_LOST_STATUS More...
 
struct  DDS_SampleRejectedStatus
 DDS_SAMPLE_REJECTED_STATUS More...
 
struct  DDS_SubscriptionMatchedStatus
 DDS_SUBSCRIPTION_MATCHED_STATUS More...
 
struct  DDS_DataReaderCacheStatus
 <<extension>> The status of the reader's cache. More...
 
struct  DDS_DataReaderProtocolStatus
 <<extension>> The status of a reader's internal protocol related metrics, like the number of samples received, filtered, rejected; and status of wire protocol traffic. More...
 
struct  DDS_DataReaderQos
 QoS policies supported by a DDSDataReader entity. More...
 
class  FooDataReader
 <<interface>> <<generic>> User data type-specific data reader. More...
 
class  DDSDataReaderSeq
 Declares IDL sequence < DDSDataReader > . More...
 
class  DDSDataReaderListener
 <<interface>> DDSListener for reader status. More...
 
class  DDSDataReader
 <<interface>> Allows the application to: (1) declare the data it wishes to receive (i.e. make a subscription) and (2) access the data received by the attached DDSSubscriber. More...
 

Enumerations

enum  DDS_SampleLostStatusKind {
  DDS_NOT_LOST = 0,
  DDS_LOST_BY_WRITER = 1,
  DDS_LOST_BY_INSTANCES_LIMIT = 2,
  DDS_LOST_BY_REMOTE_WRITERS_PER_INSTANCE_LIMIT = 3,
  DDS_LOST_BY_INCOMPLETE_COHERENT_SET = 4,
  DDS_LOST_BY_LARGE_COHERENT_SET = 5,
  DDS_LOST_BY_SAMPLES_PER_REMOTE_WRITER_LIMIT = 6,
  DDS_LOST_BY_VIRTUAL_WRITERS_LIMIT = 7,
  DDS_LOST_BY_REMOTE_WRITERS_PER_SAMPLE_LIMIT = 8,
  DDS_LOST_BY_AVAILABILITY_WAITING_TIME = 9,
  DDS_LOST_BY_REMOTE_WRITER_SAMPLES_PER_VIRTUAL_QUEUE_LIMIT = 10,
  DDS_LOST_BY_OUT_OF_MEMORY = 11,
  DDS_LOST_BY_UNKNOWN_INSTANCE = 12,
  DDS_LOST_BY_DESERIALIZATION_FAILURE = 13,
  DDS_LOST_BY_DECODE_FAILURE = 14,
  DDS_LOST_BY_SAMPLES_PER_INSTANCE_LIMIT = 15,
  DDS_LOST_BY_SAMPLES_LIMIT = 16
}
 <<extension>> Kinds of reasons why a sample was lost. More...
 
enum  DDS_SampleRejectedStatusKind {
  DDS_NOT_REJECTED = 0,
  DDS_REJECTED_BY_INSTANCES_LIMIT = 1,
  DDS_REJECTED_BY_SAMPLES_LIMIT = 2,
  DDS_REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT = 3,
  DDS_REJECTED_BY_SAMPLES_PER_REMOTE_WRITER_LIMIT = 6,
  DDS_REJECTED_BY_REMOTE_WRITER_SAMPLES_PER_VIRTUAL_QUEUE_LIMIT = 9,
  DDS_REJECTED_BY_DECODE_FAILURE = 10
}
 Kinds of reasons for rejecting a sample. More...
 

Functions

DDS_Boolean DDS_DataReaderQos_equals (const struct DDS_DataReaderQos *self, const struct DDS_DataReaderQos *other)
 Compares two DDS_DataReaderQos for equality. More...
 
DDS_ReturnCode_t DDS_DataReaderQos::print () const
 Prints this DDS_DataReaderQos to stdout. More...
 
DDS_ReturnCode_t DDS_DataReaderQos::to_string (char *string, DDS_UnsignedLong &string_size) const
 Obtains a string representation of this DDS_DataReaderQos. More...
 
DDS_ReturnCode_t DDS_DataReaderQos::to_string (char *string, DDS_UnsignedLong &string_size, const DDS_DataReaderQos &base) const
 Obtains a string representation of this DDS_DataReaderQos. More...
 
DDS_ReturnCode_t DDS_DataReaderQos::to_string (char *string, DDS_UnsignedLong &string_size, const DDS_QosPrintFormat &format) const
 Obtains a string representation of this DDS_DataReaderQos. More...
 
DDS_ReturnCode_t DDS_DataReaderQos::to_string (char *string, DDS_UnsignedLong &string_size, const DDS_DataReaderQos &base, const DDS_QosPrintFormat &format) const
 Obtains a string representation of this DDS_DataReaderQos. More...
 
DDS_ReturnCode_t DDS_DataReaderQos::to_string (char *string, DDS_UnsignedLong &string_size, const DDS_QosPrintAll_t &) const
 Obtains a string representation of this DDS_DataReaderQos. More...
 
DDS_ReturnCode_t DDS_DataReaderQos::to_string (char *string, DDS_UnsignedLong &string_size, const DDS_QosPrintAll_t &, const DDS_QosPrintFormat &format) const
 Obtains a string representation of this DDS_DataReaderQos. More...
 

Detailed Description

DDSDataReader entity and associated elements

Enumeration Type Documentation

◆ DDS_SampleLostStatusKind

<<extension>> Kinds of reasons why a sample was lost.

MONITOR-273 We assign an integer to the names in order to be compatible with the DDSMonitoring types.

Enumerator
DDS_NOT_LOST 

The sample was not lost.

This constant is an extension to the DDS standard.

DDS_LOST_BY_WRITER 

A DDSDataWriter removed the sample before being received by the DDSDataReader.

This constant is an extension to the DDS standard.

DDS_LOST_BY_INSTANCES_LIMIT 

A resource limit on the number of instances (DDS_ResourceLimitsQosPolicy::max_instances) was reached.

This constant is an extension to the DDS standard.

See also
DDS_ResourceLimitsQosPolicy
DDS_LOST_BY_REMOTE_WRITERS_PER_INSTANCE_LIMIT 

A resource limit on the number of remote writers for a single instance from which a DDSDataReader may read (DDS_DataReaderResourceLimitsQosPolicy::max_remote_writers_per_instance) was reached.

This constant is an extension to the DDS standard.

See also
DDS_DataReaderResourceLimitsQosPolicy
DDS_LOST_BY_INCOMPLETE_COHERENT_SET 

A sample is lost because it is part of an incomplete coherent set. An incomplete coherent set is a coherent set for which some of the samples are missing.

For example, consider a DDSDataWriter using DDS_KEEP_LAST_HISTORY_QOS with a depth of 1. The DataWriter publishes two samples of the same instance as part of a coherent set 'CS1'; the first sample of 'CS1' is replaced by a new sample before it can be successfully delivered to the DDSDataReader. In this case, the coherent set containing the two samples is considered incomplete. The new sample, by default, will not be provided to the application, and will be reported as LOST_BY_INCOMPLETE_COHERENT_SET. (You can change this default behavior by setting DDS_PresentationQosPolicy::drop_incomplete_coherent_set to FALSE. If you do, the new sample will be provided to the application, but it will be marked as part of an incomplete coherent set in the DDS_SampleInfo structure.)

This constant is an extension to the DDS standard.

DDS_LOST_BY_LARGE_COHERENT_SET 

A sample is lost because it is part of a large coherent set. A large coherent set is a coherent set that cannot fit all at once into the DDSDataReader queue because resource limits are exceeded.

For example, if DDS_ResourceLimitsQosPolicy::max_samples_per_instance on the DataReader is 10 and the coherent set has 15 samples for a given instance, the coherent set is a large coherent set that will be considered incomplete.

The resource limits that can lead to large coherent sets are: DDS_ResourceLimitsQosPolicy::max_samples, DDS_ResourceLimitsQosPolicy::max_samples_per_instance, DDS_ResourceLimitsQosPolicy::max_instances, and DDS_DataReaderResourceLimitsQosPolicy::max_samples_per_remote_writer.

This constant is an extension to the DDS standard.

DDS_LOST_BY_SAMPLES_PER_REMOTE_WRITER_LIMIT 

When using DDS_BEST_EFFORT_RELIABILITY_QOS: a resource limit on the number of samples from a given remote writer that a DDSDataReader may store (DDS_DataReaderResourceLimitsQosPolicy::max_samples_per_remote_writer) was reached. When using DDS_RELIABLE_RELIABILITY_QOS, reaching DDS_DataReaderResourceLimitsQosPolicy::max_samples_per_remote_writer will trigger a rejection, not a loss, with reason DDS_REJECTED_BY_SAMPLES_PER_REMOTE_WRITER_LIMIT.

This constant is an extension to the DDS standard.

See also
DDS_DataReaderResourceLimitsQosPolicy
DDS_LOST_BY_VIRTUAL_WRITERS_LIMIT 

A resource limit on the number of virtual writers from which a DDSDataReader may read (DDS_DataReaderResourceLimitsQosPolicy::max_remote_virtual_writers) was reached.

This constant is an extension to the DDS standard.

See also
DDS_DataReaderResourceLimitsQosPolicy
DDS_LOST_BY_REMOTE_WRITERS_PER_SAMPLE_LIMIT 

A resource limit on the number of remote writers per sample (DDS_DataReaderResourceLimitsQosPolicy::max_remote_writers_per_sample) was reached.

This constant is an extension to the DDS standard.

See also
DDS_DataReaderResourceLimitsQosPolicy
DDS_LOST_BY_AVAILABILITY_WAITING_TIME 

DDS_AvailabilityQosPolicy::max_data_availability_waiting_time expired.

This constant is an extension to the DDS standard.

See also
DDS_AvailabilityQosPolicy
DDS_LOST_BY_REMOTE_WRITER_SAMPLES_PER_VIRTUAL_QUEUE_LIMIT 

A resource limit on the number of samples published by a remote writer on behalf of a virtual writer that a DDSDataReader may store was reached. (This field is currently not used.)

This constant is an extension to the DDS standard.

See also
DDS_DataReaderResourceLimitsQosPolicy
DDS_LOST_BY_OUT_OF_MEMORY 

A sample was lost because there was not enough memory to store the sample.

This constant is an extension to the DDS standard.

See also
DDS_DataReaderResourceLimitsQosPolicy
DDS_LOST_BY_UNKNOWN_INSTANCE 

A received sample was lost because it doesn't contain enough information for the reader to know what instance it is associated with.

This constant is an extension to the DDS standard.

DDS_LOST_BY_DESERIALIZATION_FAILURE 

A received sample was lost because it could not be deserialized.

This constant is an extension to the DDS standard.

DDS_LOST_BY_DECODE_FAILURE 

When using DDS_BEST_EFFORT_RELIABILITY_QOS: A received sample was lost because it could not be decoded. When using DDS_RELIABLE_RELIABILITY_QOS, the sample will be rejected, not lost, with reason DDS_REJECTED_BY_DECODE_FAILURE.

This constant is an extension to the DDS standard.

DDS_LOST_BY_SAMPLES_PER_INSTANCE_LIMIT 

When using DDS_BEST_EFFORT_RELIABILITY_QOS: A resource limit on the number of samples per instance (DDS_ResourceLimitsQosPolicy::max_samples_per_instance) was reached. When using DDS_RELIABLE_RELIABILITY_QOS, reaching DDS_ResourceLimitsQosPolicy::max_samples_per_instance will trigger a rejection, not a loss, with reason DDS_REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT.

This constant is an extension to the DDS standard.

See also
DDS_ResourceLimitsQosPolicy
DDS_LOST_BY_SAMPLES_LIMIT 

When using DDS_BEST_EFFORT_RELIABILITY_QOS: A resource limit on the number of samples (DDS_ResourceLimitsQosPolicy::max_samples) was reached. When using DDS_RELIABLE_RELIABILITY_QOS, reaching DDS_ResourceLimitsQosPolicy::max_samples will trigger a rejection, not a loss, with reason DDS_REJECTED_BY_SAMPLES_LIMIT.

This constant is an extension to the DDS standard.

See also
DDS_ResourceLimitsQosPolicy

◆ DDS_SampleRejectedStatusKind

Kinds of reasons for rejecting a sample.

MONITOR-273 We assign an integer to the names in order to be compatible with the DDSMonitoring types.

Enumerator
DDS_NOT_REJECTED 

The sample was not rejected.

DDS_REJECTED_BY_INSTANCES_LIMIT 

Connext DDS does not reject samples based on instance limits (DDS_ResourceLimitsQosPolicy::max_instances), so this value will never be used.

See also
DDS_LOST_BY_INSTANCES_LIMIT

This value is not currently used by our middleware, but has been kept because it is part of the DDS specification.

DDS_REJECTED_BY_SAMPLES_LIMIT 

When using DDS_RELIABLE_RELIABILITY_QOS: A resource limit on the number of samples (DDS_ResourceLimitsQosPolicy::max_samples) was reached. When using DDS_BEST_EFFORT_RELIABILITY_QOS, reaching DDS_ResourceLimitsQosPolicy::max_samples will trigger a loss, not a rejection, with reason DDS_LOST_BY_SAMPLES_LIMIT.

See also
DDS_ResourceLimitsQosPolicy
DDS_REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT 

When using DDS_RELIABLE_RELIABILITY_QOS: A resource limit on the number of samples per instance (DDS_ResourceLimitsQosPolicy::max_samples_per_instance) was reached. When using DDS_BEST_EFFORT_RELIABILITY_QOS, reaching DDS_ResourceLimitsQosPolicy::max_samples_per_instance will trigger a loss, not a rejection, with reason DDS_LOST_BY_SAMPLES_PER_INSTANCE_LIMIT.

See also
ResourceLimitsQosPolicy
DDS_REJECTED_BY_SAMPLES_PER_REMOTE_WRITER_LIMIT 

When using DDS_RELIABLE_RELIABILITY_QOS: a resource limit on the number of samples from a given remote writer that a DDSDataReader may store (DDS_DataReaderResourceLimitsQosPolicy::max_samples_per_remote_writer) was reached. When using DDS_BEST_EFFORT_RELIABILITY_QOS, reaching DDS_DataReaderResourceLimitsQosPolicy::max_samples_per_remote_writer will trigger a loss, not a rejection, with reason DDS_LOST_BY_SAMPLES_PER_REMOTE_WRITER_LIMIT.

This constant is an extension to the DDS standard.

See also
DDS_DataReaderResourceLimitsQosPolicy
DDS_REJECTED_BY_REMOTE_WRITER_SAMPLES_PER_VIRTUAL_QUEUE_LIMIT 

A resource limit on the number of samples published by a remote writer on behalf of a virtual writer that a DDSDataReader may store was reached. (This field is currently not used.)

This constant is an extension to the DDS standard.

See also
DDS_DataReaderResourceLimitsQosPolicy
DDS_REJECTED_BY_DECODE_FAILURE 

When using DDS_RELIABLE_RELIABILITY_QOS: A received sample was rejected because it could not be decoded. When using DDS_BEST_EFFORT_RELIABILITY_QOS, the sample will be lost, not rejected, with reason DDS_LOST_BY_DECODE_FAILURE.

If a sample was rejected for this reason and the DDSDataWriter set DDS_DataWriterProtocolQosPolicy::disable_inline_keyhash to DDS_BOOLEAN_TRUE, then DDS_SampleRejectedStatus::last_instance_handle may not be correct if the sample was encrypted.

This constant is an extension to the DDS standard.

Function Documentation

◆ DDS_DataReaderQos_equals()

DDS_Boolean DDS_DataReaderQos_equals ( const struct DDS_DataReaderQos self,
const struct DDS_DataReaderQos other 
)

Compares two DDS_DataReaderQos for equality.

Parameters
self<<in>> This DataReaderQos.
other<<in>> The other DataReaderQos to be compared with this DataReaderQos.
Returns
DDS_BOOLEAN_TRUE if the two Qos objects are equal or DDS_BOOLEAN_FALSE otherwise.

Referenced by DDS_DataReaderQos::operator!=(), and DDS_DataReaderQos::operator==().

◆ print()

DDS_ReturnCode_t DDS_DataReaderQos::print ( ) const
inline

Prints this DDS_DataReaderQos to stdout.

Only the differences between this DDS_DataReaderQos and the documented default are printed. If you wish to print everything regardless, see DDS_DataReaderQos::to_string(char*, DDS_UnsignedLong&, const DDS_DataReaderQos&, const DDS_QosPrintFormat&) const. The output is formatted according to the default values for DDS_QosPrintFormat.

Returns
DDS_RETCODE_OK if no error was encountered.

◆ to_string() [1/6]

DDS_ReturnCode_t DDS_DataReaderQos::to_string ( char *  string,
DDS_UnsignedLong string_size 
) const
inline

Obtains a string representation of this DDS_DataReaderQos.

Only the differences between this DDS_DataReaderQos and the documented default are printed to the string. If you wish to print everything regardless, see DDS_DataReaderQos::to_string(char*, DDS_UnsignedLong&, const DDS_DataReaderQos&, const DDS_QosPrintFormat&) const. The output is formatted according to the default values for DDS_QosPrintFormat.

If the supplied buffer is NULL, the required length of the string is returned via the string_size parameter.

If the supplied buffer is not NULL, the string representation of the DDS_DataReaderQos is written to the buffer.

Parameters
string<<out>> The char buffer that will be used to store the string representation of this DDS_DataReaderQos. If NULL, this function will return the required length of this buffer through the string_size parameter.
string_size<<inout>> Cannot be NULL. The size of the supplied buffer. If the supplied buffer is NULL, or if the supplied buffer is not large enough, this value will be updated with the required length of the buffer.
Returns
DDS_RETCODE_OK if no error was encountered.
See also
DDS_DataReaderQos::to_string(char*, DDS_UnsignedLong&, const DDS_DataReaderQos&, const DDS_QosPrintFormat&) const

◆ to_string() [2/6]

DDS_ReturnCode_t DDS_DataReaderQos::to_string ( char *  string,
DDS_UnsignedLong string_size,
const DDS_DataReaderQos base 
) const
inline

Obtains a string representation of this DDS_DataReaderQos.

This overload behaves the same as DDS_DataReaderQos::to_string but allows the caller to specify the DDS_DataReaderQos, which is used as the base profile. Only the differences between the QoS and the base profile are included in the output string.

Parameters
string<<out>> The char buffer that will be used to store the string representation of this DDS_DataReaderQos. If NULL, this function will return the required length of this buffer through the string_size parameter.
string_size<<inout>> Cannot be NULL. The size of the supplied buffer. If the supplied buffer is NULL, or if the supplied buffer is not large enough, this value will be updated with the required length of the buffer.
base<<in>> The DDS_DataReaderQos to be used as the base QoS profile. Only the differences with respect to this base profile will be included in the output string.
Returns
DDS_RETCODE_OK if no error was encountered.
See also
DDS_DataReaderQos::to_string(char*, DDS_UnsignedLong&, const DDS_DataReaderQos&, const DDS_QosPrintFormat&) const

References DDS_QosPrintFormat_INITIALIZER.

◆ to_string() [3/6]

DDS_ReturnCode_t DDS_DataReaderQos::to_string ( char *  string,
DDS_UnsignedLong string_size,
const DDS_QosPrintFormat format 
) const
inline

Obtains a string representation of this DDS_DataReaderQos.

This overload behaves the same as DDS_DataReaderQos::to_string but allows the caller to specify the DDS_QosPrintFormat which is used to format the output.

Parameters
string<<out>> The char buffer that will be used to store the string representation of this DDS_DataReaderQos. If NULL, this function will return the required length of this buffer through the string_size parameter.
string_size<<inout>> Cannot be NULL. The size of the supplied buffer. If the supplied buffer is NULL, or if the supplied buffer is not large enough, this value will be updated with the required length of the buffer.
format<<in>> The DDS_QosPrintFormat to be used to format the output string.
Returns
DDS_RETCODE_OK if no error was encountered.
See also
DDS_DataReaderQos::to_string(char*, DDS_UnsignedLong&, const DDS_DataReaderQos&, const DDS_QosPrintFormat&) const

References DDS_RETCODE_ERROR, and DDS_RETCODE_OK.

◆ to_string() [4/6]

DDS_ReturnCode_t DDS_DataReaderQos::to_string ( char *  string,
DDS_UnsignedLong string_size,
const DDS_DataReaderQos base,
const DDS_QosPrintFormat format 
) const
inline

Obtains a string representation of this DDS_DataReaderQos.

Only the differences between this DDS_DataReaderQos and the DDS_DataReaderQos supplied as the base are printed to the string.

If the supplied buffer is NULL, the required length of the string is returned via the string_size parameter.

If the supplied buffer is not NULL, the string representation of the DDS_DataReaderQos is written to the buffer.

Parameters
string<<out>> The char buffer that will be used to store the string representation of this DDS_DataReaderQos. If NULL, this function will return the required length of this buffer through the string_size parameter.
string_size<<inout>> Cannot be NULL. The size of the supplied buffer. If the supplied buffer is NULL, or if the supplied buffer is not large enough, this value will be updated with the required length of the buffer.
base<<in>> The DDS_DataReaderQos to be used as the base QoS profile. Only the differences with respect to this base profile will be included in the output string.
format<<in>> The DDS_QosPrintFormat to be used to format the output string.
Returns
DDS_RETCODE_OK if no error was encountered.

◆ to_string() [5/6]

DDS_ReturnCode_t DDS_DataReaderQos::to_string ( char *  string,
DDS_UnsignedLong string_size,
const DDS_QosPrintAll_t  
) const
inline

Obtains a string representation of this DDS_DataReaderQos.

This overload behaves the same as DDS_DataReaderQos::to_string but prints the entire DDS_DataReaderQos object. The only valid value for the argument of type DDS_QosPrintAll_t is DDS_QOS_PRINT_ALL.

For example

DataReaderQos qos;
char *str = NULL;
DDS_UnsignedLong str_size = 0;
qos.to_string(str, str_size, QOS_PRINT_ALL);

The resultant string is formatted according to the default value for DDS_QosPrintFormat.

Parameters
string<<out>> The char buffer that will be used to store the string representation of this DDS_DataReaderQos. If NULL, this function will return the required length of this buffer through the string_size parameter.
string_size<<inout>> Cannot be NULL. The size of the supplied buffer. If the supplied buffer is NULL, or if the supplied buffer is not large enough, this value will be updated with the required length of the buffer.
Returns
DDS_RETCODE_OK if no error was encountered.
See also
DDS_DataReaderQos::to_string(char*, DDS_UnsignedLong&, const DDS_DataReaderQos&, const DDS_QosPrintFormat&) const

References DDS_QosPrintFormat_INITIALIZER.

◆ to_string() [6/6]

DDS_ReturnCode_t DDS_DataReaderQos::to_string ( char *  string,
DDS_UnsignedLong string_size,
const DDS_QosPrintAll_t ,
const DDS_QosPrintFormat format 
) const
inline

Obtains a string representation of this DDS_DataReaderQos.

This overload behaves the same as the DDS_DataReaderQos::to_string(char*, DDS_UnsignedLong&, const DDS_QosPrintAll_t&) const overload. The only difference is that it allows the caller to specify the DDS_QosPrintFormat which is used to format the resultant string.

Parameters
string<<out>> The char buffer that will be used to store the string representation of this DDS_DataReaderQos. If NULL, this function will return the required length of this buffer through the string_size parameter.
string_size<<inout>> Cannot be NULL. The size of the supplied buffer. If the supplied buffer is NULL, or if the supplied buffer is not large enough, this value will be updated with the required length of the buffer.
format<<in>> The DDS_QosPrintFormat to be used to format the output string.
Returns
DDS_RETCODE_OK if no error was encountered.
See also
DDS_DataReaderQos::to_string(char*, DDS_UnsignedLong&, const DDS_DataReaderQos&, const DDS_QosPrintFormat&) const

References DDS_SubscriberQos_equals().