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

#include <managed_subscription.h>

Inheritance diagram for DDS::Subscriber:

Public Member Functions
void	get_default_datareader_qos (DataReaderQos^ qos)
	Copies the default DDS::DataReaderQos values into the provided DDS::DataReaderQos instance.

void	set_default_datareader_qos (DataReaderQos^ qos)
	Sets the default DDS::DataReaderQos values for this subscriber.

void	set_default_datareader_qos_with_profile (System::String^ library_name, System::String^ profile_name)
	<<eXtension>> Set the default DDS::DataReaderQos values for this subscriber based on the input XML QoS profile.

void	set_default_library (System::String^ library_name)
	<<eXtension>> Sets the default XML library for a DDS::Subscriber.

System::String^	get_default_library ()
	<<eXtension>> Gets the default XML library associated with a DDS::Subscriber.

void	set_default_profile (System::String^ library_name, System::String^ profile_name)
	<<eXtension>> Sets the default XML profile for a DDS::Subscriber.

System::String^	get_default_profile ()
	<<eXtension>> Gets the default XML profile associated with a DDS::Subscriber.

System::String^	get_default_profile_library ()
	<<eXtension>> Gets the library where the default XML QoS profile is contained for a DDS::Subscriber.

DataReader^	create_datareader (ITopicDescription^ topic, DataReaderQos^ qos, DataReaderListener^ listener, StatusMask mask)
	Creates a DDS::DataReader that will be attached and belong to the DDS::Subscriber.

DataReader^	create_datareader_with_profile (ITopicDescription^ topic, System::String^ library_name, System::String^ profile_name, DataReaderListener^ listener, StatusMask mask)
	<<eXtension>> Creates a DDS::DataReader object using the DDS::DataReaderQos associated with the input XML QoS profile.

void	delete_datareader (DataReader^ %a_datareader)
	Deletes a DDS::DataReader that belongs to the DDS::Subscriber.

void	delete_contained_entities ()
	Deletes all the entities that were created by means of the "create" operation on the DDS::Subscriber.

DataReader^	lookup_datareader (System::String^ topic_name)
	Retrieves an existing DDS::DataReader.

void	begin_access ()
	Indicates that the application is about to access the data samples in any of the DDS::DataReader objects attached to the DDS::Subscriber.

void	end_access ()
	Indicates that the application has finished accessing the data samples in DDS::DataReader objects managed by the DDS::Subscriber.

void	get_datareaders (DataReaderSeq^ readers, System::UInt32 sample_states, System::UInt32 view_states, System::UInt32 instance_states)
	Allows the application to access the DDS::DataReader objects that contain samples with the specified `sample_states`, `view_states` and `instance_states`.

void	get_all_datareaders (DataReaderSeq^ readers)
	Retrieve all the DataReaders created from this Subscriber.

void	notify_datareaders ()
	Invokes the operation DDS::DataReaderListener::on_data_available() on the DDS::DataReaderListener objects attached to contained DDS::DataReader entities with ::DDS::StatusKind::DATA_AVAILABLE_STATUS that is considered changed as described in Changes in read communication status.

DomainParticipant^	get_participant ()
	Returns the DDS::DomainParticipant to which the DDS::Subscriber belongs.

void	copy_from_topic_qos (DataReaderQos^ datareader_qos, TopicQos^ topic_qos)
	Copies the policies in the DDS::TopicQos to the corresponding policies in the DDS::DataReaderQos.

void	set_qos (SubscriberQos^ qos)
	Sets the subscriber QoS.

void	set_qos_with_profile (System::String^ library_name, System::String^ profile_name)
	<<eXtension>> Change the QoS of this subscriber using the input XML QoS profile.

void	get_qos (SubscriberQos^ qos)
	Gets the subscriber QoS.

void	set_listener (SubscriberListener^ l, StatusMask mask)
	Sets the subscriber listener.

SubscriberListener^	get_listener ()
	Get the subscriber listener.

virtual void	enable () override
	Enables the DDS::Entity.

virtual StatusCondition^	get_statuscondition () override
	Allows access to the DDS::StatusCondition associated with the DDS::Entity.

virtual StatusMask	get_status_changes () override
	Retrieves the list of communication statuses in the DDS::Entity that are triggered.

virtual InstanceHandle_t	get_instance_handle () override
	Allows access to the DDS::InstanceHandle_t associated with the DDS::Entity.

DataReader^	lookup_datareader_by_name_exp (String^ datareader_name)
	<<experimental>> <<eXtension>> Retrieves a DDS::DataReader contained within the DDS::Subscriber the DDS::DataReader entity name.

Properties
static DataReaderQos^	DATAREADER_QOS_DEFAULT `[get]`
	Special value for creating data reader with default QoS.

static DataReaderQos^	DATAREADER_QOS_USE_TOPIC_QOS `[get]`
	Special value for creating DDS::DataReader with a combination of the default DDS::DataReaderQos and the DDS::TopicQos.

Detailed Description

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

QoS:: DDS::SubscriberQos

Status:: ::DDS::StatusKind::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 or by enabling related conditions.

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_NotEnabled if called on a disabled DDS::Subscriber:

All operations except for the base-class operations set_qos(), set_qos_with_profile(), get_qos(), set_listener(), get_listener(), enable() and create_datareader() may fail with DDS::Retcode_NotEnabled.

See Also: Operations Allowed in Listener Callbacks

Examples:: HelloWorld_subscriber.cpp.

Member Function Documentation

void DDS::Subscriber::get_default_datareader_qos ( DataReaderQos^ qos )

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

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 DDS::Subscriber::set_default_datareader_qos

Parameters

qos	<<inout>> DDS::DataReaderQos to be filled-up. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

See Also: DDS::Subscriber::DATAREADER_QOS_DEFAULT; DDS::Subscriber::create_datareader

void DDS::Subscriber::set_default_datareader_qos ( 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::Subscriber::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_InconsistentPolicy

MT Safety:: UNSAFE. It is not safe to set the default QoS value from a subscriber while another thread may be simultaneously calling DDS::Subscriber::set_default_datareader_qos, DDS::Subscriber::get_default_datareader_qos or calling DDS::Subscriber::create_datareader with DDS::Subscriber::DATAREADER_QOS_DEFAULT as the qos parameter.

Parameters

qos <<in>> The default DDS::DataReaderQos to be set to. The special value DDS::Subscriber::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 DDS::Subscriber::set_default_datareader_qos had never been called. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, or or DDS::Retcode_InconsistentPolicy

void DDS::Subscriber::set_default_datareader_qos_with_profile	(	System::String^	library_name,
		System::String^	profile_name
	)

<<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 DDS::DataReader if DDS::Subscriber::DATAREADER_QOS_DEFAULT is specified as the qos parameter when DDS::Subscriber::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_InconsistentPolicy

MT Safety:: UNSAFE. It is not safe to set the default QoS value from a DDS::Subscriber while another thread may be simultaneously calling DDS::Subscriber::set_default_datareader_qos, DDS::Subscriber::get_default_datareader_qos or calling DDS::Subscriber::create_datareader with DDS::Subscriber::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 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).

If the input profile cannot be found the method fails with DDS::Retcode_Error.

Exceptions

One	of the Standard Return Codes, or DDS::Retcode_InconsistentPolicy

See Also: DDS::Subscriber::DATAREADER_QOS_DEFAULT; DDS::Subscriber::create_datareader_with_profile

void DDS::Subscriber::set_default_library ( System::String^ library_name )

<<eXtension>> Sets the default XML library for a DDS::Subscriber.

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 DDS::Subscriber inherits the default from the DDS::DomainParticipant (see DDS::DomainParticipant::set_default_library).

Parameters

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

Exceptions

One	of the Standard Return Codes

See Also: DDS::Subscriber::get_default_library

System::String ^ DDS::Subscriber::get_default_library ( )

<<eXtension>> Gets the default XML library associated with a DDS::Subscriber.

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

See Also: DDS::Subscriber::set_default_library

void DDS::Subscriber::set_default_profile	(	System::String^	library_name,
		System::String^	profile_name
	)

<<eXtension>> Sets the default XML profile for a DDS::Subscriber.

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 DDS::Subscriber 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 DDS::Subscriber inherits the default from the DDS::DomainParticipant (see DDS::DomainParticipant::set_default_profile).

This method does not set the default QoS for DDS::DataReader objects created by this DDS::Subscriber; for this functionality, use DDS::Subscriber::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 DDS::DomainParticipant::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.

Exceptions

One	of the Standard Return Codes

See Also: DDS::Subscriber::get_default_profile; DDS::Subscriber::get_default_profile_library

System::String ^ DDS::Subscriber::get_default_profile ( )

<<eXtension>> Gets the default XML profile associated with a DDS::Subscriber.

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

See Also: DDS::Subscriber::set_default_profile

System::String ^ DDS::Subscriber::get_default_profile_library ( )

<<eXtension>> Gets the library where the default XML QoS profile is contained for a DDS::Subscriber.

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

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

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

See Also: DDS::Subscriber::set_default_profile

DataReader ^ DDS::Subscriber::create_datareader	(	ITopicDescription^	topic,
		DataReaderQos^	qos,
		DataReaderListener^	listener,
		StatusMask	mask
	)

Creates a DDS::DataReader that will be attached and belong to the DDS::Subscriber.

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

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

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

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

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

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 method will return NULL.; If qos is ::DDS::DATAREADER_QOS_USE_TOPIC_QOS, topic cannot be DDS::MultiTopic, or else this method will return NULL.

Parameters

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::Subscriber::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. If ::DDS::TopicDescription is of type DDS::Topic or DDS::ContentFilteredTopic, the special value ::DDS::DATAREADER_QOS_USE_TOPIC_QOS can be used to indicate that the DDS::DataReader should be created with the combination of the default DDS::DataReaderQos set on the DDS::Subscriber and the DDS::TopicQos (in the case of a DDS::ContentFilteredTopic, the DDS::TopicQos of the related DDS::Topic). if ::DDS::DATAREADER_QOS_USE_TOPIC_QOS is used, `topic` cannot be a DDS::MultiTopic. Cannot be NULL.
listener	<<in>> The listener of the DDS::DataReader.
mask	<<in>>. Changes of communication status to be invoked on the listener. See ::DDS::StatusMask.

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

See Also: DDS::TypedDataReader; Specifying QoS on entities for information on setting QoS before entity creation; DDS::DataReaderQos for rules on consistency among QoS; DDS::Subscriber::create_datareader_with_profile; DDS::Subscriber::get_default_datareader_qos; DDS::Topic::set_qos; DDS::Subscriber::copy_from_topic_qos; DDS::DataReader::set_listener

Examples:: HelloWorld_subscriber.cpp.

DataReader ^ DDS::Subscriber::create_datareader_with_profile	(	ITopicDescription^	topic,
		System::String^	library_name,
		System::String^	profile_name,
		DataReaderListener^	listener,
		StatusMask	mask
	)

<<eXtension>> Creates a DDS::DataReader object using the DDS::DataReaderQos associated with the input XML QoS profile.

The DDS::DataReader will be attached and belong to the DDS::Subscriber.

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

When a DDS::DataReader is created, only those transports already registered are available to the DDS::DataReader. 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 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 method will return NULL.

Parameters

topic	<<in>> The ::DDS::TopicDescription that the DDS::DataReader 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 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).
listener	<<in>> The listener of the DDS::DataReader.
mask	<<in>>. Changes of communication status to be invoked on the listener. See ::DDS::StatusMask.

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

See Also: DDS::TypedDataReader; Specifying QoS on entities for information on setting QoS before entity creation; DDS::DataReaderQos for rules on consistency among QoS; DDS::Subscriber::DATAREADER_QOS_DEFAULT; ::DDS::DATAREADER_QOS_USE_TOPIC_QOS; DDS::Subscriber::create_datareader; DDS::Subscriber::get_default_datareader_qos; DDS::Topic::set_qos; DDS::Subscriber::copy_from_topic_qos; DDS::DataReader::set_listener

void DDS::Subscriber::delete_datareader ( DataReader^ % a_datareader )

Deletes a DDS::DataReader that belongs to the DDS::Subscriber.

Precondition: If the DDS::DataReader does not belong to the DDS::Subscriber, or if ther are any existing DDS::ReadCondition or DDS::QueryCondition objects that are attached to the DDS::DataReader, 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_PreconditionNotMet.

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

Parameters

a_datareader <<in>> The DDS::DataReader to be deleted.

Exceptions

One	of the Standard Return Codes or DDS::Retcode_PreconditionNotMet.

void DDS::Subscriber::delete_contained_entities ( )

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 DDS::QueryCondition and DDS::ReadCondition objects belonging to the contained DDS::DataReader.

The operation will fail with DDS::Retcode_PreconditionNotMet if any of the contained entities is in a state where it cannot be deleted. This will occur, for example, if a contained DDS::DataReader cannot be deleted because the application has called a DDS::TypedDataReader::read or DDS::TypedDataReader::take operation and has not called the corresponding DDS::TypedDataReader::return_loan operation to return the loaned samples.

Once DDS::Subscriber::delete_contained_entities completes successfully, the application may delete the DDS::Subscriber, knowing that it has no contained DDS::DataReader objects.

Exceptions

One	of the Standard Return Codes, or DDS::Retcode_PreconditionNotMet

DataReader ^ DDS::Subscriber::lookup_datareader ( System::String^ topic_name )

Retrieves an existing DDS::DataReader.

Use this operation on the built-in DDS::Subscriber (Built-in Topics) 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 (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 DDS::DomainParticipant.
(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 ::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:: UNSAFE. It is not safe to lookup a DDS::DataReader in one thread while another thread is simultaneously creating or destroying that DDS::DataReader.

void DDS::Subscriber::begin_access ( )

Indicates that the application is about to access the data samples in any of the DDS::DataReader objects attached to the DDS::Subscriber.

If the DDS::PresentationQosPolicy::access_scope of the DDS::Subscriber is ::DDS::PresentationQosPolicyAccessScopeKind::GROUP_PRESENTATION_QOS or ::DDS::PresentationQosPolicyAccessScopeKind::HIGHEST_OFFERED_PRESENTATION_QOS and DDS::PresentationQosPolicy::ordered_access is true, the application is required to use this operation to access the samples in order across DataWriters of the same group (DDS::Publisher with DDS::PresentationQosPolicy::access_scope set to ::DDS::PresentationQosPolicyAccessScopeKind::GROUP_PRESENTATION_QOS).

In the above case, the operation begin_access() must be called prior to calling any of the sample-accessing operations, DDS::Subscriber::get_datareaders on the DDS::Subscriber, and DDS::TypedDataReader::read, DDS::TypedDataReader::take, DDS::TypedDataReader::read_w_condition, and DDS::TypedDataReader::take_w_condition on any DDS::DataReader.

Once the application has finished accessing the data samples, it must call DDS::Subscriber::end_access.

The application is not required to call begin_access() / end_access() to access the samples in order if the PRESENTATION policy in the DDS::Publisher has DDS::PresentationQosPolicy::access_scope set to something other than ::DDS::PresentationQosPolicyAccessScopeKind::GROUP_PRESENTATION_QOS. In this case, calling begin_access() / end_access() is not considered an error and has no effect.

Calls to begin_access() / end_access() may be nested and must be balanced.

Exceptions

One	of the Standard Return Codes or DDS::Retcode_NotEnabled.

See Also: Access to data samples; DDS::Subscriber::get_datareaders; PRESENTATION

void DDS::Subscriber::end_access ( )

Indicates that the application has finished accessing the data samples in DDS::DataReader objects managed by the DDS::Subscriber.

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

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

Exceptions

One	of the Standard Return Codes or DDS::Retcode_PreconditionNotMet or DDS::Retcode_NotEnabled.

void DDS::Subscriber::get_datareaders	(	DataReaderSeq^	readers,
		System::UInt32	sample_states,
		System::UInt32	view_states,
		System::UInt32	instance_states
	)

Allows the application to access the DDS::DataReader 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 DDS::Subscriber is ::DDS::PresentationQosPolicyAccessScopeKind::INSTANCE_PRESENTATION_QOS or ::DDS::PresentationQosPolicyAccessScopeKind::TOPIC_PRESENTATION_QOS, or if the DDS::PresentationQosPolicy::ordered_access of the DDS::Subscriber is false, the returned collection is a 'set' containing each DDS::DataReader at most once, in no specified order.

If the application is within a begin_access()/end_access() block, and the PRESENTATION policy of the DDS::Subscriber is ::DDS::PresentationQosPolicyAccessScopeKind::GROUP_PRESENTATION_QOS or ::DDS::PresentationQosPolicyAccessScopeKind::HIGHEST_OFFERED_PRESENTATION_QOS, and DDS::PresentationQosPolicy::ordered_access in the DDS::Subscriber is 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 (DDS::Publisher configured with ::DDS::PresentationQosPolicyAccessScopeKind::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_NoData.

Parameters

readers	<<inout>> a DDS::DataReaderSeq object where the set or list of readers will be returned. Cannot be NULL.
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`.

Exceptions

One	of the Standard Return Codes or DDS::Retcode_NotEnabled.

See Also: Access to data samples; DDS::Subscriber::begin_access; DDS::Subscriber::end_access; PRESENTATION

void DDS::Subscriber::get_all_datareaders ( DataReaderSeq^ readers )

Retrieve all the DataReaders created from this Subscriber.

Parameters

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

Exceptions

One	of the Standard Return Codes

void DDS::Subscriber::notify_datareaders ( )

Invokes the operation DDS::DataReaderListener::on_data_available() on the DDS::DataReaderListener objects attached to contained DDS::DataReader entities with ::DDS::StatusKind::DATA_AVAILABLE_STATUS that is considered changed as described in Changes in read communication status.

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

The operation will notify the data readers that have a sample_state of DDS::SampleStateKind::NOT_READ_SAMPLE_STATE, view_state of DDS::SampleStateKind::ANY_SAMPLE_STATE and instance_state of DDS::InstanceStateKind::ANY_INSTANCE_STATE.

Exceptions

One	of the Standard Return Codes, or DDS::Retcode_NotEnabled.

DomainParticipant ^ DDS::Subscriber::get_participant ( )

Returns the DDS::DomainParticipant to which the DDS::Subscriber belongs.

Returns: the DDS::DomainParticipant to which the DDS::Subscriber belongs.

void DDS::Subscriber::copy_from_topic_qos	(	DataReaderQos^	datareader_qos,
		TopicQos^	topic_qos
	)

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 DDS::Subscriber::get_default_datareader_qos and DDS::Topic::get_qos. The operation DDS::Subscriber::copy_from_topic_qos can be used to merge the DDS::DataReader default QoS policies with the corresponding ones on the DDS::Topic. The resulting QoS can then be used to create a new DDS::DataReader, 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 DDS::DataReader.

Parameters

datareader_qos	<<inout>> DDS::DataReaderQos to be filled-up. Cannot be NULL.
topic_qos	<<in>> DDS::TopicQos to be merged with DDS::DataReaderQos. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

void DDS::Subscriber::set_qos ( SubscriberQos^ qos )

Sets the subscriber QoS.

This operation modifies the QoS of the DDS::Subscriber.

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 DDS::Subscriber is enabled. The special value DDS::DomainParticipant::SUBSCRIBER_QOS_DEFAULT can be used to indicate that the QoS of the DDS::Subscriber should be changed to match the current default DDS::SubscriberQos set in the DDS::DomainParticipant. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, DDS::Retcode_ImmutablePolicy, or DDS::Retcode_InconsistentPolicy.

See Also: DDS::SubscriberQos for rules on consistency among QoS; set_qos (abstract); Operations Allowed in Listener Callbacks

void DDS::Subscriber::set_qos_with_profile	(	System::String^	library_name,
		System::String^	profile_name
	)

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

This operation modifies the QoS of the DDS::Subscriber.

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

Exceptions

One	of the Standard Return Codes, DDS::Retcode_ImmutablePolicy, or DDS::Retcode_InconsistentPolicy.

See Also: DDS::SubscriberQos for rules on consistency among QoS; Operations Allowed in Listener Callbacks

void DDS::Subscriber::get_qos ( SubscriberQos^ qos )

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

Exceptions

One	of the Standard Return Codes

See Also: get_qos (abstract)

void DDS::Subscriber::set_listener	(	SubscriberListener^	l,
		StatusMask	mask
	)

Sets the subscriber listener.

Parameters

l	<<in>> DDS::SubscriberListener to set to.
mask	<<in>> ::DDS::StatusMask associated with the DDS::SubscriberListener.

Exceptions

One	of the Standard Return Codes

See Also: set_listener (abstract)

SubscriberListener ^ DDS::Subscriber::get_listener ( )

Get the subscriber listener.

Returns: DDS::SubscriberListener of the DDS::Subscriber.

See Also: get_listener (abstract)

virtual void DDS::Subscriber::enable ( )

overridevirtual

Enables the DDS::Entity.

This operation enables the Entity. Entity objects can be created either enabled or disabled. This is controlled by the value of the ENTITY_FACTORY QoS policy on the corresponding factory for the DDS::Entity.

By default, ENTITY_FACTORY is set so that it is not necessary to explicitly call DDS::Entity::enable on newly created entities.

The DDS::Entity::enable operation is idempotent. Calling enable on an already enabled Entity returns OK and has no effect.

If a DDS::Entity has not yet been enabled, the following kinds of operations may be invoked on it:

set or get the QoS policies (including default QoS policies) and listener
DDS::Entity::get_statuscondition
'factory' operations
DDS::Entity::get_status_changes and other get status operations (although the status of a disabled entity never changes)
'lookup' operations

Other operations may explicitly state that they may be called on disabled entities; those that do not will return the error DDS::Retcode_NotEnabled.

It is legal to delete an DDS::Entity that has not been enabled by calling the proper operation on its factory.

Entities created from a factory that is disabled are created disabled, regardless of the setting of the DDS::EntityFactoryQosPolicy.

Calling enable on an Entity whose factory is not enabled will fail and return DDS::Retcode_PreconditionNotMet.

If DDS::EntityFactoryQosPolicy::autoenable_created_entities is TRUE, the enable operation on a factory will automatically enable all entities created from that factory.

Listeners associated with an entity are not called until the entity is enabled.

Conditions associated with a disabled entity are "inactive," that is, they have a trigger_value == FALSE.

Exceptions

One	of the Standard Return Codes, Standard Return Codes or DDS::Retcode_PreconditionNotMet.

Implements DDS::Entity.

virtual StatusCondition ^ DDS::Subscriber::get_statuscondition ( )

overridevirtual

Allows access to the DDS::StatusCondition associated with the DDS::Entity.

The returned condition can then be added to a DDS::WaitSet so that the application can wait for specific status changes that affect the DDS::Entity.

Returns: the status condition associated with this entity.

Implements DDS::Entity.

virtual StatusMask DDS::Subscriber::get_status_changes ( )

overridevirtual

Retrieves the list of communication statuses in the DDS::Entity that are triggered.

That is, the list of statuses whose value has changed since the last time the application read the status using the get_*_status() method.

When the entity is first created or if the entity is not enabled, all communication statuses are in the "untriggered" state so the list returned by the get_status_changes operation will be empty.

The list of statuses returned by the get_status_changes operation refers to the status that are triggered on the Entity itself and does not include statuses that apply to contained entities.

Returns: list of communication statuses in the DDS::Entity that are triggered.

See Also: Status Kinds

Implements DDS::Entity.

virtual InstanceHandle_t DDS::Subscriber::get_instance_handle ( )

overridevirtual

Allows access to the DDS::InstanceHandle_t associated with the DDS::Entity.

This operation returns the DDS::InstanceHandle_t that represents the DDS::Entity.

Returns: the instance handle associated with this entity.

Implements DDS::Entity.

DataReader ^ DDS::Subscriber::lookup_datareader_by_name_exp ( String^ datareader_name )

<<experimental>> <<eXtension>> Retrieves a DDS::DataReader contained within the DDS::Subscriber the DDS::DataReader entity name.

Every DDS::DataReader in the system has an entity name which is configured and stored in the <<eXtension>> EntityName policy, ENTITY_NAME.

This operation retrieves the DDS::DataReader within the DDS::Subscriber whose name matches the one specified. If there are several DDS::DataReader with the same name within the DDS::Subscriber, the operation returns the first matching occurrence.

Parameters

datareader_name <<in>> Entity name of the DDS::DataReader.

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

See Also: DDS::DomainParticipant::lookup_datareader_by_name_exp

Public Member Functions

Properties

Detailed Description

Member Function Documentation