dds_c_subscription.h File Reference

DDS subscription module. More...

#include "dds_c_sequence.h"
#include "dds_c/dds_c_type.h"
#include "dds_c/dds_c_topic.h"
#include "dds_c/dds_c_dll.h"
#include "dds_c/dds_c_rh_plugin.h"

Go to the source code of this file.

Data Structures
struct	DDS_RequestedDeadlineMissedStatus
	<<cert>> DDS_REQUESTED_DEADLINE_MISSED_STATUS More...
struct	DDS_LivelinessChangedStatus
	<<cert>> DDS_LIVELINESS_CHANGED_STATUS More...
struct	DDS_RequestedIncompatibleQosStatus
	<<cert>> DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS More...
struct	DDS_SampleRejectedStatus
	DDS_SAMPLE_REJECTED_STATUSA status structure describing the samples rejected by the reader. More...
struct	DDS_DataReaderInstanceReplacedStatus
	<<eXtension>> <<cert>> DDS_INSTANCE_REPLACED_STATUS.A status structure describing the current instance replacement status for the reader. More...
struct	DDS_SubscriptionMatchedStatus
	<<cert>> DDS_SUBSCRIPTION_MATCHED_STATUSA "match" happens when the DDS_DataReader finds a DDS_DataWriter for the same DDS_Topic with an offered QoS that is compatible with that requested by the DDS_DataReader. More...
struct	DDS_SampleInfo
	Information that accompanies each sample that is read or taken. More...
struct	DDS_SampleInfoSeq
	Declares IDL sequence < DDS_SampleInfo > . More...
struct	DDS_SampleLostStatus
	<<cert>> DDS_SAMPLE_LOST_STATUS More...
struct	DDS_DataReaderQos
	<<cert>> QoS policies supported by a DDS_DataReader entity. More...
struct	DDS_SubscriberQos
	<<cert>> QoS policies supported by a DDS_Subscriber entity. More...
struct	DDS_DataReaderSeq
	Declares IDL sequence < DDS_DataReader > . More...
struct	DDS_DataReaderListener
	<<interface>> <<cert>> DDS_Listener for reader status. More...
struct	DDS_SubscriberListener
	<<interface>> <<cert>> DDS_Listener for status about a subscriber. More...

Macros
#define	DDS_RequestedDeadlineMissedStatus_INITIALIZER
	<<cert>> Initializer for new status instances.
#define	DDS_LivelinessChangedStatus_INITIALIZER
	<<cert>> Initializer for new status instances.
#define	DDS_RequestedIncompatibleQosStatus_INITIALIZER
	<<cert>> Initializer for new status instances.
#define	DDS_SampleRejectedStatus_INITIALIZER
	<<cert>> Initializer for new status instances.
#define	DDS_DataReaderInstanceReplacedStatus_INITIALIZER
	<<cert>> Initializer for new status instances.
#define	DDS_SubscriptionMatchedStatus_INITIALIZER
	<<cert>> Initializer for new status instances.
#define	DDS_SampleLostStatus_INITIALIZER
	<<cert>> Initializer for new status instances.
#define	DDS_DataReaderQos_INITIALIZER
	<<cert>> Initializer for new QoS instances.
#define	DDS_SubscriberQos_INITIALIZER
	<<cert>> Initializer for new QoS instances.
#define	DDS_DataReaderListener_INITIALIZER
	<<cert>> Initializer for new DDS_DataReaderListener.All the new instances allocated in the stack should be initialized to this value.No memory is allocated.
#define	DDS_SubscriberListener_INITIALIZER
	<<eXtension>> <<cert>> Initializer for new DDS_SubscriberListener.All the new instances allocated in the stack should be initialized to this value.No memory is allocated.

Typedefs
typedef struct DDS_DataReaderImpl	DDS_DataReader
	<<interface>> <<cert>> Allows the application to: (1) declare the data it wishes to receive (i.e. make a subscription) and (2) access the data received by the attached DDS_Subscriber.
typedef struct DDS_SubscriberImpl	DDS_Subscriber
	<<interface>> A subscriber is the object responsible for actually receiving data from a subscription.
typedef DDS_UnsignedLong	DDS_SampleStateMask
	A bit-mask (list) of sample states, i.e. DDS_SampleStateKind.
typedef DDS_UnsignedLong	DDS_ViewStateMask
	A bit-mask (list) of view states, i.e. DDS_ViewStateKind.
typedef DDS_UnsignedLong	DDS_InstanceStateMask
	A bit-mask (list) of instance states, i.e. DDS_InstanceStateKind.
typedef void(*	DDS_DataReaderListener_RequestedDeadlineMissedCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_RequestedDeadlineMissedStatus *status)
	<<cert>> Prototype of a DDS_DataReaderListener requested_deadline_missed function.
typedef void(*	DDS_DataReaderListener_LivelinessChangedCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_LivelinessChangedStatus *status)
	<<cert>> Prototype of a DDS_DataReaderListener liveliness_changed function.
typedef void(*	DDS_DataReaderListener_RequestedIncompatibleQosCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_RequestedIncompatibleQosStatus *status)
	<<cert>> Prototype of a DDS_DataReaderListener requested_incompatible_QoS function.
typedef void(*	DDS_DataReaderListener_SampleRejectedCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_SampleRejectedStatus *status)
	<<cert>> Prototype of a DDS_DataReaderListener sample_rejected function.
typedef void(*	DDS_DataReaderListener_DataAvailableCallback )(void *listener_data, DDS_DataReader *reader)
	<<cert>> Prototype of a DDS_DataReaderListener data_available function.
typedef void(*	DDS_DataReaderListener_SubscriptionMatchedCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_SubscriptionMatchedStatus *status)
	<<cert>> Prototype of a DDS_DataReaderListener subscription_match function.
typedef void(*	DDS_DataReaderListener_SampleLostCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_SampleLostStatus *status)
	<<cert>> Prototype of a DDS_DataReaderListener subscription_lost function.
typedef void(*	DDS_DataReaderListener_InstanceReplacedCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_DataReaderInstanceReplacedStatus *status)
	<<cert>> Prototype of a DDS_DataReaderListener instance_replaced function.
typedef DDS_Boolean(*	DDS_DataReaderListener_BeforeSampleDeserializeCallback )(void *listener_data, DDS_DataReader *reader, struct NDDS_Type_Plugin *plugin, struct CDR_Stream_t *stream, DDS_Boolean *dropped)
	<<cert>> Prototype of a DDS_DataReaderListener before_sample_deserialize function.
typedef DDS_Boolean(*	DDS_DataReaderListener_BeforeSampleCommitCallback )(void *listener_data, DDS_DataReader *reader, const void *const sample, DDS_Boolean *dropped)
	<<cert>> Prototype of a DDS_DataReaderListener before_sample_commit function.
typedef void(*	DDS_SubscriberListener_DataOnReadersCallback )(void *listener_data, DDS_Subscriber *sub)
	Prototype of a DDS_SubscriberListener data_on_readers function.

Enumerations
enum	DDS_SampleRejectedStatusKind {   DDS_NOT_REJECTED,   DDS_REJECTED_BY_INSTANCES_LIMIT,   DDS_REJECTED_BY_SAMPLES_LIMIT,   DDS_REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT,   DDS_REJECTED_BY_REMOTE_WRITERS_LIMIT,   DDS_REJECTED_BY_REMOTE_WRITERS_PER_INSTANCE_LIMIT,   DDS_REJECTED_BY_SAMPLES_PER_REMOTE_WRITER_LIMIT }
	Kinds of reasons for rejecting a sample. More...
enum	DDS_SampleStateKind {   DDS_READ_SAMPLE_STATE = 0x0001 << 0,   DDS_NOT_READ_SAMPLE_STATE = 0x0001 << 1 }
	Indicates whether or not a sample has ever been read.For each sample received, the middleware internally maintains a sample_state relative to each DDS_DataReader. The sample state can be either: More...
enum	DDS_ViewStateKind {   DDS_NEW_VIEW_STATE = 0x0001 << 0,   DDS_NOT_NEW_VIEW_STATE = 0x0001 << 1 }
	Indicates whether or not an instance is new.For each instance (identified by the key), the middleware internally maintains a view state relative to each DDS_DataReader. The view state can be either: More...
enum	DDS_InstanceStateKind {   DDS_ALIVE_INSTANCE_STATE = 0x0001 << 0,   DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE = 0x0001 << 1,   DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE = 0x0001 << 2 }
	Indicates is the samples are from a live DDS_DataWriter or not.For each instance, the middleware internally maintains an instance state. The instance state can be: More...
enum	DDS_SampleLostStatusKind {   DDS_SAMPLE_LOST_NOT_LOST,   DDS_SAMPLE_LOST_BY_DATAWRITER,   DDS_SAMPLE_LOST_BY_MAX_SAMPLES_LIMIT,   DDS_SAMPLE_LOST_BY_HISTORY_DEPTH_LIMIT,   DDS_SAMPLE_LOST_BY_META_SAMPLE_LIMIT,   DDS_SAMPLE_LOST_BY_NOT_READ_ON_CACHE_DELETION }
	Kinds of reasons a sample was lost. More...

Functions
DDS_ReturnCode_t	DDS_DataReaderQos_initialize (struct DDS_DataReaderQos *self)
	Initializer for new QoS instances.
DDS_ReturnCode_t	DDS_DataReaderQos_copy (struct DDS_DataReaderQos *self, const struct DDS_DataReaderQos *source)
	Copy the contents of the given QoS into this QoS.DDS_DataReaderQos instances can use dynamic memory because of the sequences contained in some QoS policies. A shallow copy by assignment is therefore unsafe. This method performs a deep-copy, allocating memory if necessary.
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 method 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).
DDS_ReturnCode_t	DDS_SubscriberQos_initialize (struct DDS_SubscriberQos *self)
	<<cert>> Initializer for new QoS instances.
DDS_ReturnCode_t	DDS_SubscriberQos_copy (struct DDS_SubscriberQos *self, const struct DDS_SubscriberQos *source)
	Copy the contents of the given QoS into this QoS.DDS_SubscriberQos instances can use dynamic memory because of the sequences contained in some QoS policies. A shallow copy by assignment is therefore unsafe. This method performs a deep-copy, allocating memory if necessary.
DDS_ReturnCode_t	DDS_SubscriberQos_finalize (struct DDS_SubscriberQos *self)
	Free any dynamic memory allocated by the policies in this DDS_SubscriberQos.Some QoS policies may use dynamic memory (regardless of whether the QoS itself is in dynamic memory). This method 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).
DDS_Entity *	DDS_Subscriber_as_entity (DDS_Subscriber *subscriber)
	<<cert>> Access a DDS_Subscriber's supertype instance.
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.The retreived qos will match the set of values specified on the last successful call to DDS_Subscriber_set_default_datareader_qos, or else, if the call was never made, the default values from is owning DDS_DomainParticipant.
DDS_ReturnCode_t	DDS_Subscriber_set_default_datareader_qos (DDS_Subscriber *self, const struct DDS_DataReaderQos *qos)
	Sets the default DDS_DataReaderQos values for this subscriber.This call causes the default values inherited from the owning DDS_DomainParticipant to be overridden.
DDS_DataReader *	DDS_Subscriber_create_datareader (DDS_Subscriber *self, DDS_TopicDescription *topic, const struct DDS_DataReaderQos *qos, const struct DDS_DataReaderListener *listener, DDS_StatusMask mask)
	<<cert>> Creates a DDS_DataReader that will be attached and belong to the DDS_Subscriber.
DDS_ReturnCode_t	DDS_Subscriber_delete_datareader (DDS_Subscriber *self, DDS_DataReader *a_datareader)
	Deletes a DDS_DataReader that belongs to the DDS_Subscriber.
DDS_ReturnCode_t	DDS_Subscriber_enable (DDS_Entity *self)
	<<cert>> Enables a DDS_Subscriber instance.
DDS_ReturnCode_t	DDS_Subscriber_delete_contained_entities (DDS_Subscriber *self)
	Deletes all the entities that were created by means of the "create" operation on the DDS_Subscriber.Deletes all contained DDS_DataReader objects. This pattern is applied recursively. In this manner, the operation DDS_Subscriber_delete_contained_entities on the DDS_Subscriber will end up deleting all the entities recursively contained in the DDS_Subscriber, that is also the objects belonging to the contained DDS_DataReader.
DDS_DataReader *	DDS_Subscriber_lookup_datareader (DDS_Subscriber *self, const char *topic_name)
	<<cert>> Retrieves an existing DDS_DataReader.Use this operation on the built-in DDS_Subscriber (Discovery) to access the built-in DDS_DataReader entities for the built-in topics.
DDS_DomainParticipant *	DDS_Subscriber_get_participant (DDS_Subscriber *self)
	<<cert>> Returns the DDS_DomainParticipant to which the DDS_Subscriber belongs.
DDS_ReturnCode_t	DDS_Subscriber_set_qos (DDS_Subscriber *self, const struct DDS_SubscriberQos *qos)
	Sets the subscriber QoS.This operation modifies the QoS of the DDS_Subscriber.
DDS_ReturnCode_t	DDS_Subscriber_get_qos (DDS_Subscriber *self, struct DDS_SubscriberQos *qos)
	Gets the subscriber QoS.This method may potentially allocate memory depending on the sequences contained in some QoS policies.
DDS_ReturnCode_t	DDS_Subscriber_set_listener (DDS_Subscriber *self, const struct DDS_SubscriberListener *l, DDS_StatusMask mask)
	Sets the subscriber listener.
struct DDS_SubscriberListener	DDS_Subscriber_get_listener (DDS_Subscriber *self)
	Get the subscriber listener.
DDS_Entity *	DDS_DataReader_as_entity (DDS_DataReader *dataReader)
	<<cert>> Accesses the DDS_DataReader's supertype instance.
DDS_ReturnCode_t	DDS_DataReader_enable (DDS_Entity *self)
	<<cert>> Enables a DDS_DataReader instance.
DDS_TopicDescription *	DDS_DataReader_get_topicdescription (DDS_DataReader *self)
	<<cert>> Returns the DDS_TopicDescription associated with the DDS_DataReader.Returns that same DDS_TopicDescription that was used to create the DDS_DataReader.
DDS_Subscriber *	DDS_DataReader_get_subscriber (DDS_DataReader *self)
	<<cert>> Returns the DDS_Subscriber to which the DDS_DataReader belongs.
DDS_ReturnCode_t	DDS_DataReader_get_sample_rejected_status (DDS_DataReader *self, struct DDS_SampleRejectedStatus *status)
	<<cert>> Accesses the DDS_SAMPLE_REJECTED_STATUS communication status.
DDS_ReturnCode_t	DDS_DataReader_get_liveliness_changed_status (DDS_DataReader *self, struct DDS_LivelinessChangedStatus *status)
	<<cert>> Accesses the DDS_LIVELINESS_CHANGED_STATUS communication status.
DDS_ReturnCode_t	DDS_DataReader_get_requested_deadline_missed_status (DDS_DataReader *self, struct DDS_RequestedDeadlineMissedStatus *status)
	<<cert>> Accesses the DDS_REQUESTED_DEADLINE_MISSED_STATUS communication status.
DDS_ReturnCode_t	DDS_DataReader_get_requested_incompatible_qos_status (DDS_DataReader *self, struct DDS_RequestedIncompatibleQosStatus *status)
	<<cert>> Accesses the DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS communication status.
DDS_ReturnCode_t	DDS_DataReader_get_subscription_matched_status (DDS_DataReader *self, struct DDS_SubscriptionMatchedStatus *status)
	<<cert>> Accesses the DDS_SUBSCRIPTION_MATCHED_STATUS communication status.
DDS_ReturnCode_t	DDS_DataReader_get_sample_lost_status (DDS_DataReader *self, struct DDS_SampleLostStatus *status)
	<<cert>> Accesses the DDS_SAMPLE_LOST_STATUS communication status.
DDS_ReturnCode_t	DDS_DataReader_get_instance_replaced_status (DDS_DataReader *self, struct DDS_DataReaderInstanceReplacedStatus *status)
	<<cert>> Accesses the DDS_INSTANCE_REPLACED_STATUS communication status.
DDS_ReturnCode_t	DDS_DataReader_set_qos (DDS_DataReader *self, const struct DDS_DataReaderQos *qos)
	Sets the reader QoS.This operation modifies the QoS of the DDS_DataReader.
DDS_ReturnCode_t	DDS_DataReader_get_qos (DDS_DataReader *self, struct DDS_DataReaderQos *qos)
	Gets the reader QoS.This method may potentially allocate memory depending on the sequences contained in some QoS policies.
DDS_ReturnCode_t	DDS_DataReader_set_listener (DDS_DataReader *self, const struct DDS_DataReaderListener *l, DDS_StatusMask mask)
	Sets the reader listener.
struct DDS_DataReaderListener	DDS_DataReader_get_listener (DDS_DataReader *self)
	Get the reader listener.
DDS_ReturnCode_t	DDS_DataReader_read (DDS_DataReader *self, struct DDS_UntypedSampleSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_samples, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
	<<cert>> Access a collection of data samples from the DDS_DataReader.
DDS_ReturnCode_t	DDS_DataReader_take (DDS_DataReader *self, struct DDS_UntypedSampleSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_samples, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
	<<cert>> Access a collection of data-samples from the DDS_DataReader.
DDS_ReturnCode_t	DDS_DataReader_read_next_sample (DDS_DataReader *self, void *received_data, struct DDS_SampleInfo *sample_info)
	<<cert>> Copies the next not-previously-accessed data value from the DDS_DataReader.
DDS_ReturnCode_t	DDS_DataReader_take_next_sample (DDS_DataReader *self, void *received_data, struct DDS_SampleInfo *sample_info)
	<<cert>> Copies the next not-previously-accessed data value from the DDS_DataReader.
DDS_ReturnCode_t	DDS_DataReader_read_instance (DDS_DataReader *self, struct DDS_UntypedSampleSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_samples, const DDS_InstanceHandle_t *a_handle, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
	<<cert>> Access a collection of data samples from the DDS_DataReader, all of which belong to the same instance .
DDS_ReturnCode_t	DDS_DataReader_take_instance (DDS_DataReader *self, struct DDS_UntypedSampleSeq *received_data, struct DDS_SampleInfoSeq *info_seq, DDS_Long max_samples, const DDS_InstanceHandle_t *a_handle, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
	<<cert>> Access a collection of data samples from the DDS_DataReader, all of which belong to the same instance .
DDS_ReturnCode_t	DDS_DataReader_return_loan (DDS_DataReader *self, struct DDS_UntypedSampleSeq *received_data, struct DDS_SampleInfoSeq *info_seq)
	<<cert>> Indicates to the DDS_DataReader that the application is done accessing the collection of received_data and info_seq obtained by some earlier invocation of read or take on the DDS_DataReader.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.
DDS_InstanceHandle_t	DDS_DataReader_lookup_instance (DDS_DataReader *self, const void *key_holder)
	Retrieve the DDS_InstanceHandle_t identifying a specific instance.

Variables
const DDS_SampleStateMask	DDS_ANY_SAMPLE_STATE
	Any sample state DDS_READ_SAMPLE_STATE | DDS_NOT_READ_SAMPLE_STATE.
const DDS_ViewStateMask	DDS_ANY_VIEW_STATE
	Any view state DDS_NEW_VIEW_STATE | DDS_NOT_NEW_VIEW_STATE.
const DDS_InstanceStateMask	DDS_ANY_INSTANCE_STATE
	Any instance state ALIVE_INSTANCE_STATE | NOT_ALIVE_DISPOSED_INSTANCE_STATE | NOT_ALIVE_NO_WRITERS_INSTANCE_STATE.
const DDS_InstanceStateMask	DDS_NOT_ALIVE_INSTANCE_STATE
	Not alive instance state NOT_ALIVE_DISPOSED_INSTANCE_STATE | NOT_ALIVE_NO_WRITERS_INSTANCE_STATE.
struct DDS_DataReaderQos	DDS_DATAREADER_QOS_DEFAULT
	<<cert>> Special value for creating data reader with default QoS.When used in DDS_Subscriber_create_datareader, this special value is used to indicate that the DDS_DataReader should be created with the default DDS_DataReader QoS.
struct DDS_DataReaderQos	DDS_DATAREADER_QOS_USE_TOPIC_QOS
	Special value for creating DDS_DataReader with a combination of the default DDS_DataReaderQos and the DDS_TopicQos.The use of this value is equivalent to the application obtaining the default DDS_DataReaderQos and the DDS_TopicQos (by means of the operation DDS_Topic_get_qos) and then combining these two QoS so that any policy that is set on the DDS_TopicQos "overrides" the corresponding policy on the default QoS. The resulting QoS is then applied to the creation of the DDS_DataReader.

---

Detailed Description

DDS subscription module.