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

#include <dds_cpp_subscription.hxx>

Inheritance diagram for DDSSubscriber:

Public Member Functions
virtual DDSDataReader *	create_datareader (DDSTopicDescription topic, const DDS_DataReaderQos &qos, DDSDataReaderListener listener, DDS_StatusMask mask)=0
	<<cert>> Creates a DDSDataReader that will be attached and belong to the DDSSubscriber.
virtual DDS_ReturnCode_t	delete_datareader (DDSDataReader *a_datareader)=0
	Deletes a DDSDataReader that belongs to the DDSSubscriber.
virtual DDS_ReturnCode_t	get_default_datareader_qos (DDS_DataReaderQos &qos)=0
	Copies the default DDS_DataReaderQos values into the provided DDS_DataReaderQos instance.
virtual DDS_ReturnCode_t	set_default_datareader_qos (const DDS_DataReaderQos &qos)=0
	Sets the default DDS_DataReaderQos values for this subscriber.
virtual DDS_ReturnCode_t	delete_contained_entities ()=0
	Deletes all the entities that were created by means of the "create" operation on the DDSSubscriber.
virtual DDSDataReader *	lookup_datareader (const char *topic_name)=0
	<<cert>> Retrieves an existing DDSDataReader.
virtual DDSDataReader *	lookup_datareader_by_name (const char *reader_name)=0
	<<cert>> Retrieves a DDSDataReader by its entity name within this DDSSubscriber
virtual DDSDomainParticipant *	get_participant ()=0
	<<cert>> Returns the DDSDomainParticipant to which the DDSSubscriber belongs.
virtual DDS_ReturnCode_t	set_qos (const DDS_SubscriberQos &qos)=0
	Sets the subscriber QoS.
virtual DDS_ReturnCode_t	get_qos (DDS_SubscriberQos &qos)=0
	Gets the subscriber QoS.
virtual DDS_ReturnCode_t	set_listener (const DDSSubscriberListener *listener, DDS_StatusMask mask)=0
	Sets the subscriber listener.
virtual DDSSubscriberListener *	get_listener ()=0
	Get the subscriber listener.
Public Member Functions inherited from DDSEntity
DDS_ReturnCode_t	enable ()
	<<cert>> Enables the DDSEntity.
DDSStatusCondition *	get_statuscondition ()
	<<cert>> Return the DDSStatusCondition associated with a particular DDSEntity.
DDS_StatusMask	get_status_changes ()
	<<cert>> Retrieves the list of communication statuses in the DDSEntity that are triggered.
DDS_InstanceHandle_t	get_instance_handle ()
	<<cert>> Allows access to the DDS_InstanceHandle_t associated with the DDSEntity.

Detailed Description

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

QoS:: DDS_SubscriberQos

Status:: DDS_DATA_ON_READERS_STATUS

Listener:: DDSSubscriberListener

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

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

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

The base-class operations DDSEntity::enable
DDSSubscriber::create_datareader, DDSSubscriber::delete_datareader, DDSSubscriber::delete_contained_entities.

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

Member Function Documentation

virtual DDSDataReader* DDSSubscriber::create_datareader	(	DDSTopicDescription *	topic,
		const DDS_DataReaderQos &	qos,
		DDSDataReaderListener *	listener,
		DDS_StatusMask	mask
	)

pure virtual

<<cert>> Creates a DDSDataReader that will be attached and belong to the DDSSubscriber.

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

Parameters:

topic	<<in>> The DDSTopicDescription that the DDSDataReader will be associated with. Cannot be NULL.
qos	<<in>> The qos of the DDSDataReader. The special value DDS_DATAREADER_QOS_DEFAULT can be used to indicate that the DDSDataReader should be created with the default DDS_DataReaderQos set in the DDSSubscriber. If DDSTopicDescription is of type DDSTopic, the special value DDS_DATAREADER_QOS_USE_TOPIC_QOS can be used to indicate that the DDSDataReader should be created with the combination of the default DDS_DataReaderQos set on the DDSSubscriber and the DDS_TopicQos.
listener	<<in>> The listener of the DDSDataReader.
mask	<<in>>. Changes of communication status to be invoked on the listener.

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

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

virtual DDS_ReturnCode_t DDSSubscriber::delete_datareader ( DDSDataReader * a_datareader )

pure virtual

Deletes a DDSDataReader that belongs to the DDSSubscriber.

Precondition:: If the DDSDataReader does not belong to the DDSSubscriber, or if ther are any existing objects that are attached to the DDSDataReader, or if there are outstanding loans on samples (as a result of a call to read(), take(), or one of the variants thereof), the operation fails with the error DDS_RETCODE_PRECONDITION_NOT_MET.

Postcondition:: Listener installed on the DDSDataReader will not be called after this method completes successfully.

Parameters:

a_datareader <<in>> The DDSDataReader to be deleted.

Returns:: One of the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET.

virtual DDS_ReturnCode_t DDSSubscriber::get_default_datareader_qos ( DDS_DataReaderQos & qos )

pure virtual

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 DDSSubscriber::set_default_datareader_qos, or else, if the call was never made, the default values from is owning DDSDomainParticipant.

This method 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 DDSSubscriber::get_default_datareader_qos or calling DDSSubscriber::create_datareader with DDS_DATAREADER_QOS_DEFAULT as the qos parameter.

Parameters:

qos	<<inout>> DDS_DataReaderQos to be filled-up.

Returns:: One of the Standard Return Codes

See also:: DDS_DATAREADER_QOS_DEFAULT; DDSSubscriber::create_datareader

virtual DDS_ReturnCode_t DDSSubscriber::set_default_datareader_qos ( const DDS_DataReaderQos & qos )

pure virtual

Sets the default DDS_DataReaderQos values for this subscriber.

This call causes the default values inherited from the owning DDSDomainParticipant to be overridden.

This default value will be used for newly created DDSDataReader if DDS_DATAREADER_QOS_DEFAULT is specified as the qos parameter when DDSSubscriber::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 DDSSubscriber::get_default_datareader_qos or calling DDSSubscriber::create_datareader with DDS_DATAREADER_QOS_DEFAULT as the qos parameter.

Parameters:

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 DDSSubscriber::set_default_datareader_qos had never been called.

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

virtual DDS_ReturnCode_t DDSSubscriber::delete_contained_entities ( )

pure virtual

Deletes all the entities that were created by means of the "create" operation on the DDSSubscriber.

Deletes all contained DDSDataReader objects. This pattern is applied recursively. In this manner, the operation DDSSubscriber::delete_contained_entities on the DDSSubscriber will end up deleting all the entities recursively contained in the DDSSubscriber, that is also the objects belonging to the contained DDSDataReader.

The operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET if any of the contained entities is in a state where it cannot be deleted. This will occur, for example, if a contained DDSDataReader cannot be deleted because the application has called a DDSDataReader::read_untyped or DDSDataReader::take_untyped operation and has not called the corresponding DDSDataReader::return_loan_untyped operation to return the loaned samples.

Once DDSSubscriber::delete_contained_entities completes successfully, the application may delete the DDSSubscriber, knowing that it has no contained DDSDataReader objects.

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

virtual DDSDataReader* DDSSubscriber::lookup_datareader ( const char * topic_name )

pure virtual

<<cert>> Retrieves an existing DDSDataReader.

Use this operation on the built-in DDSSubscriber (Discovery) to access the built-in DDSDataReader entities for the built-in topics.

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

To ensure that builtin DDSDataReader entities receive all the discovery traffic, it is suggested that you lookup the builtin DDSDataReader before the DDSDomainParticipant is enabled. Looking up builtin DDSDataReader may implicitly register builtin transports due to creation of DDSDataReader. 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 DDSDomainParticipant.
(optional) Modify builtin transport properties
Call DDS_DomainParticipant_get_builtin_subscriber().
Call lookup_datareader().
Call enable() on the DomainParticipant.

Parameters:

topic_name <<in>> Name of the DDSTopicDescription that the retrieved DDSDataReader is attached to. Cannot be NULL.

Returns:: A DDSDataReader that belongs to the DDSSubscriber attached to the DDSTopicDescription with topic_name. If no such DDSDataReader exists, this operation returns NULL.

The returned DDSDataReader may be enabled or disabled.

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

MT Safety:: UNSAFE. It is not safe to lookup a DDSDataReader in one thread while another thread is simultaneously creating or destroying that DDSDataReader.

virtual DDSDataReader* DDSSubscriber::lookup_datareader_by_name ( const char * reader_name )

pure virtual

<<cert>> Retrieves a DDSDataReader by its entity name within this DDSSubscriber

This returned DDSDataReader is either enabled or disabled.

Every DDSDataReader in the system has an entity name which is configured and stored in the EntityName policy, ENTITY_NAME.

This operation retrieves a DDSDataReader within the DDSSubscriber given the entity's name. If there are several DDSDataReader with the same name within the DDSSubscriber, this function returns the first matching occurrence.

Parameters:

reader_name <<in>> Entity name of the DDSDataReader. Cannot be NULL.

Returns:: The first DDSDataReader found with the specified name or NULL if it is not found.

MT Safety:: UNSAFE. It is not safe to lookup a DDSDataReader in one thread while another thread is simultaneously creating or destroying that DDSDataReader.

virtual DDSDomainParticipant* DDSSubscriber::get_participant ( )

pure virtual

<<cert>> Returns the DDSDomainParticipant to which the DDSSubscriber belongs.

Returns:: the DDSDomainParticipant to which the DDSSubscriber belongs.

virtual DDS_ReturnCode_t DDSSubscriber::set_qos ( const DDS_SubscriberQos & qos )

pure virtual

Sets the subscriber QoS.

This operation modifies the QoS of the DDSSubscriber.

The DDS_SubscriberQos::entity_factory can be changed. The other policies are immutable.

Parameters:

qos <<in>> DDS_SubscriberQos to be set to. Policies must be consistent. Policies cannot be changed after DDSSubscriber is enabled. The special value DDS_SUBSCRIBER_QOS_DEFAULT can be used to indicate that the QoS of the DDSSubscriber should be changed to match the current default DDS_SubscriberQos set in the DDSDomainParticipant.

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

See also:: DDS_SubscriberQos for rules on consistency among QoS; set_qos (abstract)

virtual DDS_ReturnCode_t DDSSubscriber::get_qos ( DDS_SubscriberQos & qos )

pure virtual

Gets the subscriber QoS.

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

Parameters:

qos	<<in>> DDS_SubscriberQos to be filled in.

Returns:: One of the Standard Return Codes

See also:: get_qos (abstract)

virtual DDS_ReturnCode_t DDSSubscriber::set_listener	(	const DDSSubscriberListener *	listener,
		DDS_StatusMask	mask
	)

pure virtual

Sets the subscriber listener.

Parameters:

listener	<<in>> DDSSubscriberListener to set to.
mask	<<in>> DDS_StatusMask associated with the DDSSubscriberListener.

Returns:: One of the Standard Return Codes

See also:: set_listener (abstract)

virtual DDSSubscriberListener* DDSSubscriber::get_listener ( )

pure virtual

Get the subscriber listener.

Returns:: DDSSubscriberListener of the DDSSubscriber.

Public Member Functions

Detailed Description

Member Function Documentation