RTI Connext .Net APIs  Version 6.0.1

<<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. More...
 
void set_default_datareader_qos (DataReaderQos^ qos)
 Sets the default DDS::DataReaderQos values for this subscriber. More...
 
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. More...
 
void set_default_library (System::String^ library_name)
 <<extension>> Sets the default XML library for a DDS::Subscriber. More...
 
System::String ^ get_default_library ()
 <<extension>> Gets the default XML library associated with a DDS::Subscriber. More...
 
void set_default_profile (System::String^ library_name, System::String^ profile_name)
 <<extension>> Sets the default XML profile for a DDS::Subscriber. More...
 
System::String ^ get_default_profile ()
 <<extension>> Gets the default XML profile associated with a DDS::Subscriber. More...
 
System::String ^ get_default_profile_library ()
 <<extension>> Gets the library where the default XML QoS profile is contained for a DDS::Subscriber. More...
 
DataReadercreate_datareader (ITopicDescription^ topic, DataReaderQos^ qos, DataReaderListener^ listener, StatusMask mask)
 Creates a DDS::DataReader that will be attached and belong to the DDS::Subscriber. More...
 
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. More...
 
void delete_datareader (DataReader^% a_datareader)
 Deletes a DDS::DataReader that belongs to the DDS::Subscriber. More...
 
void delete_contained_entities ()
 Deletes all the entities that were created by means of the "create" operation on the DDS::Subscriber. More...
 
DataReaderlookup_datareader (System::String^ topic_name)
 Retrieves an existing DDS::DataReader. More...
 
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. More...
 
void end_access ()
 Indicates that the application has finished accessing the data samples in DDS::DataReader objects managed by the DDS::Subscriber. More...
 
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. More...
 
void get_all_datareaders (DataReaderSeq^ readers)
 Retrieve all the DataReaders created from this Subscriber. More...
 
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. More...
 
DomainParticipantget_participant ()
 Returns the DDS::DomainParticipant to which the DDS::Subscriber belongs. More...
 
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. More...
 
void set_qos (SubscriberQos^ qos)
 Sets the subscriber QoS. More...
 
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. More...
 
void get_qos (SubscriberQos^ qos)
 Gets the subscriber QoS. More...
 
void set_listener (SubscriberListener^ l, StatusMask mask)
 Sets the subscriber listener. More...
 
SubscriberListenerget_listener ()
 Get the subscriber listener. More...
 
virtual void enable () override
 Enables the DDS::Entity. More...
 
virtual StatusConditionget_statuscondition () override
 Allows access to the DDS::StatusCondition associated with the DDS::Entity. More...
 
virtual StatusMask get_status_changes () override
 Retrieves the list of communication statuses in the DDS::Entity that are triggered. More...
 
virtual InstanceHandle_t get_instance_handle () override
 Allows access to the DDS::InstanceHandle_t associated with the DDS::Entity. More...
 
DataReaderlookup_datareader_by_name (String^ datareader_name)
 <<extension>> Retrieves a DDS::DataReader contained within the DDS::Subscriber the DDS::DataReader entity name. More...
 

Properties

static DataReaderQosDATAREADER_QOS_DEFAULT [get]
 Special value for creating data reader with default QoS. More...
 
static DataReaderQosDATAREADER_QOS_USE_TOPIC_QOS [get]
 Special value for creating DDS::DataReader with a combination of the default DDS::DataReaderQos and the DDS::TopicQos. More...
 

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 DDS::Subscriber::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 DDS::Subscriber::set_qos, DDS::Subscriber::set_qos_with_profile,DDS::Subscriber::get_qos, DDS::Subscriber::set_listener, DDS::Subscriber::get_listener, DDS::Entity::enable and DDS::Subscriber::create_datareader may fail with DDS::Retcode_NotEnabled.

See also
Operations Allowed in Listener Callbacks
Examples:
HelloWorld_subscriber.cpp.

Member Function Documentation

◆ get_default_datareader_qos()

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

◆ set_default_datareader_qos()

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

◆ set_default_datareader_qos_with_profile()

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

◆ set_default_library()

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

◆ 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

◆ set_default_profile()

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

◆ get_default_profile()

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

◆ get_default_profile_library()

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

◆ create_datareader()

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 ITopicDescription 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::Subscriber::DATAREADER_QOS_USE_TOPIC_QOS, topic cannot be DDS::MultiTopic, or else this method will return NULL.
Parameters
topic<<in>> The ITopicDescription 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 ITopicDescription is of type DDS::Topic or DDS::ContentFilteredTopic, the special value DDS::Subscriber::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::Subscriber::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.

◆ create_datareader_with_profile()

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 ITopicDescription 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 ITopicDescription 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::Subscriber::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

◆ delete_datareader()

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.
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 DDS::DataReader to be deleted.
Exceptions
Oneof the Standard Return Codes or DDS::Retcode_PreconditionNotMet.

◆ delete_contained_entities()

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.

MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
Exceptions
Oneof the Standard Return Codes, or DDS::Retcode_PreconditionNotMet

◆ lookup_datareader()

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 ITopicDescription that the retrieved DDS::DataReader is attached to. Cannot be NULL.
Returns
A DDS::DataReader that belongs to the DDS::Subscriber attached to the ITopicDescription 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.

◆ begin_access()

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, this operation 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 DDS::Subscriber::begin_access / DDS::Subscriber::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 DDS::Subscriber::begin_access / DDS::Subscriber::end_access is not considered an error and has no effect.

Calls to DDS::Subscriber::begin_access / DDS::Subscriber::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

◆ end_access()

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.

◆ get_datareaders()

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

◆ get_all_datareaders()

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

◆ notify_datareaders()

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.

◆ get_participant()

DomainParticipant ^ DDS::Subscriber::get_participant ( )

◆ copy_from_topic_qos()

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

◆ set_qos()

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

Referenced by RTI.Connext.Queuing.QueueConsumer< TRep >::QueueConsumer().

◆ set_qos_with_profile()

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

◆ get_qos()

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)

Referenced by RTI.Connext.Queuing.QueueConsumer< TRep >::QueueConsumer().

◆ set_listener()

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)

◆ get_listener()

SubscriberListener ^ DDS::Subscriber::get_listener ( )

Get the subscriber listener.

Returns
DDS::SubscriberListener of the DDS::Subscriber.
See also
get_listener (abstract)

◆ enable()

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 Entity that is disabled are created disabled, regardless of the setting of the DDS::EntityFactoryQosPolicy.

Calling enable on an Entity whose factory Entity 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 (for example, enabling a DDS::Publisher will enable all its contained DDS::DataWriter objects)

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.

◆ get_statuscondition()

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.

◆ get_status_changes()

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.

◆ get_instance_handle()

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.

◆ lookup_datareader_by_name()

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

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

RTI Connext .Net APIs Version 6.0.1 Copyright © Sat Nov 23 2019 Real-Time Innovations, Inc