RTI Connext C API Version 7.2.0

DDS_DataReader entity and associated elements More...

Modules

 Read Conditions
 DDS_ReadCondition and associated elements
 
 Query Conditions
 DDS_QueryCondition and associated elements
 
 Topic Queries
 DDS_TopicQuery and associated elements.
 

Data Structures

struct  FooDataReader
 <<interface>> <<generic>> User data type-specific data reader. More...
 
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 DDS_DataReader entity. More...
 
struct  DDS_DataReaderSeq
 Declares IDL sequence < DDS_DataReader > . More...
 
struct  DDS_DataReaderListener
 <<interface>> DDS_Listener for reader status. More...
 

Macros

#define DDS_RequestedDeadlineMissedStatus_INITIALIZER
 Initializer for new status instances. More...
 
#define DDS_LivelinessChangedStatus_INITIALIZER
 Initializer for new status instances. More...
 
#define DDS_RequestedIncompatibleQosStatus_INITIALIZER
 Initializer for new status instances. More...
 
#define DDS_SampleLostStatus_INITIALIZER
 Initializer for new status instances. More...
 
#define DDS_SampleRejectedStatus_INITIALIZER
 Initializer for new status instances. More...
 
#define DDS_SubscriptionMatchedStatus_INITIALIZER
 Initializer for new status instances. More...
 
#define DDS_DataReaderCacheStatus_INITIALIZER
 Initializer for new status instances. More...
 
#define DDS_DataReaderProtocolStatus_INITIALIZER
 Initializer for new status instances. More...
 
#define DDS_DataReaderQos_INITIALIZER
 Initializer for new QoS instances. More...
 
#define DDS_DataReaderListener_INITIALIZER
 Initializer for new DDS_DataReaderListener. More...
 

Typedefs

typedef struct DDS_DataReaderImpl DDS_DataReader
 <<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 DDS_Subscriber. More...
 
typedef void(* DDS_DataReaderListener_RequestedDeadlineMissedCallback) (void *listener_data, DDS_DataReader *reader, const struct DDS_RequestedDeadlineMissedStatus *status)
 Prototype of a DDS_DataReaderListener requested_deadline_missed function. More...
 
typedef void(* DDS_DataReaderListener_LivelinessChangedCallback) (void *listener_data, DDS_DataReader *reader, const struct DDS_LivelinessChangedStatus *status)
 Prototype of a DDS_DataReaderListener liveliness_changed function. More...
 
typedef void(* DDS_DataReaderListener_RequestedIncompatibleQosCallback) (void *listener_data, DDS_DataReader *reader, const struct DDS_RequestedIncompatibleQosStatus *status)
 Prototype of a DDS_DataReaderListener requested_incompatible_QoS function. More...
 
typedef void(* DDS_DataReaderListener_SampleRejectedCallback) (void *listener_data, DDS_DataReader *reader, const struct DDS_SampleRejectedStatus *status)
 Prototype of a DDS_DataReaderListener sample_rejected function. More...
 
typedef void(* DDS_DataReaderListener_DataAvailableCallback) (void *listener_data, DDS_DataReader *reader)
 Prototype of a DDS_DataReaderListener data_available function. More...
 
typedef void(* DDS_DataReaderListener_SubscriptionMatchedCallback) (void *listener_data, DDS_DataReader *reader, const struct DDS_SubscriptionMatchedStatus *status)
 Prototype of a DDS_DataReaderListener subscription_match function. More...
 
typedef void(* DDS_DataReaderListener_SampleLostCallback) (void *listener_data, DDS_DataReader *reader, const struct DDS_SampleLostStatus *status)
 Prototype of a DDS_DataReaderListener subscription_lost function. 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

FooDataReaderFooDataReader_narrow (DDS_DataReader *reader)
 Narrow the given DDS_DataReader pointer to a FooDataReader pointer. More...
 
DDS_DataReaderFooDataReader_as_datareader (FooDataReader *reader)
 Widen the given FooDataReader pointer to a DDS_DataReader pointer. More...
 
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. More...
 
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. More...
 
DDS_ReturnCode_t FooDataReader_read_w_condition (FooDataReader *self, struct FooSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_samples, DDS_ReadCondition *condition)
 Accesses via FooDataReader_read the samples that match the criteria specified in the DDS_ReadCondition. More...
 
DDS_ReturnCode_t FooDataReader_take_w_condition (FooDataReader *self, FooSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_samples, DDS_ReadCondition *condition)
 Analogous to FooDataReader_read_w_condition except it accesses samples via the FooDataReader_take operation. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
DDS_ReturnCode_t FooDataReader_read_instance_w_condition (FooDataReader *self, struct FooSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_samples, const DDS_InstanceHandle_t *a_handle, DDS_ReadCondition *condition)
 <<extension>> Accesses via FooDataReader_read_instance the samples that match the criteria specified in the DDS_ReadCondition. More...
 
DDS_ReturnCode_t FooDataReader_take_instance_w_condition (FooDataReader *self, struct FooSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_samples, const DDS_InstanceHandle_t *a_handle, DDS_ReadCondition *condition)
 <<extension>> Accesses via FooDataReader_take_instance the samples that match the criteria specified in the DDS_ReadCondition. More...
 
DDS_ReturnCode_t FooDataReader_read_next_instance (FooDataReader *self, struct FooSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_samples, const DDS_InstanceHandle_t *previous_handle, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
 Access a collection of data samples from the DDS_DataReader. More...
 
DDS_ReturnCode_t FooDataReader_take_next_instance (FooDataReader *self, struct FooSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_samples, const DDS_InstanceHandle_t *previous_handle, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
 Access a collection of data samples from the DDS_DataReader. More...
 
DDS_ReturnCode_t FooDataReader_read_next_instance_w_condition (FooDataReader *self, struct FooSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_samples, const DDS_InstanceHandle_t *previous_handle, DDS_ReadCondition *condition)
 Accesses via FooDataReader_read_next_instance the samples that match the criteria specified in the DDS_ReadCondition. More...
 
DDS_ReturnCode_t FooDataReader_take_next_instance_w_condition (FooDataReader *self, struct FooSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_samples, const DDS_InstanceHandle_t *previous_handle, DDS_ReadCondition *condition)
 Accesses via FooDataReader_take_next_instance the samples that match the criteria specified in the DDS_ReadCondition. More...
 
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. More...
 
DDS_ReturnCode_t FooDataReader_get_key_value (FooDataReader *self, Foo *key_holder, const DDS_InstanceHandle_t *handle)
 Retrieve the instance key that corresponds to an instance handle. More...
 
DDS_InstanceHandle_t FooDataReader_lookup_instance (FooDataReader *self, const Foo *key_holder)
 Retrieves the instance handle that corresponds to an instance key_holder. More...
 
DDS_ReturnCode_t FooDataReader_is_data_consistent (FooDataReader *self, DDS_Boolean *is_data_consistent, const Foo *sample, const struct DDS_SampleInfo *sample_info)
 When using Zero Copy transfer over shared memory, checks if the sample has been overwritten by the DataWriter. More...
 
DDS_ReturnCode_t DDS_RequestedDeadlineMissedStatus_initialize (struct DDS_RequestedDeadlineMissedStatus *self)
 Initializer for new status instances. More...
 
DDS_ReturnCode_t DDS_RequestedDeadlineMissedStatus_copy (struct DDS_RequestedDeadlineMissedStatus *self, const struct DDS_RequestedDeadlineMissedStatus *source)
 Copy the contents of the given status into this status. More...
 
DDS_ReturnCode_t DDS_RequestedDeadlineMissedStatus_finalize (struct DDS_RequestedDeadlineMissedStatus *self)
 Free any dynamic memory allocated by status instances. More...
 
DDS_Boolean DDS_RequestedDeadlineMissedStatus_equals (const struct DDS_RequestedDeadlineMissedStatus *left, const struct DDS_RequestedDeadlineMissedStatus *right)
 Compares two DDS_RequestedDeadlineMissedStatus for equality. More...
 
DDS_ReturnCode_t DDS_LivelinessChangedStatus_initialize (struct DDS_LivelinessChangedStatus *self)
 Initializer for new status instances. More...
 
DDS_ReturnCode_t DDS_LivelinessChangedStatus_copy (struct DDS_LivelinessChangedStatus *self, const struct DDS_LivelinessChangedStatus *source)
 Copy the contents of the given status into this status. More...
 
DDS_ReturnCode_t DDS_LivelinessChangedStatus_finalize (struct DDS_LivelinessChangedStatus *self)
 Free any dynamic memory allocated by status instances. More...
 
DDS_Boolean DDS_LivelinessChangedStatus_equals (const struct DDS_LivelinessChangedStatus *left, const struct DDS_LivelinessChangedStatus *right)
 Compares two DDS_LivelinessChangedStatus for equality. More...
 
DDS_ReturnCode_t DDS_RequestedIncompatibleQosStatus_initialize (struct DDS_RequestedIncompatibleQosStatus *self)
 Initializer for new status instances. More...
 
DDS_ReturnCode_t DDS_RequestedIncompatibleQosStatus_copy (struct DDS_RequestedIncompatibleQosStatus *self, const struct DDS_RequestedIncompatibleQosStatus *source)
 Copy the contents of the given status into this status. More...
 
DDS_ReturnCode_t DDS_RequestedIncompatibleQosStatus_finalize (struct DDS_RequestedIncompatibleQosStatus *self)
 Free any dynamic memory allocated by status instances. More...
 
DDS_Boolean DDS_RequestedIncompatibleQosStatus_equals (const struct DDS_RequestedIncompatibleQosStatus *left, const struct DDS_RequestedIncompatibleQosStatus *right)
 Compares two DDS_RequestedIncompatibleQosStatus for equality. More...
 
DDS_ReturnCode_t DDS_SampleLostStatus_initialize (struct DDS_SampleLostStatus *self)
 Initializer for new status instances. More...
 
DDS_ReturnCode_t DDS_SampleLostStatus_copy (struct DDS_SampleLostStatus *self, const struct DDS_SampleLostStatus *source)
 Copy the contents of the given status into this status. More...
 
DDS_ReturnCode_t DDS_SampleLostStatus_finalize (struct DDS_SampleLostStatus *self)
 Free any dynamic memory allocated by status instances. More...
 
DDS_Boolean DDS_SampleLostStatus_equals (const struct DDS_SampleLostStatus *left, const struct DDS_SampleLostStatus *right)
 Compares two DDS_SampleLostStatus for equality. More...
 
DDS_ReturnCode_t DDS_SampleRejectedStatus_initialize (struct DDS_SampleRejectedStatus *self)
 Initializer for new status instances. More...
 
DDS_ReturnCode_t DDS_SampleRejectedStatus_copy (struct DDS_SampleRejectedStatus *self, const struct DDS_SampleRejectedStatus *source)
 Copy the contents of the given status into this status. More...
 
DDS_ReturnCode_t DDS_SampleRejectedStatus_finalize (struct DDS_SampleRejectedStatus *self)
 Free any dynamic memory allocated by status instances. More...
 
DDS_Boolean DDS_SampleRejectedStatus_equals (const struct DDS_SampleRejectedStatus *left, const struct DDS_SampleRejectedStatus *right)
 Compares two DDS_SampleRejectedStatus for equality. More...
 
DDS_ReturnCode_t DDS_SubscriptionMatchedStatus_initialize (struct DDS_SubscriptionMatchedStatus *self)
 Initializer for new status instances. More...
 
DDS_ReturnCode_t DDS_SubscriptionMatchedStatus_copy (struct DDS_SubscriptionMatchedStatus *self, const struct DDS_SubscriptionMatchedStatus *source)
 Copy the contents of the given status into this status. More...
 
DDS_ReturnCode_t DDS_SubscriptionMatchedStatus_finalize (struct DDS_SubscriptionMatchedStatus *self)
 Free any dynamic memory allocated by status instances. More...
 
DDS_Boolean DDS_SubscriptionMatchedStatus_equals (const struct DDS_SubscriptionMatchedStatus *left, const struct DDS_SubscriptionMatchedStatus *right)
 Compares two DDS_SubscriptionMatchedStatus for equality. More...
 
DDS_ReturnCode_t DDS_DataReaderCacheStatus_initialize (struct DDS_DataReaderCacheStatus *self)
 Initializer for new status instances. More...
 
DDS_ReturnCode_t DDS_DataReaderCacheStatus_copy (struct DDS_DataReaderCacheStatus *self, const struct DDS_DataReaderCacheStatus *source)
 Copy the contents of the given status into this status. More...
 
DDS_ReturnCode_t DDS_DataReaderCacheStatus_finalize (struct DDS_DataReaderCacheStatus *self)
 Free any dynamic memory allocated by status instances. More...
 
DDS_Boolean DDS_DataReaderCacheStatus_equals (const struct DDS_DataReaderCacheStatus *left, const struct DDS_DataReaderCacheStatus *right)
 Compares two DDS_DataReaderCacheStatus for equality. More...
 
DDS_ReturnCode_t DDS_DataReaderProtocolStatus_initialize (struct DDS_DataReaderProtocolStatus *self)
 Initializer for new status instances. More...
 
DDS_ReturnCode_t DDS_DataReaderProtocolStatus_copy (struct DDS_DataReaderProtocolStatus *self, const struct DDS_DataReaderProtocolStatus *source)
 Copy the contents of the given status into this status. More...
 
DDS_ReturnCode_t DDS_DataReaderProtocolStatus_finalize (struct DDS_DataReaderProtocolStatus *self)
 Free any dynamic memory allocated by status instances. More...
 
DDS_Boolean DDS_DataReaderProtocolStatus_equals (const struct DDS_DataReaderProtocolStatus *left, const struct DDS_DataReaderProtocolStatus *right)
 Compares two DDS_DataReaderProtocolStatus for equality. More...
 
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 struct DDS_DataReaderQos *self)
 Prints this DDS_DataReaderQos to stdout. More...
 
DDS_ReturnCode_t DDS_DataReaderQos_to_string (const struct DDS_DataReaderQos *self, char *string, DDS_UnsignedLong *string_size)
 Obtains a string representation of this DDS_DataReaderQos. More...
 
DDS_ReturnCode_t DDS_DataReaderQos_to_string_w_params (const struct DDS_DataReaderQos *self, char *string, DDS_UnsignedLong *string_size, const struct DDS_DataReaderQos *base, const struct DDS_QosPrintFormat *format)
 Obtains a string representation of this DDS_DataReaderQos. More...
 
DDS_ReturnCode_t DDS_DataReaderQos_initialize (struct DDS_DataReaderQos *self)
 Initializer for new QoS instances. More...
 
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. More...
 
DDS_ReturnCode_t DDS_DataReaderQos_finalize (struct DDS_DataReaderQos *self)
 Free any dynamic memory allocated by the policies in this DDS_DataReaderQos. More...
 
DDS_EntityDDS_DataReader_as_entity (DDS_DataReader *dataReader)
 Accesses the DDS_DataReader's supertype instance. More...
 
DDS_ReadConditionDDS_DataReader_create_readcondition (DDS_DataReader *self, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
 Creates a DDS_ReadCondition. More...
 
DDS_ReadConditionDDS_DataReader_create_readcondition_w_params (DDS_DataReader *self, const struct DDS_ReadConditionParams *params)
 <<extension>> Creates a DDS_ReadCondition with parameters. More...
 
DDS_QueryConditionDDS_DataReader_create_querycondition (DDS_DataReader *self, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states, const char *query_expression, const struct DDS_StringSeq *query_parameters)
 Creates a DDS_QueryCondition. More...
 
DDS_QueryConditionDDS_DataReader_create_querycondition_w_params (DDS_DataReader *self, const struct DDS_QueryConditionParams *params)
 <<extension>> Creates a DDS_QueryCondition with parameters. More...
 
DDS_ReturnCode_t DDS_DataReader_delete_readcondition (DDS_DataReader *self, DDS_ReadCondition *condition)
 Deletes a DDS_ReadCondition or DDS_QueryCondition attached to the DDS_DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_delete_contained_entities (DDS_DataReader *self)
 Deletes all the entities that were created by means of the "create" operations on the DDS_DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_wait_for_historical_data (DDS_DataReader *self, const struct DDS_Duration_t *max_wait)
 Waits until all "historical" data is received for DDS_DataReader entities that have a non-VOLATILE Durability Qos kind. More...
 
DDS_ReturnCode_t DDS_DataReader_acknowledge_sample_w_response (DDS_DataReader *self, const struct DDS_SampleInfo *sample_info, const struct DDS_AckResponseData_t *response_data)
 <<extension>> Acknowledges a single sample explicitly. More...
 
DDS_ReturnCode_t DDS_DataReader_acknowledge_all_w_response (DDS_DataReader *self, const struct DDS_AckResponseData_t *response_data)
 <<extension>> Acknowledges all previously accessed samples. More...
 
DDS_ReturnCode_t DDS_DataReader_acknowledge_sample (DDS_DataReader *self, const struct DDS_SampleInfo *sample_info)
 <<extension>> Acknowledges a single sample explicitly. More...
 
DDS_ReturnCode_t DDS_DataReader_acknowledge_all (DDS_DataReader *self)
 <<extension>> Acknowledges all previously accessed samples. More...
 
DDS_ReturnCode_t DDS_DataReader_get_matched_publications (DDS_DataReader *self, struct DDS_InstanceHandleSeq *publication_handles)
 Retrieves the list of publications currently "associated" with this DDS_DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_is_matched_publication_alive (DDS_DataReader *self, DDS_Boolean *is_alive, const DDS_InstanceHandle_t *publication_handle)
 Check if a publication currently matched with a DataReader is alive. More...
 
DDS_ReturnCode_t DDS_DataReader_get_matched_publication_data (DDS_DataReader *self, struct DDS_PublicationBuiltinTopicData *publication_data, const DDS_InstanceHandle_t *publication_handle)
 Retrieves the information on a publication that is currently "associated" with the DDS_DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_get_matched_publication_participant_data (DDS_DataReader *self, struct DDS_ParticipantBuiltinTopicData *participant_data, const DDS_InstanceHandle_t *publication_handle)
 <<extension>> Retrieves the information on the discovered DDS_DomainParticipant associated with the publication that is currently matching with the DDS_DataReader. More...
 
DDS_TopicDescriptionDDS_DataReader_get_topicdescription (DDS_DataReader *self)
 Returns the DDS_TopicDescription associated with the DDS_DataReader. More...
 
DDS_SubscriberDDS_DataReader_get_subscriber (DDS_DataReader *self)
 Returns the DDS_Subscriber to which the DDS_DataReader belongs. More...
 
DDS_ReturnCode_t DDS_DataReader_get_sample_rejected_status (DDS_DataReader *self, struct DDS_SampleRejectedStatus *status)
 Accesses the DDS_SAMPLE_REJECTED_STATUS communication status. More...
 
DDS_ReturnCode_t DDS_DataReader_get_liveliness_changed_status (DDS_DataReader *self, struct DDS_LivelinessChangedStatus *status)
 Accesses the DDS_LIVELINESS_CHANGED_STATUS communication status. More...
 
DDS_ReturnCode_t DDS_DataReader_get_requested_deadline_missed_status (DDS_DataReader *self, struct DDS_RequestedDeadlineMissedStatus *status)
 Accesses the DDS_REQUESTED_DEADLINE_MISSED_STATUS communication status. More...
 
DDS_ReturnCode_t DDS_DataReader_get_requested_incompatible_qos_status (DDS_DataReader *self, struct DDS_RequestedIncompatibleQosStatus *status)
 Accesses the DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS communication status. More...
 
DDS_ReturnCode_t DDS_DataReader_get_subscription_matched_status (DDS_DataReader *self, struct DDS_SubscriptionMatchedStatus *status)
 Accesses the DDS_SUBSCRIPTION_MATCHED_STATUS communication status. More...
 
DDS_ReturnCode_t DDS_DataReader_get_sample_lost_status (DDS_DataReader *self, struct DDS_SampleLostStatus *status)
 Accesses the DDS_SAMPLE_LOST_STATUS communication status. More...
 
DDS_ReturnCode_t DDS_DataReader_get_datareader_cache_status (DDS_DataReader *self, struct DDS_DataReaderCacheStatus *status)
 <<extension>> Gets the datareader cache status for this reader. More...
 
DDS_ReturnCode_t DDS_DataReader_get_datareader_protocol_status (DDS_DataReader *self, struct DDS_DataReaderProtocolStatus *status)
 <<extension>> Gets the datareader protocol status for this reader. More...
 
DDS_ReturnCode_t DDS_DataReader_get_matched_publication_datareader_protocol_status (DDS_DataReader *self, struct DDS_DataReaderProtocolStatus *status, const DDS_InstanceHandle_t *publication_handle)
 <<extension>> Gets the datareader protocol status for this reader, per matched publication identified by the publication_handle. More...
 
DDS_ReturnCode_t DDS_DataReader_set_qos (DDS_DataReader *self, const struct DDS_DataReaderQos *qos)
 Sets the reader QoS. More...
 
DDS_ReturnCode_t DDS_DataReader_set_qos_with_profile (DDS_DataReader *self, const char *library_name, const char *profile_name)
 <<extension>> Changes the QoS of this reader using the input XML QoS profile. More...
 
DDS_ReturnCode_t DDS_DataReader_get_qos (DDS_DataReader *self, struct DDS_DataReaderQos *qos)
 Gets the reader QoS. More...
 
DDS_ReturnCode_t DDS_DataReader_set_property (DDS_DataReader *self, const char *property_name, const char *value, DDS_Boolean propagate)
 Set the value for a property that applies to a DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_set_listener (DDS_DataReader *self, const struct DDS_DataReaderListener *l, DDS_StatusMask mask)
 Sets the reader listener. More...
 
struct DDS_DataReaderListener DDS_DataReader_get_listener (DDS_DataReader *self)
 Gets the reader listener. More...
 
DDS_ReturnCode_t DDS_DataReader_get_listenerX (DDS_DataReader *self, struct DDS_DataReaderListener *listener)
 <<extension>> Gets the reader listener. More...
 
DDS_TopicQueryDDS_DataReader_create_topic_query (DDS_DataReader *self, const struct DDS_TopicQuerySelection *selection)
 Creates a DDS_TopicQuery. More...
 
DDS_ReturnCode_t DDS_DataReader_delete_topic_query (DDS_DataReader *self, DDS_TopicQuery *query)
 Deletes a DDS_TopicQuery. More...
 
DDS_TopicQueryDDS_DataReader_lookup_topic_query (DDS_DataReader *self, const struct DDS_GUID_t *guid)
 Retrieves an existing DDS_TopicQuery. More...
 
DDS_ReturnCode_t DDS_DataReader_take_discovery_snapshot (DDS_DataReader *self, const char *file_name)
 Take a snapshot of the compatible and incompatible remote writers matched by a local reader. More...
 

Detailed Description

DDS_DataReader entity and associated elements

Macro Definition Documentation

◆ DDS_RequestedDeadlineMissedStatus_INITIALIZER

#define DDS_RequestedDeadlineMissedStatus_INITIALIZER

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. DDS_InconsistentTopicStatus_finalize should be called to free the contained fields that use dynamic memory:

...
#define DDS_RequestedDeadlineMissedStatus_INITIALIZER
Initializer for new status instances.
Definition: subscription.ifc:284
DDS_ReturnCode_t DDS_RequestedDeadlineMissedStatus_finalize(struct DDS_RequestedDeadlineMissedStatus *self)
Free any dynamic memory allocated by status instances.
DDS_REQUESTED_DEADLINE_MISSED_STATUS
Definition: subscription.ifc:266
See also
DDS_RequestedDeadlineMissedStatus_initialize
DDS_RequestedDeadlineMissedStatus_finalize

◆ DDS_LivelinessChangedStatus_INITIALIZER

#define DDS_LivelinessChangedStatus_INITIALIZER

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. DDS_LivelinessChangedStatus_finalize should be called to free the contained fields that use dynamic memory:

...
DDS_LivelinessChangedStatuss_finalize(&myStatus);
#define DDS_LivelinessChangedStatus_INITIALIZER
Initializer for new status instances.
Definition: subscription.ifc:342
DDS_LIVELINESS_CHANGED_STATUS
Definition: subscription.ifc:316
See also
DDS_LivelinessChangedStatus_initialize
DDS_LivelinessChangedStatus_finalize

◆ DDS_RequestedIncompatibleQosStatus_INITIALIZER

#define DDS_RequestedIncompatibleQosStatus_INITIALIZER

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. DDS_RequestedIncompatibleQosStatus_finalize should be called to free the contained fields that use dynamic memory:

...
#define DDS_RequestedIncompatibleQosStatus_INITIALIZER
Initializer for new status instances.
Definition: subscription.ifc:395
DDS_ReturnCode_t DDS_RequestedIncompatibleQosStatus_finalize(struct DDS_RequestedIncompatibleQosStatus *self)
Free any dynamic memory allocated by status instances.
DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS
Definition: subscription.ifc:374
See also
DDS_RequestedIncompatibleQosStatus_initialize
DDS_RequestedIncompatibleQosStatus_finalize

◆ DDS_SampleLostStatus_INITIALIZER

#define DDS_SampleLostStatus_INITIALIZER

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. DDS_SampleLostStatus_finalize should be called to free the contained fields that use dynamic memory:

...
DDS_ReturnCode_t DDS_SampleLostStatus_finalize(struct DDS_SampleLostStatus *self)
Free any dynamic memory allocated by status instances.
#define DDS_SampleLostStatus_INITIALIZER
Initializer for new status instances.
Definition: subscription.ifc:524
DDS_SAMPLE_LOST_STATUS
Definition: subscription.ifc:507
See also
DDS_SampleLostStatus_initialize
DDS_SampleLostStatus_finalize

◆ DDS_SampleRejectedStatus_INITIALIZER

#define DDS_SampleRejectedStatus_INITIALIZER

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. DDS_SampleRejectedStatus_finalize should be called to free the contained fields that use dynamic memory:

...
#define DDS_SampleRejectedStatus_INITIALIZER
Initializer for new status instances.
Definition: subscription.ifc:620
DDS_ReturnCode_t DDS_SampleRejectedStatus_finalize(struct DDS_SampleRejectedStatus *self)
Free any dynamic memory allocated by status instances.
DDS_SAMPLE_REJECTED_STATUS
Definition: subscription.ifc:598
See also
DDS_SampleRejectedStatus_initialize
DDS_SampleRejectedStatus_finalize

◆ DDS_SubscriptionMatchedStatus_INITIALIZER

#define DDS_SubscriptionMatchedStatus_INITIALIZER

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. DDS_SubscriptionMatchedStatus_finalize should be called to free the contained fields that use dynamic memory:

...
#define DDS_SubscriptionMatchedStatus_INITIALIZER
Initializer for new status instances.
Definition: subscription.ifc:683
DDS_ReturnCode_t DDS_SubscriptionMatchedStatus_finalize(struct DDS_SubscriptionMatchedStatus *self)
Free any dynamic memory allocated by status instances.
DDS_SUBSCRIPTION_MATCHED_STATUS
Definition: subscription.ifc:653
See also
DDS_SubscriptionMatchedStatus_initialize
DDS_SubscriptionMatchedStatus_finalize

◆ DDS_DataReaderCacheStatus_INITIALIZER

#define DDS_DataReaderCacheStatus_INITIALIZER

Initializer for new status instances.

New DDS_DataReaderCacheStatus instances 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. DDS_DataReaderCacheStatus_finalize should be called to free the contained fields that use dynamic memory:

DDS_ReturnCode_t DDS_DataReaderCacheStatus_finalize(struct DDS_DataReaderCacheStatus *self)
Free any dynamic memory allocated by status instances.
#define DDS_DataReaderCacheStatus_INITIALIZER
Initializer for new status instances.
Definition: subscription.ifc:773
DDS_ReturnCode_t DDS_DataReader_get_datareader_cache_status(DDS_DataReader *self, struct DDS_DataReaderCacheStatus *status)
<<extension>> Gets the datareader cache status for this reader.
<<extension>> The status of the reader's cache.
Definition: subscription.ifc:712
See also
DDS_DataReader_get_datareader_cache_status
DDS_DataReaderCacheStatus_finalize

◆ DDS_DataReaderProtocolStatus_INITIALIZER

#define DDS_DataReaderProtocolStatus_INITIALIZER

Initializer for new status instances.

New DDS_DataReaderProtocolStatus instances 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. DDS_DataReaderProtocolStatus_finalize should be called to free the contained fields that use dynamic memory:

DDS_ReturnCode_t DDS_DataReaderProtocolStatus_finalize(struct DDS_DataReaderProtocolStatus *self)
Free any dynamic memory allocated by status instances.
DDS_ReturnCode_t DDS_DataReader_get_datareader_protocol_status(DDS_DataReader *self, struct DDS_DataReaderProtocolStatus *status)
<<extension>> Gets the datareader protocol status for this reader.
#define DDS_DataReaderProtocolStatus_INITIALIZER
Initializer for new status instances.
Definition: subscription.ifc:976
<<extension>> The status of a reader's internal protocol related metrics, like the number of samples ...
Definition: subscription.ifc:848
See also
DDS_DataReader_get_datareader_protocol_status
DDS_DataReaderProtocolStatus_finalize

◆ DDS_DataReaderQos_INITIALIZER

#define DDS_DataReaderQos_INITIALIZER

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:

#define DDS_DataReaderQos_INITIALIZER
Initializer for new QoS instances.
Definition: subscription.ifc:1824
QoS policies supported by a DDS_DataReader entity.
Definition: subscription.ifc:1594

Note that the above assignment is not a substitute for calling DDS_Subscriber_get_default_datareader_qos or DDS_DataReader_get_qos; one of those should be called subsequently to setting the QoS of a new or existing entity:

DDS_DataReader_get_qos(myReader, &myQos);
DDS_ReturnCode_t DDS_DataReader_get_qos(DDS_DataReader *self, struct DDS_DataReaderQos *qos)
Gets the reader QoS.
DDS_ReturnCode_t DDS_Subscriber_get_default_datareader_qos(DDS_Subscriber *self, struct DDS_DataReaderQos *qos)
Copies the default DDS_DataReaderQos values into the provided DDS_DataReaderQos instance.
See also
DDS_DataReaderQos_initialize
DDS_Subscriber_get_default_datareader_qos
DDS_DataReaderQos_finalize

◆ DDS_DataReaderListener_INITIALIZER

#define DDS_DataReaderListener_INITIALIZER

Initializer for new DDS_DataReaderListener.

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

Examples
HelloWorld_subscriber.c.

Typedef Documentation

◆ DDS_DataReader

typedef struct DDS_DataReaderImpl DDS_DataReader

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

QoS:
DDS_DataReaderQos
Status:
DDS_DATA_AVAILABLE_STATUS;
DDS_LIVELINESS_CHANGED_STATUS, DDS_LivelinessChangedStatus;
DDS_REQUESTED_DEADLINE_MISSED_STATUS, DDS_RequestedDeadlineMissedStatus;
DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS, DDS_RequestedIncompatibleQosStatus;
DDS_SAMPLE_LOST_STATUS, DDS_SampleLostStatus;
DDS_SAMPLE_REJECTED_STATUS, DDS_SampleRejectedStatus;
DDS_SUBSCRIPTION_MATCHED_STATUS, DDS_SubscriptionMatchedStatus;
Listener:
DDS_DataReaderListener

A DDS_DataReader refers to exactly one DDS_TopicDescription (either a DDS_Topic, a DDS_ContentFilteredTopic or a DDS_MultiTopic) 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.

DDS_DataReader is an abstract class. It must be specialised for each particular application data-type (see USER_DATA). The additional methods or functions that must be defined in the auto-generated class for a hypothetical application type Foo are specified in the generic type FooDataReader.

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:

All sample-accessing operations, namely: FooDataReader_read, FooDataReader_take, FooDataReader_read_w_condition, and FooDataReader_take_w_condition may fail with the error DDS_RETCODE_PRECONDITION_NOT_MET as described in DDS_Subscriber_begin_access.

See also
Operations Allowed in Listener Callbacks
Access to data samples

◆ DDS_DataReaderListener_RequestedDeadlineMissedCallback

typedef void(* DDS_DataReaderListener_RequestedDeadlineMissedCallback) (void *listener_data, DDS_DataReader *reader, const struct DDS_RequestedDeadlineMissedStatus *status)

Prototype of a DDS_DataReaderListener requested_deadline_missed function.

◆ DDS_DataReaderListener_LivelinessChangedCallback

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

Prototype of a DDS_DataReaderListener liveliness_changed function.

◆ DDS_DataReaderListener_RequestedIncompatibleQosCallback

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

Prototype of a DDS_DataReaderListener requested_incompatible_QoS function.

◆ DDS_DataReaderListener_SampleRejectedCallback

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

Prototype of a DDS_DataReaderListener sample_rejected function.

◆ DDS_DataReaderListener_DataAvailableCallback

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

Prototype of a DDS_DataReaderListener data_available function.

◆ DDS_DataReaderListener_SubscriptionMatchedCallback

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

Prototype of a DDS_DataReaderListener subscription_match function.

◆ DDS_DataReaderListener_SampleLostCallback

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

Prototype of a DDS_DataReaderListener subscription_lost function.

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 DDS_DataWriter removed the sample before being received by the DDS_DataReader.

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 DDS_DataReader 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 DDS_DataWriter 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 DDS_DataReader. 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 DDS_DataReader 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 DDS_DataReader 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 DDS_DataReader 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 DDS_DataReader 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<P> 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 DDS_DataReader 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 DDS_DataReader 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 DDS_DataWriter 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

◆ FooDataReader_narrow()

FooDataReader * FooDataReader_narrow ( DDS_DataReader reader)

Narrow the given DDS_DataReader pointer to a FooDataReader pointer.

Parameters
reader<<in>> Cannot be NULL.

◆ FooDataReader_as_datareader()

DDS_DataReader * FooDataReader_as_datareader ( FooDataReader reader)

Widen the given FooDataReader pointer to a DDS_DataReader pointer.

Parameters
reader<<in>> Cannot be NULL.

◆ FooDataReader_read()

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.

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.

Important: When you loan data from the middleware, you must not keep any pointers to any part of the data samples or the DDS_SampleInfo objects after the call to FooDataReader_return_loan. Returning the loan places the objects back into a pool, allowing the middleware to overwrite them with new data.

Note: While you must call 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 and the DDS_DataReaderResourceLimitsQosPolicy.

Important: If the samples "returned" by this function are loaned from RTI Connext (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, up to the limits described in the documentation for FooDataReader_take().
sample_states<<in>> Data samples matching one of these sample_states are returned.
view_states<<in>> Data samples matching one of these view_state are returned.
instance_states<<in>> Data samples matching ones of these instance_state are returned.
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
FooDataReader_read_w_condition,
FooDataReader_take_w_condition
DDS_LENGTH_UNLIMITED

◆ FooDataReader_take()

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 matches the specified DDS_SampleStateMask, DDS_ViewStateMask and DDS_InstanceStateMask.

This operation may fail with DDS_RETCODE_ERROR if the 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:

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

Important: When you loan data from the middleware, you must not keep any pointers to any part of the data samples or the DDS_SampleInfo objects after the call to FooDataReader_return_loan. Returning the loan places the objects back into a pool, allowing the middleware to overwrite them with new data.

Note: While you must call 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 and the DDS_DataReaderResourceLimitsQosPolicy.

If the sequences are not empty (maximum size not equal to 0 and length not equal to 0) when FooDataReader_take is called, samples are copied to received_data and info_seq. The application will not need to call FooDataReader_return_loan.

The order of the samples returned to the caller depends on the DDS_PresentationQosPolicy.

  • If DDS_PresentationQosPolicy::access_scope is DDS_TOPIC_PRESENTATION_QOS and DDS_PresentationQosPolicy::ordered_access is set to DDS_BOOLEAN_TRUE, then the returned collection is a list where the relative order of samples as they were written by a DataWriter is preserved also across different instances. In other words, changes made by a single DataWriter are made available to subscribers in the same order in which they occur. Samples belonging to the same instance may or may not be consecutive. This is because, to preserve order within a single DataWriter, it may be necessary to mix samples from different instances.

In all of the above cases, the relative order between the samples of one instance is consistent with the DESTINATION_ORDER policy:

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.

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

The 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. For an example on how take can be used, please refer to the Access received data via a reader "receive example".

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, up to the limits described above.
sample_states<<in>> Data samples matching one of these sample_states are returned.
view_states<<in>> Data samples matching one of these view_state are returned.
instance_states<<in>> Data samples matching one of these instance_state are returned.
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
FooDataReader_read_w_condition, FooDataReader_take_w_condition
DDS_LENGTH_UNLIMITED

◆ FooDataReader_read_w_condition()

DDS_ReturnCode_t FooDataReader_read_w_condition ( FooDataReader self,
struct FooSeq received_data,
struct DDS_SampleInfoSeq info_seq,
DDS_Long  max_samples,
DDS_ReadCondition condition 
)

Accesses via FooDataReader_read the samples that match the criteria specified in the DDS_ReadCondition.

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

The specified DDS_ReadCondition must be attached to the DDS_DataReader; otherwise the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

In case the DDS_ReadCondition is a plain DDS_ReadCondition and not the specialized DDS_QueryCondition, the operation is equivalent to calling FooDataReader_read and passing as sample_states, view_states and instance_states the value of the corresponding attributes in the read_condition. Using this operation, the application can avoid repeating the same parameters specified when creating the DDS_ReadCondition.

The samples are accessed with the same semantics as FooDataReader_read.

If the DDS_DataReader has no samples that meet the constraints, the operation will fail with DDS_RETCODE_NO_DATA.

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, up to the limits described in the documentation for FooDataReader_take().
condition<<in>> the DDS_ReadCondition to select samples of interest. Cannot be NULL.
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
FooDataReader_take, FooDataReader_take_w_condition
DDS_LENGTH_UNLIMITED

◆ FooDataReader_take_w_condition()

DDS_ReturnCode_t FooDataReader_take_w_condition ( FooDataReader self,
FooSeq received_data,
struct DDS_SampleInfoSeq info_seq,
DDS_Long  max_samples,
DDS_ReadCondition condition 
)

Analogous to FooDataReader_read_w_condition except it accesses samples via the FooDataReader_take operation.

This operation is analogous to FooDataReader_read_w_condition except that it accesses samples via the FooDataReader_take operation.

The specified DDS_ReadCondition must be attached to the DDS_DataReader; otherwise the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

The samples are accessed with the same semantics as FooDataReader_take.

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

If the DDS_DataReader has no samples that meet the constraints, the function will fail with DDS_RETCODE_NO_DATA.

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, up to the limits described in the documentation for FooDataReader_take().
condition<<in>> the DDS_ReadCondition to select samples of interest. Cannot be NULL.
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_w_condition, FooDataReader_read
FooDataReader_take
DDS_LENGTH_UNLIMITED

◆ FooDataReader_read_next_sample()

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.

Note
Calling FooDataReader_read_next_sample from the DDS_DataReaderListener::on_data_available() callback reads only one sample of potentially many samples in the reader queue, because DDS_DataReaderListener::on_data_available() is triggered only once when new samples arrive in the queue. Therefore, it is recommended that you call FooDataReader_read_next_sample in a loop within the on_data_available callback until FooDataReader_read_next_sample returns DDS_RETCODE_NO_DATA . This ensures that all samples in the reader queue are serviced by application logic. (You may also choose to use FooDataReader_read rather than FooDataReader_read_next_sample in order to read more than one sample at a time.)
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

◆ FooDataReader_take_next_sample()

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

Note
Calling FooDataReader_take_next_sample from the DDS_DataReaderListener::on_data_available() callback retrieves only one sample of potentially many samples in the reader queue, because DDS_DataReaderListener::on_data_available() is triggered only once when new samples arrive in the queue. Therefore, it is recommended that you call FooDataReader_take_next_sample in a loop within the on_data_available callback until FooDataReader_take_next_sample returns DDS_RETCODE_NO_DATA . This ensures that all samples in the reader queue are serviced by application logic. (You may also choose to use the FooDataReader_take rather than FooDataReader_take_next_sample in order to take more than one sample at a time.)
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

◆ FooDataReader_read_instance()

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, up to the limits described in the documentation for FooDataReader_take().
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

◆ FooDataReader_take_instance()

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, up to the limits described in the documentation for FooDataReader_take().
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

◆ FooDataReader_read_instance_w_condition()

DDS_ReturnCode_t FooDataReader_read_instance_w_condition ( FooDataReader self,
struct FooSeq received_data,
struct DDS_SampleInfoSeq info_seq,
DDS_Long  max_samples,
const DDS_InstanceHandle_t a_handle,
DDS_ReadCondition condition 
)

<<extension>> Accesses via FooDataReader_read_instance the samples that match the criteria specified in the DDS_ReadCondition.

This operation accesses a collection of data values from the DDS_DataReader. The behavior is identical to FooDataReader_read_instance, except that all returned samples satisfy the specified condition. In other words, on success, all returned samples belong to belong the single specified instance whose handle is a_handle, and for which the specified DDS_ReadCondition evaluates to TRUE.

The behavior of the FooDataReader_read_instance_w_condition 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_w_condition operation may 'loan' elements to the output collections, which must then be returned by means of FooDataReader_return_loan.

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

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, up to the limits described in the documentation for FooDataReader_take().
a_handle<<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned. Must be a valid non-NULL DDS_InstanceHandle_t. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
condition<<in>> the DDS_ReadCondition to select samples of interest. Cannot be NULL.
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_next_instance
DDS_LENGTH_UNLIMITED

◆ FooDataReader_take_instance_w_condition()

DDS_ReturnCode_t FooDataReader_take_instance_w_condition ( FooDataReader self,
struct FooSeq received_data,
struct DDS_SampleInfoSeq info_seq,
DDS_Long  max_samples,
const DDS_InstanceHandle_t a_handle,
DDS_ReadCondition condition 
)

<<extension>> Accesses via FooDataReader_take_instance the samples that match the criteria specified in the DDS_ReadCondition.

This operation accesses a collection of data values from the DDS_DataReader and 'removes' them from the DDS_DataReader. The behavior is identical to FooDataReader_take_instance, except that all returned samples satisfy the specified condition. In other words, on success, all returned samples belong to belong the single specified instance whose handle is a_handle, and for which the specified DDS_ReadCondition evaluates to TRUE.

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

The behavior of the FooDataReader_take_instance_w_condition 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_w_condition 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.

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, up to the limits described in the documentation for FooDataReader_take().
a_handle<<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned. Must be a valid non-NULL DDS_InstanceHandle_t. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
condition<<in>> the DDS_ReadCondition to select samples of interest. Cannot be NULL.
Returns
One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, or DDS_RETCODE_NO_DATA, DDS_RETCODE_NOT_ENABLED.
See also
FooDataReader_take_next_instance
DDS_LENGTH_UNLIMITED

◆ FooDataReader_read_next_instance()

DDS_ReturnCode_t FooDataReader_read_next_instance ( FooDataReader self,
struct FooSeq received_data,
struct DDS_SampleInfoSeq info_seq,
DDS_Long  max_samples,
const DDS_InstanceHandle_t previous_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 where all the samples belong to a single instance. The behavior is similar to FooDataReader_read_instance, except that the actual instance is not directly specified. Rather, the samples will all belong to the 'next' instance with instance_handle 'greater' than the specified 'previous_handle' that has available samples.

This operation implies the existence of a total order 'greater-than' relationship between the instance handles. The specifics of this relationship are not all important and are implementation specific. The important thing is that, according to the middleware, all instances are ordered relative to each other. This ordering is between the instance handles; It should not depend on the state of the instance (e.g. whether it has data or not) and must be defined even for instance handles that do not correspond to instances currently managed by the DDS_DataReader. For the purposes of the ordering, it should be 'as if' each instance handle was represented as unique integer.

The behavior of FooDataReader_read_next_instance is 'as if' the DDS_DataReader invoked FooDataReader_read_instance, passing the smallest instance_handle among all the ones that: (a) are greater than previous_handle, and (b) have available samples (i.e. samples that meet the constraints imposed by the specified states).

The special value DDS_HANDLE_NIL is guaranteed to be 'less than' any valid instance_handle. So the use of the parameter value previous_handle == DDS_HANDLE_NIL will return the samples for the instance which has the smallest instance_handle among all the instances that contain available samples.

Note
The operation FooDataReader_read_next_instance is intended to be used in an application-driven iteration, where the application starts by passing previous_handle == DDS_HANDLE_NIL, examines the samples returned, and then uses the instance_handle returned in the DDS_SampleInfo as the value of the previous_handle argument to the next call to FooDataReader_read_next_instance. The iteration continues until FooDataReader_read_next_instance fails with DDS_RETCODE_NO_DATA. This application-driven iteration is required to ensure that all samples on the reader queue are read.

Note that it is possible to call the FooDataReader_read_next_instance operation with a previous_handle that does not correspond to an instance currently managed by the DDS_DataReader. This is because as stated earlier the 'greater-than' relationship is defined even for handles not managed by the DDS_DataReader. One practical situation where this may occur is when an application is iterating though all the instances, takes all the samples of a DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE instance, returns the loan (at which point the instance information may be removed, and thus the handle becomes invalid), and tries to read the next instance. The behavior of the FooDataReader_read_next_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.

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, up to the limits described in the documentation for FooDataReader_take().
previous_handle<<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned. Must be a valid non-NULL DDS_InstanceHandle_t. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
sample_states<<in>> data samples matching ones of these sample_states are returned. See the valid values for this parameter here: DDS_SampleStateKind.
view_states<<in>> data samples matching ones of these view_state are returned. See the valid values for this parameter here: DDS_ViewStateKind.
instance_states<<in>> data samples matching ones of these instance_state are returned. See the valid values for this parameter here: DDS_InstanceStateKind.
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

◆ FooDataReader_take_next_instance()

DDS_ReturnCode_t FooDataReader_take_next_instance ( FooDataReader self,
struct FooSeq received_data,
struct DDS_SampleInfoSeq info_seq,
DDS_Long  max_samples,
const DDS_InstanceHandle_t previous_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 and 'removes' them from the DDS_DataReader.

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

Note
Like FooDataReader_read_next_instance, this operation is intended to be used in an application-driven iteration until all samples on the reader queue are taken. The iteration continues until FooDataReader_take_next_instance fails with the value DDS_RETCODE_NO_DATA .

Similar to the operation FooDataReader_read_next_instance, it is possible to call FooDataReader_take_next_instance with a previous_handle that does not correspond to an instance currently managed by the DDS_DataReader.

The behavior of the FooDataReader_take_next_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_next_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.

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, up to the limits described in the documentation for FooDataReader_take().
previous_handle<<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned. Must be a valid non-NULL DDS_InstanceHandle_t. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
sample_states<<in>> data samples matching ones of these sample_states are returned.
view_states<<in>> data samples matching ones of these view_state are returned.
instance_states<<in>> data samples matching ones of these instance_state are returned.
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

◆ FooDataReader_read_next_instance_w_condition()

DDS_ReturnCode_t FooDataReader_read_next_instance_w_condition ( FooDataReader self,
struct FooSeq received_data,
struct DDS_SampleInfoSeq info_seq,
DDS_Long  max_samples,
const DDS_InstanceHandle_t previous_handle,
DDS_ReadCondition condition 
)

Accesses via FooDataReader_read_next_instance the samples that match the criteria specified in the DDS_ReadCondition.

This operation accesses a collection of data values from the DDS_DataReader. The behavior is identical to FooDataReader_read_next_instance, except that all returned samples satisfy the specified condition. In other words, on success, all returned samples belong to the same instance, and the instance is the instance with 'smallest' instance_handle among the ones that verify: (a) instance_handle >= previous_handle, and (b) have samples for which the specified DDS_ReadCondition evaluates to TRUE.

Similar to the operation FooDataReader_read_next_instance, it is possible to call FooDataReader_read_next_instance_w_condition with a previous_handle that does not correspond to an instance currently managed by the DDS_DataReader.

The behavior of the FooDataReader_read_next_instance_w_condition 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_next_instance_w_condition 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.

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, up to the limits described in the documentation for FooDataReader_take().
previous_handle<<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned. Must be a valid non-NULL DDS_InstanceHandle_t. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
condition<<in>> the DDS_ReadCondition to select samples of interest. Cannot be NULL.
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_next_instance
DDS_LENGTH_UNLIMITED

◆ FooDataReader_take_next_instance_w_condition()

DDS_ReturnCode_t FooDataReader_take_next_instance_w_condition ( FooDataReader self,
struct FooSeq received_data,
struct DDS_SampleInfoSeq info_seq,
DDS_Long  max_samples,
const DDS_InstanceHandle_t previous_handle,
DDS_ReadCondition condition 
)

Accesses via FooDataReader_take_next_instance the samples that match the criteria specified in the DDS_ReadCondition.

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

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

Similar to the operation FooDataReader_read_next_instance, it is possible to call FooDataReader_take_next_instance_w_condition with a previous_handle that does not correspond to an instance currently managed by the DDS_DataReader.

The behavior of the FooDataReader_take_next_instance_w_condition 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 FooDataReader_read, the FooDataReader_take_next_instance_w_condition 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.

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, up to the limits described in the documentation for FooDataReader_take().
previous_handle<<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned. Must be a valid non-NULL DDS_InstanceHandle_t. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL.
condition<<in>> the DDS_ReadCondition to select samples of interest. Cannot be NULL.
Returns
One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, or DDS_RETCODE_NO_DATA, DDS_RETCODE_NOT_ENABLED.
See also
FooDataReader_take_next_instance
DDS_LENGTH_UNLIMITED

◆ FooDataReader_return_loan()

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.

◆ FooDataReader_get_key_value()

DDS_ReturnCode_t FooDataReader_get_key_value ( FooDataReader self,
Foo key_holder,
const DDS_InstanceHandle_t handle 
)

Retrieve the instance key that corresponds to an instance handle.

Useful for keyed data types.

The operation will only fill the fields that form the key inside the key_holder instance. If the type has no keys, this function has no effect and exits with no error.

For keyed data types, this operation may fail with DDS_RETCODE_BAD_PARAMETER if the handle does not correspond to an existing data-object known to the DDS_DataReader.

Parameters
self<<in>> Cannot be NULL.
key_holder<<inout>> a user data type specific key holder, whose key fields are filled by this operation. If Foo has no key, this function has no effect. This function will fail with DDS_RETCODE_BAD_PARAMETER if key_holder is NULL.
handle<<in>> the instance whose key is to be retrieved. If Foo has a key, handle must represent an existing instance of type Foo known to the DDS_DataReader. Otherwise, this function will fail with DDS_RETCODE_BAD_PARAMETER.

If Foo has a key and handle is DDS_HANDLE_NIL, this function will fail with DDS_RETCODE_BAD_PARAMETER.

If Foo has a key and handle represents an instance of another type or an instance of type Foo that has been unregistered, this function will fail with DDS_RETCODE_BAD_PARAMETER. If Foo has no key, this function has no effect.

This function will fail with DDS_RETCODE_BAD_PARAMETER if handle is NULL.

Returns
One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.
See also
FooDataWriter_get_key_value

◆ FooDataReader_lookup_instance()

DDS_InstanceHandle_t FooDataReader_lookup_instance ( FooDataReader self,
const Foo key_holder 
)

Retrieves the instance handle that corresponds to an instance key_holder.

Useful for keyed data types.

This operation takes as a parameter an instance and returns a handle that can be used in subsequent operations that accept an instance handle as an argument. The instance parameter is only used for the purpose of examining the fields that define the key. If the instance is unknown to the DataReader, or if for any other reason the Service is unable to provide an instance handle, the Service will return the special value DDS_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

◆ FooDataReader_is_data_consistent()

DDS_ReturnCode_t FooDataReader_is_data_consistent ( FooDataReader self,
DDS_Boolean is_data_consistent,
const Foo sample,
const struct DDS_SampleInfo sample_info 
)

When using Zero Copy transfer over shared memory, checks if the sample has been overwritten by the DataWriter.

When a sample is received via Zero Copy transfer over shared memory, the sample can be reused by the DataWriter once it is removed from the DataWriter's send queue. Since there is no synchronization between the DataReader and the DataWriter, the sample could be overwritten by the DataWriter before it is processed by the DataReader. The FooDataReader_is_data_consistent operation can be used after processing the sample to check if it was overwritten by the DataWriter.

A precondition for using this operation is to set DDS_DataWriterShmemRefTransferModeSettings::enable_data_consistency_check to true.

Warning
This operation cannot be used when the data type is annotated with @language_binding(FLAT_DATA). Reading a FlatData sample delivered with Zero Copy transfer over shared memory while the DataWriter is overwriting it is undefined behavior. An application-level synchronization mechanism is required in this case.
Parameters
self<<in>> Cannot be NULL.
is_data_consistent<<inout>> Set to true if the sample is consistent (i.e., the sample has not been overwritten by the DataWriter)
sample<<in>> Sample to be validated
sample_info<<in>> DDS_SampleInfo object received with the sample
Returns
One of the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET.

◆ DDS_RequestedDeadlineMissedStatus_initialize()

DDS_ReturnCode_t DDS_RequestedDeadlineMissedStatus_initialize ( struct DDS_RequestedDeadlineMissedStatus self)

Initializer for new status instances.

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

DDS_RequestedDeadlineMissedStatus_finalize should be called to free the contained fields that use dynamic memory:

...
free(myStatus);
DDS_ReturnCode_t DDS_RequestedDeadlineMissedStatus_initialize(struct DDS_RequestedDeadlineMissedStatus *self)
Initializer for new status instances.
Parameters
self<<in>> Cannot be NULL.
See also
DDS_RequestedDeadlineMissedStatus_INITIALIZER
DDS_RequestedDeadlineMissedStatus_finalize

◆ DDS_RequestedDeadlineMissedStatus_copy()

DDS_ReturnCode_t DDS_RequestedDeadlineMissedStatus_copy ( struct DDS_RequestedDeadlineMissedStatus self,
const struct DDS_RequestedDeadlineMissedStatus source 
)

Copy the contents of the given status into this status.

Status instances can use dynamic memory because of the sequences contained in some status. 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_RequestedDeadlineMissedStatus_finalize()

DDS_ReturnCode_t DDS_RequestedDeadlineMissedStatus_finalize ( struct DDS_RequestedDeadlineMissedStatus self)

Free any dynamic memory allocated by status instances.

some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).

Note that if this status 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 status instance after calling this function.

Parameters
self<<in>> Cannot be NULL.

◆ DDS_RequestedDeadlineMissedStatus_equals()

DDS_Boolean DDS_RequestedDeadlineMissedStatus_equals ( const struct DDS_RequestedDeadlineMissedStatus left,
const struct DDS_RequestedDeadlineMissedStatus right 
)

Compares two DDS_RequestedDeadlineMissedStatus for equality.

Parameters
left<<in>> This RequestedDeadlineMissedStatus. Can be NULL.
right<<in>> The other RequestedDeadlineMissedStatus to be compared with this status instance. Can be NULL.
Returns
DDS_BOOLEAN_TRUE if the two RequestedDeadlineMissedStatus have equal values, or DDS_BOOLEAN_FALSE otherwise.

◆ DDS_LivelinessChangedStatus_initialize()

DDS_ReturnCode_t DDS_LivelinessChangedStatus_initialize ( struct DDS_LivelinessChangedStatus self)

Initializer for new status instances.

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

DDS_LivelinessChangedStatus_finalize should be called to free the contained fields that use dynamic memory:

DDS_LivelinessChangedStatus *myStatus = malloc(sizeof(struct DDS_LivelinessChangedStatus));
...
free(myStatus);
DDS_ReturnCode_t DDS_LivelinessChangedStatus_initialize(struct DDS_LivelinessChangedStatus *self)
Initializer for new status instances.
DDS_ReturnCode_t DDS_LivelinessChangedStatus_finalize(struct DDS_LivelinessChangedStatus *self)
Free any dynamic memory allocated by status instances.
Parameters
self<<in>> Cannot be NULL.
See also
DDS_LivelinessChangedStatus_INITIALIZER
DDS_LivelinessChangedStatus_finalize

◆ DDS_LivelinessChangedStatus_copy()

DDS_ReturnCode_t DDS_LivelinessChangedStatus_copy ( struct DDS_LivelinessChangedStatus self,
const struct DDS_LivelinessChangedStatus source 
)

Copy the contents of the given status into this status.

Status instances can use dynamic memory because of the sequences contained in some status. 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_LivelinessChangedStatus_finalize()

DDS_ReturnCode_t DDS_LivelinessChangedStatus_finalize ( struct DDS_LivelinessChangedStatus self)

Free any dynamic memory allocated by status instances.

some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).

Note that if this status 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 status instance after calling this function.

Parameters
self<<in>> Cannot be NULL.

◆ DDS_LivelinessChangedStatus_equals()

DDS_Boolean DDS_LivelinessChangedStatus_equals ( const struct DDS_LivelinessChangedStatus left,
const struct DDS_LivelinessChangedStatus right 
)

Compares two DDS_LivelinessChangedStatus for equality.

Parameters
left<<in>> This LivelinessChangedStatus. Can be NULL.
right<<in>> The other LivelinessChangedStatus to be compared with this status instance. Can be NULL.
Returns
DDS_BOOLEAN_TRUE if the two LivelinessChangedStatus have equal values, or DDS_BOOLEAN_FALSE otherwise.

◆ DDS_RequestedIncompatibleQosStatus_initialize()

DDS_ReturnCode_t DDS_RequestedIncompatibleQosStatus_initialize ( struct DDS_RequestedIncompatibleQosStatus self)

Initializer for new status instances.

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

DDS_RequestedIncompatibleQosStatus_finalize should be called to free the contained fields that use dynamic memory:

...
free(myStatus);
DDS_ReturnCode_t DDS_RequestedIncompatibleQosStatus_initialize(struct DDS_RequestedIncompatibleQosStatus *self)
Initializer for new status instances.
See also
DDS_RequestedIncompatibleQosStatus_INITIALIZER
DDS_RequestedIncompatibleQosStatus_finalize

◆ DDS_RequestedIncompatibleQosStatus_copy()

DDS_ReturnCode_t DDS_RequestedIncompatibleQosStatus_copy ( struct DDS_RequestedIncompatibleQosStatus self,
const struct DDS_RequestedIncompatibleQosStatus source 
)

Copy the contents of the given status into this status.

Status instances can use dynamic memory because of the sequences contained in some status. 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_RequestedIncompatibleQosStatus_finalize()

DDS_ReturnCode_t DDS_RequestedIncompatibleQosStatus_finalize ( struct DDS_RequestedIncompatibleQosStatus self)

Free any dynamic memory allocated by status instances.

some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).

Note that if this status 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 status instance after calling this function.

Parameters
self<<in>> Cannot be NULL.

◆ DDS_RequestedIncompatibleQosStatus_equals()

DDS_Boolean DDS_RequestedIncompatibleQosStatus_equals ( const struct DDS_RequestedIncompatibleQosStatus left,
const struct DDS_RequestedIncompatibleQosStatus right 
)

Compares two DDS_RequestedIncompatibleQosStatus for equality.

Parameters
left<<in>> This RequestedIncompatibleQosStatus. Can be NULL.
right<<in>> The other RequestedIncompatibleQosStatus to be compared with this status instance. Can be NULL.
Returns
DDS_BOOLEAN_TRUE if the two RequestedIncompatibleQosStatus have equal values, or DDS_BOOLEAN_FALSE otherwise.

◆ DDS_SampleLostStatus_initialize()

DDS_ReturnCode_t DDS_SampleLostStatus_initialize ( struct DDS_SampleLostStatus self)

Initializer for new status instances.

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

DDS_RequestedIncompatibleQosStatus_finalize should be called to free the contained fields that use dynamic memory:

DDS_SampleLostStatus *myStatus = malloc(sizeof(struct DDS_SampleLostStatus));
...
free(myStatus);
DDS_ReturnCode_t DDS_SampleLostStatus_initialize(struct DDS_SampleLostStatus *self)
Initializer for new status instances.
Parameters
self<<in>> Cannot be NULL.
See also
DDS_SampleLostStatus_INITIALIZER
DDS_SampleLostStatus_finalize

◆ DDS_SampleLostStatus_copy()

DDS_ReturnCode_t DDS_SampleLostStatus_copy ( struct DDS_SampleLostStatus self,
const struct DDS_SampleLostStatus source 
)

Copy the contents of the given status into this status.

Status instances can use dynamic memory because of the sequences contained in some status. 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_SampleLostStatus_finalize()

DDS_ReturnCode_t DDS_SampleLostStatus_finalize ( struct DDS_SampleLostStatus self)

Free any dynamic memory allocated by status instances.

some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).

Note that if this status 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 status instance after calling this function.

Parameters
self<<in>> Cannot be NULL.

◆ DDS_SampleLostStatus_equals()

DDS_Boolean DDS_SampleLostStatus_equals ( const struct DDS_SampleLostStatus left,
const struct DDS_SampleLostStatus right 
)

Compares two DDS_SampleLostStatus for equality.

Parameters
left<<in>> This SampleLostStatus. Can be NULL.
right<<in>> The other SampleLostStatus to be compared with this status instance. Can be NULL.
Returns
DDS_BOOLEAN_TRUE if the two SampleLostStatus have equal values, or DDS_BOOLEAN_FALSE otherwise.

◆ DDS_SampleRejectedStatus_initialize()

DDS_ReturnCode_t DDS_SampleRejectedStatus_initialize ( struct DDS_SampleRejectedStatus self)

Initializer for new status instances.

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

DDS_RequestedIncompatibleQosStatus_finalize should be called to free the contained fields that use dynamic memory:

DDS_SampleRejectedStatus *myStatus = malloc(sizeof(struct DDS_SampleRejectedStatus));
...
free(myStatus);
DDS_ReturnCode_t DDS_SampleRejectedStatus_initialize(struct DDS_SampleRejectedStatus *self)
Initializer for new status instances.
Parameters
self<<in>> Cannot be NULL.
See also
DDS_SampleRejectedStatus_INITIALIZER
DDS_SampleRejectedStatus_finalize

◆ DDS_SampleRejectedStatus_copy()

DDS_ReturnCode_t DDS_SampleRejectedStatus_copy ( struct DDS_SampleRejectedStatus self,
const struct DDS_SampleRejectedStatus source 
)

Copy the contents of the given status into this status.

Status instances can use dynamic memory because of the sequences contained in some status. 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_SampleRejectedStatus_finalize()

DDS_ReturnCode_t DDS_SampleRejectedStatus_finalize ( struct DDS_SampleRejectedStatus self)

Free any dynamic memory allocated by status instances.

some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).

Note that if this status 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 status instance after calling this function.

Parameters
self<<in>> Cannot be NULL.

◆ DDS_SampleRejectedStatus_equals()

DDS_Boolean DDS_SampleRejectedStatus_equals ( const struct DDS_SampleRejectedStatus left,
const struct DDS_SampleRejectedStatus right 
)

Compares two DDS_SampleRejectedStatus for equality.

Parameters
left<<in>> This SampleRejectedStatus. Can be NULL.
right<<in>> The other SampleRejectedStatus to be compared with this status instance. Can be NULL.
Returns
DDS_BOOLEAN_TRUE if the two SampleRejectedStatus have equal values, or DDS_BOOLEAN_FALSE otherwise.

◆ DDS_SubscriptionMatchedStatus_initialize()

DDS_ReturnCode_t DDS_SubscriptionMatchedStatus_initialize ( struct DDS_SubscriptionMatchedStatus self)

Initializer for new status instances.

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

DDS_RequestedIncompatibleQosStatus_finalize should be called to free the contained fields that use dynamic memory:

...
free(myStatus);
DDS_ReturnCode_t DDS_SubscriptionMatchedStatus_initialize(struct DDS_SubscriptionMatchedStatus *self)
Initializer for new status instances.
Parameters
self<<in>> Cannot be NULL.
See also
DDS_SubscriptionMatchedStatus_INITIALIZER
DDS_SubscriptionMatchedStatus_finalize

◆ DDS_SubscriptionMatchedStatus_copy()

DDS_ReturnCode_t DDS_SubscriptionMatchedStatus_copy ( struct DDS_SubscriptionMatchedStatus self,
const struct DDS_SubscriptionMatchedStatus source 
)

Copy the contents of the given status into this status.

Status instances can use dynamic memory because of the sequences contained in some status. 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_SubscriptionMatchedStatus_finalize()

DDS_ReturnCode_t DDS_SubscriptionMatchedStatus_finalize ( struct DDS_SubscriptionMatchedStatus self)

Free any dynamic memory allocated by status instances.

some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).

Note that if this status 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 status instance after calling this function.

Parameters
self<<in>> Cannot be NULL.

◆ DDS_SubscriptionMatchedStatus_equals()

DDS_Boolean DDS_SubscriptionMatchedStatus_equals ( const struct DDS_SubscriptionMatchedStatus left,
const struct DDS_SubscriptionMatchedStatus right 
)

Compares two DDS_SubscriptionMatchedStatus for equality.

Parameters
left<<in>> This SubscriptionMatchedStatus. Can be NULL.
right<<in>> The other SubscriptionMatchedStatus to be compared with this status instance. Can be NULL.
Returns
DDS_BOOLEAN_TRUE if the two SubscriptionMatchedStatus have equal values, or DDS_BOOLEAN_FALSE otherwise.

◆ DDS_DataReaderCacheStatus_initialize()

DDS_ReturnCode_t DDS_DataReaderCacheStatus_initialize ( struct DDS_DataReaderCacheStatus self)

Initializer for new status instances.

New DDS_DataReaderCacheStatus instance on heap should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.

DDS_DataReaderCacheStatus_finalize should be called to free the contained fields that use dynamic memory:

DDS_DataReaderCacheStatus *myStatus = malloc(sizeof(struct DDS_DataReaderCacheStatus));
free(myStatus);
DDS_ReturnCode_t DDS_DataReaderCacheStatus_initialize(struct DDS_DataReaderCacheStatus *self)
Initializer for new status instances.
Returns
One of the Standard Return Codes
See also
DDS_DataReader_get_datareader_cache_status
DDS_DataReaderCacheStatus_finalize

◆ DDS_DataReaderCacheStatus_copy()

DDS_ReturnCode_t DDS_DataReaderCacheStatus_copy ( struct DDS_DataReaderCacheStatus self,
const struct DDS_DataReaderCacheStatus source 
)

Copy the contents of the given status into this status.

Status instances can use dynamic memory because of the sequences contained in some status. 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.
Returns
One of the Standard Return Codes
See also
DDS_DataReaderCacheStatus_INITIALIZER
DDS_DataReaderCacheStatus_initialize
DDS_DataReaderCacheStatus_finalize

◆ DDS_DataReaderCacheStatus_finalize()

DDS_ReturnCode_t DDS_DataReaderCacheStatus_finalize ( struct DDS_DataReaderCacheStatus self)

Free any dynamic memory allocated by status instances.

some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).

Note that if this status 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 status instance after calling this function.

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_DataReaderCacheStatus_INITIALIZER
DDS_DataReaderCacheStatus_initialize

◆ DDS_DataReaderCacheStatus_equals()

DDS_Boolean DDS_DataReaderCacheStatus_equals ( const struct DDS_DataReaderCacheStatus left,
const struct DDS_DataReaderCacheStatus right 
)

Compares two DDS_DataReaderCacheStatus for equality.

Parameters
left<<in>> This DataReaderCacheStatus. Can be NULL.
right<<in>> The other DataReaderCacheStatus to be compared with this status instance. Can be NULL.
Returns
DDS_BOOLEAN_TRUE if the two DataReaderCacheStatus have equal values, or DDS_BOOLEAN_FALSE otherwise.

◆ DDS_DataReaderProtocolStatus_initialize()

DDS_ReturnCode_t DDS_DataReaderProtocolStatus_initialize ( struct DDS_DataReaderProtocolStatus self)

Initializer for new status instances.

New DDS_DataReaderProtocolStatus instance on heap should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.

DDS_DataReaderProtocolStatus_finalize should be called to free the contained fields that use dynamic memory:

DDS_DataReaderProtocolStatus *myStatus = malloc(sizeof(struct DDS_DataReaderProtocolStatus));
free(myStatus);
DDS_ReturnCode_t DDS_DataReaderProtocolStatus_initialize(struct DDS_DataReaderProtocolStatus *self)
Initializer for new status instances.
Returns
One of the Standard Return Codes
See also
DDS_DataReader_get_datareader_protocol_status
DDS_DataReaderProtocolStatus_finalize

◆ DDS_DataReaderProtocolStatus_copy()

DDS_ReturnCode_t DDS_DataReaderProtocolStatus_copy ( struct DDS_DataReaderProtocolStatus self,
const struct DDS_DataReaderProtocolStatus source 
)

Copy the contents of the given status into this status.

Status instances can use dynamic memory because of the sequences contained in some status. 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.
Returns
One of the Standard Return Codes
See also
DDS_DataReaderProtocolStatus_INITIALIZER
DDS_DataReaderProtocolStatus_initialize
DDS_DataReaderProtocolStatus_finalize

◆ DDS_DataReaderProtocolStatus_finalize()

DDS_ReturnCode_t DDS_DataReaderProtocolStatus_finalize ( struct DDS_DataReaderProtocolStatus self)

Free any dynamic memory allocated by status instances.

some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).

Note that if this status 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 status instance after calling this function.

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_DataReaderProtocolStatus_INITIALIZER
DDS_DataReaderProtocolStatus_initialize

◆ DDS_DataReaderProtocolStatus_equals()

DDS_Boolean DDS_DataReaderProtocolStatus_equals ( const struct DDS_DataReaderProtocolStatus left,
const struct DDS_DataReaderProtocolStatus right 
)

Compares two DDS_DataReaderProtocolStatus for equality.

Parameters
left<<in>> This DataReaderProtocolStatus. Can be NULL.
right<<in>> The other DataReaderProtocolStatus to be compared with this status instance. Can be NULL.
Returns
DDS_BOOLEAN_TRUE if the two DataReaderProtocolStatus have equal values, or DDS_BOOLEAN_FALSE otherwise.

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

◆ DDS_DataReaderQos_print()

DDS_ReturnCode_t DDS_DataReaderQos_print ( const struct DDS_DataReaderQos self)

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_w_params. The output is formatted according to the default values for DDS_QosPrintFormat.

Parameters
self<<in>> Cannot be NULL.
Returns
DDS_RETCODE_OK if no error was encountered.

◆ DDS_DataReaderQos_to_string()

DDS_ReturnCode_t DDS_DataReaderQos_to_string ( const struct DDS_DataReaderQos self,
char *  string,
DDS_UnsignedLong string_size 
)

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_w_params. 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
self<<in>> Cannot be NULL.
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_w_params

◆ DDS_DataReaderQos_to_string_w_params()

DDS_ReturnCode_t DDS_DataReaderQos_to_string_w_params ( const struct DDS_DataReaderQos self,
char *  string,
DDS_UnsignedLong string_size,
const struct DDS_DataReaderQos base,
const struct DDS_QosPrintFormat format 
)

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.

It is possible to supply the sentinel value DDS_DATAREADER_QOS_PRINT_ALL as the base to print everything within the QoS.

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
self<<in>> Cannot be NULL.
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.

◆ DDS_DataReaderQos_initialize()

DDS_ReturnCode_t DDS_DataReaderQos_initialize ( struct DDS_DataReaderQos self)

Initializer for new QoS instances.

New DDS_DataReaderQos instances on 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.

Calling this function is not a substitute for calling DDS_DataReader_get_qos or DDS_DomainParticipant_get_default_datareader_qos; one of those should be called subsequently to setting the QoS of any new or existing entity. DDS_DataReaderQos_finalize should be called to free the contained QoS policies that use dynamic memory:

DDS_DataReaderQos *myQos = malloc(sizeof(struct DDS_DataReaderQos));
DDS_DomainParticipantFactory_get_default_datareader_qos(myFactory, myQos);
DDS_DataReaderQos_set_qos(myDataReader, myQos);
free(myQos);
DDS_ReturnCode_t DDS_DataReaderQos_finalize(struct DDS_DataReaderQos *self)
Free any dynamic memory allocated by the policies in this DDS_DataReaderQos.
DDS_ReturnCode_t DDS_DataReaderQos_initialize(struct DDS_DataReaderQos *self)
Initializer for new QoS instances.
Parameters
self<<in>> Cannot be NULL.
See also
DDS_DataReaderQos_INITIALIZER
DDS_DomainParticipant_get_default_datareader_qos
DDS_DataReaderQos_finalize

◆ DDS_DataReaderQos_copy()

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_DataReaderQos_finalize()

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_DataReader_as_entity()

DDS_Entity * DDS_DataReader_as_entity ( DDS_DataReader dataReader)

Accesses the DDS_DataReader's supertype instance.

Parameters
dataReader<<in>> Cannot be NULL.

◆ DDS_DataReader_create_readcondition()

DDS_ReadCondition * DDS_DataReader_create_readcondition ( DDS_DataReader self,
DDS_SampleStateMask  sample_states,
DDS_ViewStateMask  view_states,
DDS_InstanceStateMask  instance_states 
)

Creates a DDS_ReadCondition.

The returned DDS_ReadCondition will be attached and belong to the DDS_DataReader.

Parameters
self<<in>> Cannot be NULL.
sample_states<<in>> sample state of the data samples that are of interest
view_states<<in>> view state of the data samples that are of interest
instance_states<<in>> instance state of the data samples that are of interest
Returns
return DDS_ReadCondition created. Returns NULL in case of failure.

◆ DDS_DataReader_create_readcondition_w_params()

DDS_ReadCondition * DDS_DataReader_create_readcondition_w_params ( DDS_DataReader self,
const struct DDS_ReadConditionParams params 
)

<<extension>> Creates a DDS_ReadCondition with parameters.

The returned DDS_ReadCondition will be attached and belong to the DDS_DataReader.

Parameters
self<<in>> Cannot be NULL.
params<<in>> creation parameters.
Returns
return DDS_ReadCondition created. Returns NULL in case of failure.

◆ DDS_DataReader_create_querycondition()

DDS_QueryCondition * DDS_DataReader_create_querycondition ( DDS_DataReader self,
DDS_SampleStateMask  sample_states,
DDS_ViewStateMask  view_states,
DDS_InstanceStateMask  instance_states,
const char *  query_expression,
const struct DDS_StringSeq query_parameters 
)

Creates a DDS_QueryCondition.

The returned DDS_QueryCondition will be attached and belong to the DDS_DataReader.

Queries and Filters Syntax describes the syntax of query_expression and query_parameters.

Parameters
self<<in>> Cannot be NULL.
sample_states<<in>> sample state of the data samples that are of interest
view_states<<in>> view state of the data samples that are of interest
instance_states<<in>> instance state of the data samples that are of interest
query_expression<<in>> Expression for the query. Cannot be NULL.
query_parameters<<in>> Parameters for the query expression. Cannot be NULL.
Returns
return DDS_QueryCondition created. Returns NULL in case of failure.

◆ DDS_DataReader_create_querycondition_w_params()

DDS_QueryCondition * DDS_DataReader_create_querycondition_w_params ( DDS_DataReader self,
const struct DDS_QueryConditionParams params 
)

<<extension>> Creates a DDS_QueryCondition with parameters.

The returned DDS_QueryCondition will be attached and belong to the DDS_DataReader.

Parameters
self<<in>> Cannot be NULL.
params<<in>> creation parameters.
Returns
return DDS_QueryCondition created. Returns NULL in case of failure.

◆ DDS_DataReader_delete_readcondition()

DDS_ReturnCode_t DDS_DataReader_delete_readcondition ( DDS_DataReader self,
DDS_ReadCondition condition 
)

Deletes a DDS_ReadCondition or DDS_QueryCondition attached to the DDS_DataReader.

Since DDS_QueryCondition specializes DDS_ReadCondition, it can also be used to delete a DDS_QueryCondition.

Precondition
The DDS_ReadCondition must be attached to the DDS_DataReader, or the operation will fail with the error DDS_RETCODE_PRECONDITION_NOT_MET.
MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
Parameters
self<<in>> Cannot be NULL.
condition<<in>> Condition to be deleted.
Returns
One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET

◆ DDS_DataReader_delete_contained_entities()

DDS_ReturnCode_t DDS_DataReader_delete_contained_entities ( DDS_DataReader self)

Deletes all the entities that were created by means of the "create" operations on the DDS_DataReader.

Deletes all contained DDS_ReadCondition, DDS_QueryCondition, and DDS_TopicQuery objects.

The operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET if the any of the contained entities is in a state where it cannot be deleted.

Once DDS_DataReader_delete_contained_entities completes successfully, the application may delete the DDS_DataReader.

MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET

◆ DDS_DataReader_wait_for_historical_data()

DDS_ReturnCode_t DDS_DataReader_wait_for_historical_data ( DDS_DataReader self,
const struct DDS_Duration_t max_wait 
)

Waits until all "historical" data is received for DDS_DataReader entities that have a non-VOLATILE Durability Qos kind.

This operation is intended only for DDS_DataReader entities that have a non-VOLATILE Durability QoS kind.

As soon as an application enables a non-VOLATILE DDS_DataReader, it will start receiving both "historical" data (i.e., the data that was written prior to the time the DDS_DataReader joined the domain) as well as any new data written by the DDS_DataWriter entities. There are situations where the application logic may require the application to wait until all "historical" data is received. This is the purpose of the DDS_DataReader_wait_for_historical_data operations.

DDS_DataReader_wait_for_historical_data() blocks the calling thread until either all "historical" data is received, or until the duration specified by the max_wait parameter elapses, whichever happens first. It will return immediately if no DataWriters have been discovered at the time the operation is called; therefore it is advisable to make sure at least one DDS_DataWriter has been discovered before calling this operation. (One way to do this is by using DDS_DataReader_get_subscription_matched_status.)

A successful completion indicates that all the "historical" data was "received"; timing out indicates that max_wait elapsed before all the data was received.

Parameters
self<<in>> Cannot be NULL.
max_wait<<in>> Timeout value. Cannot be NULL.
Returns
One of the Standard Return Codes, DDS_RETCODE_TIMEOUT or DDS_RETCODE_NOT_ENABLED.

◆ DDS_DataReader_acknowledge_sample_w_response()

DDS_ReturnCode_t DDS_DataReader_acknowledge_sample_w_response ( DDS_DataReader self,
const struct DDS_SampleInfo sample_info,
const struct DDS_AckResponseData_t response_data 
)

<<extension>> Acknowledges a single sample explicitly.

Applicable only when DDS_ReliabilityQosPolicy::acknowledgment_kind = DDS_APPLICATION_EXPLICIT_ACKNOWLEDGMENT_MODE

A call to this function does not necessarily trigger the sending of an AppAck RTPS message from the DataReader to the DataWriter. How and when AppAck messages are sent can be configured using the QoS values DDS_RtpsReliableReaderProtocol_t::samples_per_app_ack and DDS_RtpsReliableReaderProtocol_t::app_ack_period.

The maximum length of the response is configured using DDS_DataReaderResourceLimitsQosPolicy::max_app_ack_response_length

Parameters
self<<in>> Cannot be NULL.
sample_info<<in>> DDS_SampleInfo identifying the sample being acknowledged.
response_data<<in>> Response data sent to DDS_DataWriter upon acknowledgment (via DDS_DataWriterListener::on_application_acknowledgment)
Returns
One of the Standard Return Codes

◆ DDS_DataReader_acknowledge_all_w_response()

DDS_ReturnCode_t DDS_DataReader_acknowledge_all_w_response ( DDS_DataReader self,
const struct DDS_AckResponseData_t response_data 
)

<<extension>> Acknowledges all previously accessed samples.

Applicable only when DDS_ReliabilityQosPolicy::acknowledgment_kind = DDS_APPLICATION_EXPLICIT_ACKNOWLEDGMENT_MODE

A call to this function does not necessarily trigger the sending of an AppAck RTPS message from the DataReader to the DataWriter. How and when AppAck messages are sent can be configured using the QoS values DDS_RtpsReliableReaderProtocol_t::samples_per_app_ack and DDS_RtpsReliableReaderProtocol_t::app_ack_period.

The maximum length of the response is configured using DDS_DataReaderResourceLimitsQosPolicy::max_app_ack_response_length.

Parameters
self<<in>> Cannot be NULL.
response_data<<in>> Response data sent to DDS_DataWriter upon acknowledgment
Returns
One of the Standard Return Codes

◆ DDS_DataReader_acknowledge_sample()

DDS_ReturnCode_t DDS_DataReader_acknowledge_sample ( DDS_DataReader self,
const struct DDS_SampleInfo sample_info 
)

<<extension>> Acknowledges a single sample explicitly.

Applicable only when DDS_ReliabilityQosPolicy::acknowledgment_kind = DDS_APPLICATION_EXPLICIT_ACKNOWLEDGMENT_MODE

A call to this function does not necessarily trigger the sending of an AppAck RTPS message from the DataReader to the DataWriter. How and when AppAck messages are sent can be configured using the QoS values DDS_RtpsReliableReaderProtocol_t::samples_per_app_ack and DDS_RtpsReliableReaderProtocol_t::app_ack_period.

Parameters
self<<in>> Cannot be NULL.
sample_info<<in>> DDS_SampleInfo identifying the sample being acknowledged.
Returns
One of the Standard Return Codes

◆ DDS_DataReader_acknowledge_all()

DDS_ReturnCode_t DDS_DataReader_acknowledge_all ( DDS_DataReader self)

<<extension>> Acknowledges all previously accessed samples.

Applicable only when DDS_ReliabilityQosPolicy::acknowledgment_kind = DDS_APPLICATION_EXPLICIT_ACKNOWLEDGMENT_MODE

A call to this function does not necessarily trigger the sending of an AppAck RTPS message from the DataReader to the DataWriter. How and when AppAck messages are sent can be configured using the QoS values DDS_RtpsReliableReaderProtocol_t::samples_per_app_ack and DDS_RtpsReliableReaderProtocol_t::app_ack_period.

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes

◆ DDS_DataReader_get_matched_publications()

DDS_ReturnCode_t DDS_DataReader_get_matched_publications ( DDS_DataReader self,
struct DDS_InstanceHandleSeq publication_handles 
)

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

A publication is considered to be matching if all of the following criteria are true:

  • The publication is within the same domain as this subscription.
  • The publication has a matching DDS_Topic.
  • The publication has compatible QoS.
  • If the applications are using partitions, the publication shares a common partition with this subscription.
  • The DDS_DomainParticipant has not indicated that the publication's DDS_DomainParticipant should be "ignored" by means of the DDS_DomainParticipant_ignore_publication API.
  • If the subscription is using a DDS_ContentFilteredTopic and the publication is using the DDS_MultiChannelQosPolicy, there is an intersection between at least one of the associated filters.
  • If the endpoints need to exchange key material to communicate (i.e., they are securing their communications), the reader has completed the key exchange with the writer.

The handles returned in the publication_handles list are the ones that are used by the RTI Connext 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.

This API may return the publication handles of publications that are not alive. DDS_DataReader_is_matched_publication_alive can be used to check the liveliness of the remote publication.

Parameters
self<<in>> Cannot be NULL.
publication_handles<<inout>>. 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 of the matches and the system cannot 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 cannot resize it, or DDS_RETCODE_NOT_ENABLED

◆ DDS_DataReader_is_matched_publication_alive()

DDS_ReturnCode_t DDS_DataReader_is_matched_publication_alive ( DDS_DataReader self,
DDS_Boolean is_alive,
const DDS_InstanceHandle_t publication_handle 
)

Check if a publication currently matched with a DataReader is alive.

This API is used for querying the endpoint liveliness of a matched publication. A matched publication will be marked as not alive if the liveliness that it committed to through its LIVELINESS QoS policy was not respected. Note that if the participant associated with the matched publication loses liveliness, the DDS_InstanceHandle_t will become invalid and this function will fail with DDS_RETCODE_BAD_PARAMETER.

Parameters
self<<in>> Cannot be NULL.
publication_handle<<in>> The DDS_InstanceHandle_t of the matched publication. See DDS_DataReader_get_matched_publications for a description of what is considered a matched publication.
is_alive<<out>> Indicates whether or not the matched publication is alive.
Returns
One of the Standard Return Codes

◆ DDS_DataReader_get_matched_publication_data()

DDS_ReturnCode_t DDS_DataReader_get_matched_publication_data ( DDS_DataReader self,
struct DDS_PublicationBuiltinTopicData publication_data,
const DDS_InstanceHandle_t publication_handle 
)

Retrieves the information on a publication that is currently "associated" with the DDS_DataReader.

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.

Note: This operation does not retrieve the DDS_PublicationBuiltinTopicData::type_code. This information is available through DDS_DataReaderListener::on_data_available() (if a reader listener is installed on the DDS_PublicationBuiltinTopicDataDataReader).

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. Must correspond to a publication currently associated with the DDS_DataReader. Cannot be NULL.
Returns
One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED

◆ DDS_DataReader_get_matched_publication_participant_data()

DDS_ReturnCode_t DDS_DataReader_get_matched_publication_participant_data ( DDS_DataReader self,
struct DDS_ParticipantBuiltinTopicData participant_data,
const DDS_InstanceHandle_t publication_handle 
)

<<extension>> Retrieves the information on the discovered DDS_DomainParticipant associated with the publication that is currently matching with the DDS_DataReader.

The publication_handle must correspond to a publication currently associated with the DDS_DataReader. Otherwise, the operation will fail with DDS_RETCODE_BAD_PARAMETER. The operation may also fail with DDS_RETCODE_PRECONDITION_NOT_MET if the publication corresponds to the same DDS_DomainParticipant that the DataReader belongs to. 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.
participant_data<<inout>>. The information to be filled in on the associated participant. Cannot be NULL.
publication_handle<<in>>. Handle to a specific publication associated with a DDS_DataWriter. Must correspond to a publication currently associated with the DDS_DataReader. Cannot be NULL.
Returns
One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED

◆ DDS_DataReader_get_topicdescription()

DDS_TopicDescription * DDS_DataReader_get_topicdescription ( DDS_DataReader self)

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_DataReader_get_subscriber()

DDS_Subscriber * DDS_DataReader_get_subscriber ( DDS_DataReader self)

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_DataReader_get_sample_rejected_status()

DDS_ReturnCode_t DDS_DataReader_get_sample_rejected_status ( DDS_DataReader self,
struct DDS_SampleRejectedStatus status 
)

Accesses the DDS_SAMPLE_REJECTED_STATUS communication status.

This also resets the status so that it is no longer considered changed.

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_DataReader_get_liveliness_changed_status()

DDS_ReturnCode_t DDS_DataReader_get_liveliness_changed_status ( DDS_DataReader self,
struct DDS_LivelinessChangedStatus status 
)

Accesses the DDS_LIVELINESS_CHANGED_STATUS communication status.

This also resets the status so that it is no longer considered changed.

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_DataReader_get_requested_deadline_missed_status()

DDS_ReturnCode_t DDS_DataReader_get_requested_deadline_missed_status ( DDS_DataReader self,
struct DDS_RequestedDeadlineMissedStatus status 
)

Accesses the DDS_REQUESTED_DEADLINE_MISSED_STATUS communication status.

This also resets the status so that it is no longer considered changed.

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_DataReader_get_requested_incompatible_qos_status()

DDS_ReturnCode_t DDS_DataReader_get_requested_incompatible_qos_status ( DDS_DataReader self,
struct DDS_RequestedIncompatibleQosStatus status 
)

Accesses the DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS communication status.

This also resets the status so that it is no longer considered changed.

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_DataReader_get_subscription_matched_status()

DDS_ReturnCode_t DDS_DataReader_get_subscription_matched_status ( DDS_DataReader self,
struct DDS_SubscriptionMatchedStatus status 
)

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_DataReader_get_sample_lost_status()

DDS_ReturnCode_t DDS_DataReader_get_sample_lost_status ( DDS_DataReader self,
struct DDS_SampleLostStatus status 
)

Accesses the DDS_SAMPLE_LOST_STATUS communication status.

This also resets the status so that it is no longer considered changed.

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_DataReader_get_datareader_cache_status()

DDS_ReturnCode_t DDS_DataReader_get_datareader_cache_status ( DDS_DataReader self,
struct DDS_DataReaderCacheStatus status 
)

<<extension>> Gets the datareader cache status for this reader.

Parameters
self<<in>> Cannot be NULL.
status<<inout>> DDS_DataReaderCacheStatus to be filled in. Cannot be NULL.
Returns
One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

◆ DDS_DataReader_get_datareader_protocol_status()

DDS_ReturnCode_t DDS_DataReader_get_datareader_protocol_status ( DDS_DataReader self,
struct DDS_DataReaderProtocolStatus status 
)

<<extension>> Gets the datareader protocol status for this reader.

This also resets the status so that it is no longer considered changed.

Parameters
self<<in>> Cannot be NULL.
status<<inout>> DDS_DataReaderProtocolStatus to be filled in. Cannot be NULL.
Returns
One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

◆ DDS_DataReader_get_matched_publication_datareader_protocol_status()

DDS_ReturnCode_t DDS_DataReader_get_matched_publication_datareader_protocol_status ( DDS_DataReader self,
struct DDS_DataReaderProtocolStatus status,
const DDS_InstanceHandle_t publication_handle 
)

<<extension>> Gets the datareader protocol status for this reader, per matched publication identified by the publication_handle.

This also resets the status so that it is no longer considered changed.

Note: Status for a remote entity is only kept while the entity is alive. Once a remote entity is no longer alive, its status is deleted.

Parameters
self<<in>> Cannot be NULL.
status<<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_DataReader_set_qos()

DDS_ReturnCode_t DDS_DataReader_set_qos ( DDS_DataReader self,
const struct DDS_DataReaderQos qos 
)

Sets the reader QoS.

Modifies the QoS of the DDS_DataReader.

The DDS_DataReaderQos::user_data, DDS_DataReaderQos::deadline, DDS_DataReaderQos::latency_budget, DDS_DataReaderQos::time_based_filter, DDS_DataReaderQos::reader_data_lifecycle 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. Immutable 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
Operations Allowed in Listener Callbacks

◆ DDS_DataReader_set_qos_with_profile()

DDS_ReturnCode_t DDS_DataReader_set_qos_with_profile ( DDS_DataReader self,
const char *  library_name,
const char *  profile_name 
)

<<extension>> Changes the QoS of this reader using the input XML QoS profile.

This operation modifies the QoS of the DDS_DataReader.

The DDS_DataReaderQos::user_data, DDS_DataReaderQos::deadline, DDS_DataReaderQos::latency_budget, DDS_DataReaderQos::time_based_filter, DDS_DataReaderQos::reader_data_lifecycle can be changed. The other policies are immutable.

Parameters
self<<in>> Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS_Subscriber_set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_Subscriber_set_default_profile).
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
DDS_DataReader_set_qos
Operations Allowed in Listener Callbacks

◆ DDS_DataReader_get_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_DataReader_set_property()

DDS_ReturnCode_t DDS_DataReader_set_property ( DDS_DataReader self,
const char *  property_name,
const char *  value,
DDS_Boolean  propagate 
)

Set the value for a property that applies to a DataReader.

Warning
This function is not implemented in all APIs and it's intended only for testing purposes. You should use DDS_DataReader_set_qos instead.
Parameters
self<<in>> Cannot be NULL.
property_name<<in>>. Name of the property that you want to set.
value<<in>>. New value for the property.
propagate<<in>>. Indicates if the property will be propagated or not.
Returns
One of the Standard Return Codes
See also
DDS_DomainParticipant_set_property
DDS_DataWriter_set_property
DDS_DataReader_set_qos

◆ DDS_DataReader_set_listener()

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)

◆ DDS_DataReader_get_listener()

struct DDS_DataReaderListener DDS_DataReader_get_listener ( DDS_DataReader self)

Gets the reader listener.

Parameters
self<<in>> Cannot be NULL.
Returns
DDS_DataReaderListener of the DDS_DataReader.
See also
DDS_DataReader_get_listenerX
get_listener (abstract)

◆ DDS_DataReader_get_listenerX()

DDS_ReturnCode_t DDS_DataReader_get_listenerX ( DDS_DataReader self,
struct DDS_DataReaderListener listener 
)

<<extension>> Gets the reader listener.

An alternative form of get_listener that fills in an existing listener structure rather than returning one on the stack.

Parameters
self<<in>> Cannot be NULL.
listener<<inout>> DDS_DataReaderListener structure to be filled up. Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_DataReader_get_listener
get_listener (abstract)

◆ DDS_DataReader_create_topic_query()

DDS_TopicQuery * DDS_DataReader_create_topic_query ( DDS_DataReader self,
const struct DDS_TopicQuerySelection selection 
)

Creates a DDS_TopicQuery.

The returned DDS_TopicQuery will have been issued if the DDS_DataReader is enabled. Otherwise, the DDS_TopicQuery will be issued once the DDS_DataReader is enabled

Parameters
self<<in>> Cannot be NULL.
selection<<in>> The selection with which to create the DDS_TopicQuery. The special values DDS_TOPIC_QUERY_SELECTION_SELECT_ALL and DDS_TOPIC_QUERY_SELECTION_USE_READER_CONTENT_FILTER can be used. The expression can start with the special condition "@instance_state = ALIVE AND" followed by the rest of the expression. This restricts the selection to samples of alive instances. Cannot be NULL.
Returns
return Created DDS_TopicQuery. Returns NULL in case of failure.

◆ DDS_DataReader_delete_topic_query()

DDS_ReturnCode_t DDS_DataReader_delete_topic_query ( DDS_DataReader self,
DDS_TopicQuery query 
)

Deletes a DDS_TopicQuery.

Cancels an active DDS_TopicQuery. After deleting a TopicQuery, new DataWriters won't discover it and existing DataWriters currently publishing cached samples may stop before delivering all of them.

Parameters
self<<in>> Cannot be NULL.
query<<in>> The DDS_TopicQuery to delete. Cannot be NULL.
Returns
One of the Standard Return Codes

◆ DDS_DataReader_lookup_topic_query()

DDS_TopicQuery * DDS_DataReader_lookup_topic_query ( DDS_DataReader self,
const struct DDS_GUID_t guid 
)

Retrieves an existing DDS_TopicQuery.

Retrieves the DDS_TopicQuery that corresponds to the input DDS_GUID_t.

If no TopicQuery is found for the specified GUID or the TopicQuery is marked for deletion, this returns NULL.

To get the DDS_GUID_t associated with a DDS_TopicQuery, use the function DDS_TopicQuery_get_guid.

Parameters
self<<in>> Cannot be NULL.
guid<<in>> The DDS_TopicQuery GUID. Cannot be NULL.

◆ DDS_DataReader_take_discovery_snapshot()

DDS_ReturnCode_t DDS_DataReader_take_discovery_snapshot ( DDS_DataReader self,
const char *  file_name 
)

Take a snapshot of the compatible and incompatible remote writers matched by a local reader.

A possible output may be the following:

Remote writers that match the local reader domain=0 name="readerTestName"
guid="0x0101542A,0x2C59B595,0xA1693BDF:0x80000004"
topic="FooTopic" type="FooType"
----------------------------------------------------------------------------
Compatible writers:
1. 0x0101D8D1,0x20B83C0D,0x4495246E:0x80000003 name="writer1TestName"
kind="unkeyed user datareader"
unicastLocators="udpv4://192.168.1.170:7411"
liveliness="ALIVE"
Incompatible writers:
1. 0x0101D8D1,0x20B83C0D,0x4495246E:0x80000103 name="writer2TestName"
kind="unkeyed user datareader"
unicastLocators="udpv4://192.168.1.170:7411"
reason="Inconsistent QoS"
----------------------------------------------------------------------------
Precondition
self is not NULL.
Parameters
self<<in>> The local reader.
file_name<<in>> Name of the file where snapshot should be printed. If NULL, the snapshot will be printed through NDDS_Config_Logger. Otherwise, the snapshot will be printed in the file specified by file_name.
Returns
One of the Standard Return Codes.