DDS_Subscriber entity and associated elements More...

Data Structures
struct	DDS_SubscriberQos
	<<cert>> QoS policies supported by a DDS_Subscriber entity. More...
struct	DDS_SubscriberListener
	<<interface>> <<cert>> DDS_Listener for status about a subscriber. More...

Macros
#define	DDS_SubscriberQos_INITIALIZER
	<<cert>> Initializer for new QoS instances.
#define	DDS_SubscriberListener_INITIALIZER
	<<eXtension>> <<cert>> Initializer for new DDS_SubscriberListener.

Typedefs
typedef struct DDS_SubscriberImpl	DDS_Subscriber
	<<interface>> A subscriber is the object responsible for actually receiving data from a subscription.
typedef void(*	DDS_SubscriberListener_DataOnReadersCallback )(void listener_data, DDS_Subscriber sub)
	Prototype of a DDS_SubscriberListener data_on_readers function.

Functions
DDS_ReturnCode_t	DDS_SubscriberQos_initialize (struct DDS_SubscriberQos *self)
	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_Boolean	DDS_SubscriberQos_is_equal (const struct DDS_SubscriberQos left, const struct DDS_SubscriberQos right)
	Compare two DDS_SubscriberQos policies for equality.
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.
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.
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_DataReader *	DDS_Subscriber_lookup_datareader (DDS_Subscriber self, const char topic_name)
	<<cert>> Retrieves an existing DDS_DataReader.
DDS_DomainParticipant *	DDS_Subscriber_get_participant (DDS_Subscriber *self)
	<<cert>> Returns the DDS_DomainParticipant to which the DDS_Subscriber belongs.

Variables
struct DDS_DataReaderQos	DDS_DATAREADER_QOS_DEFAULT
	<<cert>> Special value for creating data reader with default QoS.

Detailed Description

DDS_Subscriber entity and associated elements

Macro Definition Documentation

#define DDS_SubscriberQos_INITIALIZER

<<cert>> Initializer for new QoS instances.

New DDS_SubscriberQos instances stored on 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. This does not allocate memory.

The simplest way to create a new QoS structure is to initialize it on the stack at the time of its creation:

DDS_SubscriberQos myQos = DDS_SubscriberQos_INITIALIZER;

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

Typedef Documentation

typedef struct DDS_SubscriberImpl DDS_Subscriber

<<interface>> A subscriber is the object responsible for actually receiving data from a subscription.

QoS:: DDS_SubscriberQos

Status:: DDS_DATA_ON_READERS_STATUS

Listener:: DDS_SubscriberListener

A subscriber acts on the behalf of one or several DDS_DataReader objects that are related to it. When it receives data (from the other parts of the system), it builds the list of concerned DDS_DataReader objects and then indicates to the application that data is available through its listener.

The application can access the list of concerned DDS_DataReader objects through the operation get_datareaders() and then access the data available through operations on the DDS_DataReader.

The following operations may be called even if the DDS_Subscriber is not enabled. Other operations will the value DDS_RETCODE_NOT_ENABLED if called on a disabled DDS_Subscriber:

The base-class operations DDS_Entity_enable
DDS_Subscriber_create_datareader

All operations except for the base-class operations enable() and create_datareader() may fail with DDS_RETCODE_NOT_ENABLED.

typedef void(* DDS_SubscriberListener_DataOnReadersCallback)(void *listener_data, DDS_Subscriber *sub)

Prototype of a DDS_SubscriberListener data_on_readers function.

Function Documentation

DDS_ReturnCode_t DDS_SubscriberQos_initialize ( struct DDS_SubscriberQos * self )

Initializer for new QoS instances.

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

Parameters:

self	<<in>> Cannot be NULL.

Returns:: One of the Standard Return Codes

MT Safety:: This operation is thread safe. However, note that the arguments are not protected from being modified by other threads and must not be modified until the call returns.

See also:: DDS_SubscriberQos_INITIALIZER

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 function performs a deep-copy, allocating memory if necessary.

Parameters:

self	<<in>> Cannot be NULL.
source	<<in>> The DDS_PublisherQos to copy from.

Returns:: One of the Standard Return Codes

MT Safety:: UNSAFE. This operation is not thread safe. This operation does not protect the source or destination from being modified by another thread while the source is being copied to the destination.

API Restriction:: This function must only be called after DDS_DomainParticipantFactory_get_instance.

DDS_Boolean DDS_SubscriberQos_is_equal	(	const struct DDS_SubscriberQos *	left,
		const struct DDS_SubscriberQos *	right
	)

Compare two DDS_SubscriberQos policies for equality.

Parameters:

[in]	left	The left side of the comparison.
[in]	right	The right side of the comparison.

Returns:: DDS_BOOLEAN_TRUE if left is equal to right, otherwise DDS_BOOLEAN_FALSE.

MT Safety:: UNSAFE. This operation does not protect against the left or right side from being modified by another thread while the comparison is made.

See also:: DDS_SubscriberQos_INITIALIZER; DDS_SubscriberQos_initialize

DDS_Entity* DDS_Subscriber_as_entity ( DDS_Subscriber * subscriber )

<<cert>> Access a DDS_Subscriber's supertype instance.

Parameters:

subscriber <<in>> Cannot be NULL.

Returns:: The DDS_Entity that is supertype instance of the subscriber.

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.

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

MT Safety:: UNSAFE. It is not safe to retrieve the default QoS value from a subscriber while another thread may be simultaneously calling DDS_Subscriber_get_default_datareader_qos or calling DDS_Subscriber_create_datareader with DDS_DATAREADER_QOS_DEFAULT as the qos parameter.

Parameters:

self	<<in>> Cannot be NULL.
qos	<<inout>> DDS_DataReaderQos to be filled-up. Cannot be NULL.

Returns:: One of the Standard Return Codes

See also:: DDS_DATAREADER_QOS_DEFAULT; DDS_Subscriber_create_datareader

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.

This default value will be used for newly created DDS_DataReader if DDS_DATAREADER_QOS_DEFAULT is specified as the qos parameter when DDS_Subscriber_create_datareader is called.

Precondition:: The specified QoS policies must be consistent, or else the operation will have no effect and fail with DDS_RETCODE_INCONSISTENT_POLICY

MT Safety:: UNSAFE. It is not safe to retrieve the default QoS value from a subscriber while another thread may be simultaneously calling DDS_Subscriber_get_default_datareader_qos or calling DDS_Subscriber_create_datareader with DDS_DATAREADER_QOS_DEFAULT as the qos parameter.

Parameters:

self	<<in>> Cannot be NULL.
qos	<<in>> The default DDS_DataReaderQos to be set to. The special value DDS_DATAREADER_QOS_DEFAULT may be passed as `qos` to indicate that the default QoS should be reset back to the initial values the factory would have used if DDS_Subscriber_set_default_datareader_qos had never been called. Cannot be NULL.

Returns:: One of the Standard Return Codes, or or DDS_RETCODE_INCONSISTENT_POLICY

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.

Precondition:: If subscriber is enabled, the topic must be enabled. If it is not, this operation will fail and no DDS_DataReader will be created.; The given DDS_TopicDescription must have been created from the same participant as this subscriber. If it was created from a different participant, this function will return NULL.

Parameters:

self	<<in>> Cannot be NULL.
topic	<<in>> The DDS_TopicDescription that the DDS_DataReader will be associated with. Cannot be NULL.
qos	<<in>> The qos of the DDS_DataReader. The special value DDS_DATAREADER_QOS_DEFAULT can be used to indicate that the DDS_DataReader should be created with the default DDS_DataReaderQos set in the DDS_Subscriber. Cannot be NULL.
listener	<<in>> The listener of the DDS_DataReader.
mask	<<in>>. Changes of communication status to be invoked on the listener.

Returns:: A DDS_DataReader of a derived class specific to the data-type associated with the DDS_Topic or NULL if an error occurred.

MT Safety:: This operation is thread safe. However, note that the arguments are not protected from being modified by other threads and must not be modified until the call returns.

See also:: Specifying QoS on entities for information on setting QoS before entity creation; DDS_DataReaderQos for rules on consistency among QoS

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.

The built-in DDS_DataReader is created when this operation is called on a built-in topic for the first time. The built-in DDS_DataReader is deleted automatically when the DDS_DomainParticipant is deleted.

To ensure that builtin DDS_DataReader entities receive all the discovery traffic, it is suggested that you lookup the builtin DDS_DataReader before the DDS_DomainParticipant is enabled. Looking up builtin DDS_DataReader may implicitly register builtin transports due to creation of DDS_DataReader. Therefore, if you are want to modify builtin transport properties, do so before using this operation.

Therefore the suggested sequence when looking up builtin DataReaders is:

Create a disabled DDS_DomainParticipant.
(optional) Modify builtin transport properties
Call DDS_DomainParticipant_get_builtin_subscriber().
Call lookup_datareader().
Call enable() on the DomainParticipant.

Parameters:

self	<<in>> Cannot be NULL.
topic_name	<<in>> Name of the DDS_TopicDescription that the retrieved DDS_DataReader is attached to. Cannot be NULL.

Returns:: A DDS_DataReader that belongs to the DDS_Subscriber attached to the DDS_TopicDescription with topic_name. If no such DDS_DataReader exists, this operation returns NULL.

The returned DDS_DataReader may be enabled or disabled.

If more than one DDS_DataReader is attached to the DDS_Subscriber, this operation may return any one of them.

MT Safety:: This operation is thread safe. However, note that the arguments are not protected from being modified by other threads and must not be modified until the call returns.

DDS_DomainParticipant* DDS_Subscriber_get_participant ( DDS_Subscriber * self )

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

Parameters:

self	<<in>> Cannot be NULL.

Returns:: the DDS_DomainParticipant to which the DDS_Subscriber belongs.

MT Safety:: This operation is thread safe.

Variable Documentation

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.

See also:: DDS_Subscriber_create_datareader

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation

Variable Documentation