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

Inheritance diagram for DDSSubscriber:

Public Member Functions
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	set_default_datareader_qos_with_profile (const char library_name, const char profile_name)=0
	<<extension>> Set the default DDS_DataReaderQos values for this subscriber based on the input XML QoS profile.

virtual DDS_ReturnCode_t	set_default_library (const char *library_name)=0
	<<extension>> Sets the default XML library for a DDSSubscriber.

virtual const char *	get_default_library ()=0
	<<extension>> Gets the default XML library associated with a DDSSubscriber.

virtual DDS_ReturnCode_t	set_default_profile (const char library_name, const char profile_name)=0
	<<extension>> Sets the default XML profile for a DDSSubscriber.

virtual const char *	get_default_profile ()=0
	<<extension>> Gets the default XML profile associated with a DDSSubscriber.

virtual const char *	get_default_profile_library ()=0
	<<extension>> Gets the library where the default XML QoS profile is contained for a DDSSubscriber.

virtual DDSDataReader *	create_datareader (DDSTopicDescription topic, const DDS_DataReaderQos &qos, DDSDataReaderListener listener, DDS_StatusMask mask)=0
	Creates a DDSDataReader that will be attached and belong to the DDSSubscriber.

virtual DDSDataReader *	create_datareader_with_profile (DDSTopicDescription topic, const char library_name, const char profile_name, DDSDataReaderListener listener, DDS_StatusMask mask)=0
	<<extension>> Creates a DDSDataReader object using the DDS_DataReaderQos associated with the input XML QoS profile.

virtual DDS_ReturnCode_t	delete_datareader (DDSDataReader *a_datareader)=0
	Deletes a DDSDataReader that belongs to the DDSSubscriber.

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
	Retrieves an existing DDSDataReader.

virtual DDS_ReturnCode_t	begin_access ()=0
	Indicates that the application is about to access the data samples in any of the DDSDataReader objects attached to the DDSSubscriber.

virtual DDS_ReturnCode_t	end_access ()=0
	Indicates that the application has finished accessing the data samples in DDSDataReader objects managed by the DDSSubscriber.

virtual DDS_ReturnCode_t	get_datareaders (DDSDataReaderSeq &readers, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)=0
	Allows the application to access the DDSDataReader objects that contain samples with the specified `sample_states`, `view_states` and `instance_states`.

virtual DDS_ReturnCode_t	get_all_datareaders (DDSDataReaderSeq &readers)=0
	Retrieve all the DataReaders created from this Subscriber.

virtual DDS_ReturnCode_t	notify_datareaders ()=0
	Invokes the operation DDSDataReaderListener::on_data_available() on the DDSDataReaderListener objects attached to contained DDSDataReader entities with DDS_DATA_AVAILABLE_STATUS that is considered changed as described in Changes in read communication status.

virtual DDSDomainParticipant *	get_participant ()=0
	Returns the DDSDomainParticipant to which the DDSSubscriber belongs.

virtual DDS_ReturnCode_t	copy_from_topic_qos (DDS_DataReaderQos &datareader_qos, const DDS_TopicQos &topic_qos)=0
	Copies the policies in the DDS_TopicQos to the corresponding policies in the DDS_DataReaderQos.

virtual DDS_ReturnCode_t	set_qos (const DDS_SubscriberQos &qos)=0
	Sets the subscriber QoS.

virtual DDS_ReturnCode_t	set_qos_with_profile (const char library_name, const char profile_name)=0
	<<extension>> Change the QoS of this subscriber using the input XML QoS profile.

virtual DDS_ReturnCode_t	get_qos (DDS_SubscriberQos &qos)=0
	Gets the subscriber QoS.

virtual DDS_ReturnCode_t	set_listener (DDSSubscriberListener *l, DDS_StatusMask mask=DDS_STATUS_MASK_ALL)=0
	Sets the subscriber listener.

virtual DDSSubscriberListener *	get_listener ()=0
	Get the subscriber listener.

virtual DDSDataReader *	lookup_datareader_by_name (const char *datareader_name)=0
	<<extension>> Retrieves a DDSDataReader contained within the DDSSubscriber the DDSDataReader entity name.

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 or by enabling related conditions.

The application can access the list of concerned DDSDataReader objects through the operation DDSSubscriber::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:

All operations except for DDSSubscriber::set_qos, DDSSubscriber::set_qos_with_profile,DDSSubscriber::get_qos, DDSSubscriber::set_listener, DDSSubscriber::get_listener, DDSEntity::enable and DDSSubscriber::create_datareader may fail with DDS_RETCODE_NOT_ENABLED.

See Also: Operations Allowed in Listener Callbacks

Examples:: HelloWorld_subscriber.cxx.

Member Function Documentation

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 retrieved qos will match the set of values specified on the last successful call to DDSSubscriber::set_default_datareader_qos, or DDSSubscriber::set_default_datareader_qos_with_profile, 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::set_default_datareader_qos

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 set the default QoS value from a subscriber while another thread may be simultaneously calling DDSSubscriber::set_default_datareader_qos, 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 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::set_default_datareader_qos_with_profile	(	const char *	library_name,
		const char *	profile_name
	)

pure virtual

<<extension>> Set the default DDS_DataReaderQos values for this subscriber based on the input XML QoS profile.

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 DDS_DataReaderQos contained in the specified XML QoS profile 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 set the default QoS value from a DDSSubscriber while another thread may be simultaneously calling DDSSubscriber::set_default_datareader_qos, DDSSubscriber::get_default_datareader_qos or calling DDSSubscriber::create_datareader with DDS_DATAREADER_QOS_DEFAULT as the qos parameter.

Parameters

library_name	<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSSubscriber::set_default_library).
profile_name	<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSSubscriber::set_default_profile).

If the input profile cannot be found the method fails with DDS_RETCODE_ERROR.

Returns: One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY

See Also: DDS_DATAREADER_QOS_DEFAULT; DDSSubscriber::create_datareader_with_profile

virtual DDS_ReturnCode_t DDSSubscriber::set_default_library ( const char * library_name )

pure virtual

<<extension>> Sets the default XML library for a DDSSubscriber.

This method specifies the library that will be used as the default the next time a default library is needed during a call to one of this Subscriber's operations.

Any API requiring a library_name as a parameter can use null to refer to the default library.

If the default library is not set, the DDSSubscriber inherits the default from the DDSDomainParticipant (see DDSDomainParticipant::set_default_library).

Parameters

library_name <<in>> Library name. If library_name is null any previous default is unset.

Returns: One of the Standard Return Codes

See Also: DDSSubscriber::get_default_library

virtual const char* DDSSubscriber::get_default_library ( )

pure virtual

<<extension>> Gets the default XML library associated with a DDSSubscriber.

Returns: The default library or null if the default library was not set.

See Also: DDSSubscriber::set_default_library

virtual DDS_ReturnCode_t DDSSubscriber::set_default_profile	(	const char *	library_name,
		const char *	profile_name
	)

pure virtual

<<extension>> Sets the default XML profile for a DDSSubscriber.

This method specifies the profile that will be used as the default the next time a default Subscriber profile is needed during a call to one of this Subscriber's operations. When calling a DDSSubscriber method that requires a profile_name parameter, you can use NULL to refer to the default profile. (This same information applies to setting a default library.)

If the default profile is not set, the DDSSubscriber inherits the default from the DDSDomainParticipant (see DDSDomainParticipant::set_default_profile).

This method does not set the default QoS for DDSDataReader objects created by this DDSSubscriber; for this functionality, use DDSSubscriber::set_default_datareader_qos_with_profile (you may pass in NULL after having called set_default_profile()).

This method does not set the default QoS for newly created Subscribers; for this functionality, use DDSDomainParticipant::set_default_subscriber_qos_with_profile.

Parameters

library_name	<<in>> The library name containing the profile.
profile_name	<<in>> The profile name. If profile_name is null any previous default is unset.

Returns: One of the Standard Return Codes

See Also: DDSSubscriber::get_default_profile; DDSSubscriber::get_default_profile_library

virtual const char* DDSSubscriber::get_default_profile ( )

pure virtual

<<extension>> Gets the default XML profile associated with a DDSSubscriber.

Returns: The default profile or null if the default profile was not set.

See Also: DDSSubscriber::set_default_profile

virtual const char* DDSSubscriber::get_default_profile_library ( )

pure virtual

<<extension>> Gets the library where the default XML QoS profile is contained for a DDSSubscriber.

The default profile library is automatically set when DDSSubscriber::set_default_profile is called.

This library can be different than the DDSSubscriber default library (see DDSSubscriber::get_default_library).

Returns: The default profile library or null if the default profile was not set.

See Also: DDSSubscriber::set_default_profile

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

pure virtual

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

For each application-defined type Foo, there is an implied, auto-generated class FooDataReader (an incarnation of FooDataReader) that extends DDSDataReader and contains the operations to read data of type Foo.

Note that a common application pattern to construct the QoS for the DDSDataReader is to:

Retrieve the QoS policies on the associated DDSTopic by means of the DDSTopic::get_qos operation.
Retrieve the default DDSDataReader qos by means of the DDSSubscriber::get_default_datareader_qos operation.
Combine those two QoS policies (for example, using DDSSubscriber::copy_from_topic_qos) and selectively modify policies as desired
Use the resulting QoS policies to construct the DDSDataReader.

When a DDSDataReader is created, only those transports already registered are available to the DDSDataReader. See Built-in Transport Plugins for details on when a builtin transport is registered.

MT Safety:: UNSAFE. If DDS_DATAREADER_QOS_DEFAULT is used for the qos parameter, it is not safe to create the datareader while another thread may be simultaneously calling DDSSubscriber::set_default_datareader_qos.

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.; If qos is DDS_DATAREADER_QOS_USE_TOPIC_QOS, topic cannot be DDSMultiTopic, or else 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 or DDSContentFilteredTopic, 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 (in the case of a DDSContentFilteredTopic, the DDS_TopicQos of the related DDSTopic). if DDS_DATAREADER_QOS_USE_TOPIC_QOS is used, `topic` cannot be a DDSMultiTopic.
listener	<<in>> The listener of the DDSDataReader.
mask	<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.

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

See Also: FooDataReader; Specifying QoS on entities for information on setting QoS before entity creation; DDS_DataReaderQos for rules on consistency among QoS; DDSSubscriber::create_datareader_with_profile; DDSSubscriber::get_default_datareader_qos; DDSTopic::set_qos; DDSSubscriber::copy_from_topic_qos; DDSDataReader::set_listener

Examples:: HelloWorld_subscriber.cxx.

virtual DDSDataReader* DDSSubscriber::create_datareader_with_profile	(	DDSTopicDescription *	topic,
		const char *	library_name,
		const char *	profile_name,
		DDSDataReaderListener *	listener,
		DDS_StatusMask	mask
	)

pure virtual

<<extension>> Creates a DDSDataReader object using the DDS_DataReaderQos associated with the input XML QoS profile.

The DDSDataReader will be attached and belong to the DDSSubscriber.

For each application-defined type Foo, there is an implied, auto-generated class FooDataReader (an incarnation of FooDataReader) that extends DDSDataReader and contains the operations to read data of type Foo.

When a DDSDataReader is created, only those transports already registered are available to the DDSDataReader. See Built-in Transport Plugins for details on when a builtin transport is registered.

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.
library_name	<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSSubscriber::set_default_library).
profile_name	<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSSubscriber::set_default_profile).
listener	<<in>> The listener of the DDSDataReader.
mask	<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.

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

See Also: FooDataReader; Specifying QoS on entities for information on setting QoS before entity creation; DDS_DataReaderQos for rules on consistency among QoS; DDS_DATAREADER_QOS_DEFAULT; DDS_DATAREADER_QOS_USE_TOPIC_QOS; DDSSubscriber::create_datareader; DDSSubscriber::get_default_datareader_qos; DDSTopic::set_qos; DDSSubscriber::copy_from_topic_qos; DDSDataReader::set_listener

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 DDSReadCondition or DDSQueryCondition 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.

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

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::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 DDSQueryCondition and DDSReadCondition 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 FooDataReader::read or FooDataReader::take operation and has not called the corresponding FooDataReader::return_loan 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.

MT Safety:: UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.

Returns: One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET

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

pure virtual

Retrieves an existing DDSDataReader.

Use this operation on the built-in DDSSubscriber (Built-in Topics) 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 (see Built-in Transport Plugins for details on when a builtin transport is registered). 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 DDSDomainParticipant::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 DDS_ReturnCode_t DDSSubscriber::begin_access ( )

pure virtual

Indicates that the application is about to access the data samples in any of the DDSDataReader objects attached to the DDSSubscriber.

If the DDS_PresentationQosPolicy::access_scope of the DDSSubscriber is DDS_GROUP_PRESENTATION_QOS or DDS_HIGHEST_OFFERED_PRESENTATION_QOS and DDS_PresentationQosPolicy::ordered_access is DDS_BOOLEAN_TRUE, the application is required to use this operation to access the samples in order across DataWriters of the same group (DDSPublisher with DDS_PresentationQosPolicy::access_scope set to DDS_GROUP_PRESENTATION_QOS).

In the above case, this operation must be called prior to calling any of the sample-accessing operations, DDSSubscriber::get_datareaders on the DDSSubscriber, and FooDataReader::read, FooDataReader::take, FooDataReader::read_w_condition, and FooDataReader::take_w_condition on any DDSDataReader.

Once the application has finished accessing the data samples, it must call DDSSubscriber::end_access

The application is not required to call DDSSubscriber::begin_access / DDSSubscriber::end_access to access the samples in order if the PRESENTATION policy in the DDSPublisher has DDS_PresentationQosPolicy::access_scope set to something other than DDS_GROUP_PRESENTATION_QOS. In this case, calling DDSSubscriber::begin_access / DDSSubscriber::end_access is not considered an error and has no effect.

Calls to DDSSubscriber::begin_access / DDSSubscriber::end_access may be nested and must be balanced.

Returns: One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

See Also: Access to data samples; DDSSubscriber::get_datareaders; PRESENTATION

virtual DDS_ReturnCode_t DDSSubscriber::end_access ( )

pure virtual

Indicates that the application has finished accessing the data samples in DDSDataReader objects managed by the DDSSubscriber.

This operation must be used to close a corresponding begin_access().

This call must close a previous call to DDSSubscriber::begin_access(), otherwise the operation will fail with the error DDS_RETCODE_PRECONDITION_NOT_MET.

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

virtual DDS_ReturnCode_t DDSSubscriber::get_datareaders	(	DDSDataReaderSeq &	readers,
		DDS_SampleStateMask	sample_states,
		DDS_ViewStateMask	view_states,
		DDS_InstanceStateMask	instance_states
	)

pure virtual

Allows the application to access the DDSDataReader objects that contain samples with the specified sample_states, view_states and instance_states.

If the application is outside a begin_access()/end_access() block, or if the DDS_PresentationQosPolicy::access_scope of the DDSSubscriber is DDS_INSTANCE_PRESENTATION_QOS or DDS_TOPIC_PRESENTATION_QOS, or if the DDS_PresentationQosPolicy::ordered_access of the DDSSubscriber is DDS_BOOLEAN_FALSE, the returned collection is a 'set' containing each DDSDataReader at most once, in no specified order.

If the application is within a begin_access()/end_access() block, and the PRESENTATION policy of the DDSSubscriber is DDS_GROUP_PRESENTATION_QOS or DDS_HIGHEST_OFFERED_PRESENTATION_QOS, and DDS_PresentationQosPolicy::ordered_access in the DDSSubscriber is DDS_BOOLEAN_TRUE, the returned collection is a 'list' of DataReaders where a DataReader may appear more than one time.

To retrieve the samples in the order they were published across DataWriters of the same group (DDSPublisher configured with DDS_GROUP_PRESENTATION_QOS), the application should read()/take() from each DataReader in the same order as it appears in the output sequence. The application will move to the next DataReader when the read()/take() operation fails with DDS_RETCODE_NO_DATA.

Parameters

readers	<<inout>> a DDSDataReaderSeq object where the set or list of readers will be returned.
sample_states	<<in>> the returned DataReader must contain samples that have one of these `sample_states`.
view_states	<<in>> the returned DataReader must contain samples that have one of these `view_states`.
instance_states	<<in>> the returned DataReader must contain samples that have one of these `instance_states`.

Returns: One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

See Also: Access to data samples; DDSSubscriber::begin_access; DDSSubscriber::end_access; PRESENTATION

virtual DDS_ReturnCode_t DDSSubscriber::get_all_datareaders ( DDSDataReaderSeq & readers )

pure virtual

Retrieve all the DataReaders created from this Subscriber.

Parameters

readers <<inout>> Sequence where the DataReaders will be added

Returns: One of the Standard Return Codes

virtual DDS_ReturnCode_t DDSSubscriber::notify_datareaders ( )

pure virtual

Invokes the operation DDSDataReaderListener::on_data_available() on the DDSDataReaderListener objects attached to contained DDSDataReader entities with DDS_DATA_AVAILABLE_STATUS that is considered changed as described in Changes in read communication status.

This operation is typically invoked from the DDSSubscriberListener::on_data_on_readers operation in the DDSSubscriberListener. That way the DDSSubscriberListener can delegate to the DDSDataReaderListener objects the handling of the data.

The operation will notify the data readers that have a sample_state of DDS_NOT_READ_SAMPLE_STATE, view_state of DDS_ANY_SAMPLE_STATE and instance_state of DDS_ANY_INSTANCE_STATE.

Returns: One of the Standard Return Codes, or DDS_RETCODE_NOT_ENABLED.

virtual DDSDomainParticipant* DDSSubscriber::get_participant ( )

pure virtual

Returns the DDSDomainParticipant to which the DDSSubscriber belongs.

Returns: the DDSDomainParticipant to which the DDSSubscriber belongs.

virtual DDS_ReturnCode_t DDSSubscriber::copy_from_topic_qos	(	DDS_DataReaderQos &	datareader_qos,
		const DDS_TopicQos &	topic_qos
	)

pure virtual

Copies the policies in the DDS_TopicQos to the corresponding policies in the DDS_DataReaderQos.

Copies the policies in the DDS_TopicQos to the corresponding policies in the DDS_DataReaderQos (replacing values in the DDS_DataReaderQos, if present).

This is a "convenience" operation most useful in combination with the operations DDSSubscriber::get_default_datareader_qos and DDSTopic::get_qos. The operation DDSSubscriber::copy_from_topic_qos can be used to merge the DDSDataReader default QoS policies with the corresponding ones on the DDSTopic. The resulting QoS can then be used to create a new DDSDataReader, or set its QoS.

This operation does not check the resulting DDS_DataReaderQos for consistency. This is because the 'merged' DDS_DataReaderQos may not be the final one, as the application can still modify some policies prior to applying the policies to the DDSDataReader.

Parameters

datareader_qos	<<inout>> DDS_DataReaderQos to be filled-up.
topic_qos	<<in>> DDS_TopicQos to be merged with DDS_DataReaderQos.

Returns: One of the Standard Return Codes

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::group_data, DDS_SubscriberQos::partition and 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. Immutable 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); Operations Allowed in Listener Callbacks

virtual DDS_ReturnCode_t DDSSubscriber::set_qos_with_profile	(	const char *	library_name,
		const char *	profile_name
	)

pure virtual

<<extension>> Change the QoS of this subscriber using the input XML QoS profile.

This operation modifies the QoS of the DDSSubscriber.

The DDS_SubscriberQos::group_data, DDS_SubscriberQos::partition and DDS_SubscriberQos::entity_factory can be changed. The other policies are immutable.

Parameters

library_name	<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSSubscriber::set_default_library).
profile_name	<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSSubscriber::set_default_profile).

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; Operations Allowed in Listener Callbacks

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	(	DDSSubscriberListener *	l,
		DDS_StatusMask	mask = `DDS_STATUS_MASK_ALL`
	)

pure virtual

Sets the subscriber listener.

Parameters

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

See Also: get_listener (abstract)

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

pure virtual

<<extension>> Retrieves a DDSDataReader contained within the DDSSubscriber the DDSDataReader entity name.

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

This operation retrieves the DDSDataReader within the DDSSubscriber whose name matches the one specified. If there are several DDSDataReader with the same name within the DDSSubscriber, the operation returns the first matching occurrence.

Parameters

datareader_name <<in>> Entity name of the DDSDataReader.

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

See Also: DDSDomainParticipant::lookup_datareader_by_name

Public Member Functions

Detailed Description

Member Function Documentation