RTI Connext .Net APIs  Version 5.0.0
DDS::Subscriber Class Reference

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

#include <managed_subscription.h>

Inheritance diagram for DDS::Subscriber:
DDS::DomainEntity DDS::Entity

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.
 
DataReadercreate_datareader (ITopicDescription^ topic, DataReaderQos^ qos, DataReaderListener^ listener, StatusMask mask)
 Creates a DDS::DataReader that will be attached and belong to the DDS::Subscriber.
 
DataReadercreate_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.
 
DataReaderlookup_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.
 
DomainParticipantget_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.
 
SubscriberListenerget_listener ()
 Get the subscriber listener.
 
virtual void enable () override
 Enables the DDS::Entity.
 
virtual StatusConditionget_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.
 
DataReaderlookup_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
Oneof 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
Oneof 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
Oneof 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
Oneof 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
Oneof 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:

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
Oneof 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
Oneof 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:

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
Oneof 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
Oneof 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
Oneof 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
Oneof 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
Oneof 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
Oneof 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
Oneof 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
Oneof 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
Oneof 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
Oneof 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:

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
Oneof 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

RTI Connext .Net APIs Version 5.0.0 Copyright © Thu Aug 30 2012 Real-Time Innovations, Inc