DDS::Subscriber Class Reference
[Subscribers]

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

List of all members.

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.

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 Data Distribution Service will use the default library (see DDS::Subscriber::set_default_library).
profile_name <<in>> XML QoS Profile name. If profile_name is null RTI Data Distribution Service 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:

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.
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 Data Distribution Service will use the default library (see DDS::Subscriber::set_default_library).
profile_name <<in>> XML QoS Profile name. If profile_name is null RTI Data Distribution Service 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.
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:

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 Data Distribution Service will use the default library (see DDS::Subscriber::set_default_library).
profile_name <<in>> XML QoS Profile name. If profile_name is null RTI Data Distribution Service 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 (  )  [override, virtual]

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:
One of the Standard Return Codes, Standard Return Codes or DDS::Retcode_PreconditionNotMet.

Implements DDS::Entity.

virtual StatusCondition ^ DDS::Subscriber::get_statuscondition (  )  [override, virtual]

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 (  )  [override, virtual]

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 (  )  [override, virtual]

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.

RTI Data Distribution Service .Net APIs Version 4.5e Copyright © 23 Oct 2011 Real-Time Innovations, Inc