RTI Connext Traditional C++ API  Version 6.0.0
 All Classes Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
DDSSubscriber Class Referenceabstract

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

Inheritance diagram for DDSSubscriber:
DDSDomainEntity DDSEntity

Public Member Functions

virtual DDS_ReturnCode_t get_default_datareader_qos (DDS_DataReaderQos &qos)=0
 Copies the default DDS_DataReaderQos values into the provided DDS_DataReaderQos instance.
 
virtual DDS_ReturnCode_t set_default_datareader_qos (const DDS_DataReaderQos &qos)=0
 Sets the default DDS_DataReaderQos values for this subscriber.
 
virtual DDS_ReturnCode_t set_default_datareader_qos_with_profile (const char *library_name, const char *profile_name)=0
 <<extension>> Set the default DDS_DataReaderQos values for this subscriber based on the input XML QoS profile.
 
virtual DDS_ReturnCode_t set_default_library (const char *library_name)=0
 <<extension>> Sets the default XML library for a DDSSubscriber.
 
virtual const char * get_default_library ()=0
 <<extension>> Gets the default XML library associated with a DDSSubscriber.
 
virtual DDS_ReturnCode_t set_default_profile (const char *library_name, const char *profile_name)=0
 <<extension>> Sets the default XML profile for a DDSSubscriber.
 
virtual const char * get_default_profile ()=0
 <<extension>> Gets the default XML profile associated with a DDSSubscriber.
 
virtual const char * get_default_profile_library ()=0
 <<extension>> Gets the library where the default XML QoS profile is contained for a DDSSubscriber.
 
virtual DDSDataReadercreate_datareader (DDSTopicDescription *topic, const DDS_DataReaderQos &qos, DDSDataReaderListener *listener, DDS_StatusMask mask)=0
 Creates a DDSDataReader that will be attached and belong to the DDSSubscriber.
 
virtual DDSDataReadercreate_datareader_with_profile (DDSTopicDescription *topic, const char *library_name, const char *profile_name, DDSDataReaderListener *listener, DDS_StatusMask mask)=0
 <<extension>> Creates a DDSDataReader object using the DDS_DataReaderQos associated with the input XML QoS profile.
 
virtual DDS_ReturnCode_t delete_datareader (DDSDataReader *a_datareader)=0
 Deletes a DDSDataReader that belongs to the DDSSubscriber.
 
virtual DDS_ReturnCode_t delete_contained_entities ()=0
 Deletes all the entities that were created by means of the "create" operation on the DDSSubscriber.
 
virtual DDSDataReaderlookup_datareader (const char *topic_name)=0
 Retrieves an existing DDSDataReader.
 
virtual DDS_ReturnCode_t begin_access ()=0
 Indicates that the application is about to access the data samples in any of the DDSDataReader objects attached to the DDSSubscriber.
 
virtual DDS_ReturnCode_t end_access ()=0
 Indicates that the application has finished accessing the data samples in DDSDataReader objects managed by the DDSSubscriber.
 
virtual DDS_ReturnCode_t get_datareaders (DDSDataReaderSeq &readers, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)=0
 Allows the application to access the DDSDataReader objects that contain samples with the specified sample_states, view_states and instance_states.
 
virtual DDS_ReturnCode_t get_all_datareaders (DDSDataReaderSeq &readers)=0
 Retrieve all the DataReaders created from this Subscriber.
 
virtual DDS_ReturnCode_t notify_datareaders ()=0
 Invokes the operation DDSDataReaderListener::on_data_available() on the DDSDataReaderListener objects attached to contained DDSDataReader entities with DDS_DATA_AVAILABLE_STATUS that is considered changed as described in Changes in read communication status.
 
virtual DDSDomainParticipantget_participant ()=0
 Returns the DDSDomainParticipant to which the DDSSubscriber belongs.
 
virtual DDS_ReturnCode_t copy_from_topic_qos (DDS_DataReaderQos &datareader_qos, const DDS_TopicQos &topic_qos)=0
 Copies the policies in the DDS_TopicQos to the corresponding policies in the DDS_DataReaderQos.
 
virtual DDS_ReturnCode_t set_qos (const DDS_SubscriberQos &qos)=0
 Sets the subscriber QoS.
 
virtual DDS_ReturnCode_t set_qos_with_profile (const char *library_name, const char *profile_name)=0
 <<extension>> Change the QoS of this subscriber using the input XML QoS profile.
 
virtual DDS_ReturnCode_t get_qos (DDS_SubscriberQos &qos)=0
 Gets the subscriber QoS.
 
virtual DDS_ReturnCode_t set_listener (DDSSubscriberListener *l, DDS_StatusMask mask=DDS_STATUS_MASK_ALL)=0
 Sets the subscriber listener.
 
virtual DDSSubscriberListenerget_listener ()=0
 Get the subscriber listener.
 
virtual DDSDataReaderlookup_datareader_by_name (const char *datareader_name)=0
 <<extension>> Retrieves a DDSDataReader contained within the DDSSubscriber the DDSDataReader entity name.
 

Detailed Description

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

QoS:
DDS_SubscriberQos
Status:
DDS_DATA_ON_READERS_STATUS
Listener:
DDSSubscriberListener

A subscriber acts on the behalf of one or several DDSDataReader objects that are related to it. When it receives data (from the other parts of the system), it builds the list of concerned DDSDataReader objects and then indicates to the application that data is available through its listener or by enabling related conditions.

The application can access the list of concerned DDSDataReader objects through the operation DDSSubscriber::get_datareaders and then access the data available through operations on the DDSDataReader.

The following operations may be called even if the DDSSubscriber is not enabled. Other operations will the value DDS_RETCODE_NOT_ENABLED if called on a disabled DDSSubscriber:

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

See Also
Operations Allowed in Listener Callbacks
Examples:
HelloWorld_subscriber.cxx.

Member Function Documentation

virtual DDS_ReturnCode_t DDSSubscriber::get_default_datareader_qos ( DDS_DataReaderQos qos)
pure virtual

Copies the default DDS_DataReaderQos values into the provided DDS_DataReaderQos instance.

The retrieved qos will match the set of values specified on the last successful call to DDSSubscriber::set_default_datareader_qos, or DDSSubscriber::set_default_datareader_qos_with_profile, or else, if the call was never made, the default values from is owning DDSDomainParticipant.

This method may potentially allocate memory depending on the sequences contained in some QoS policies.

MT Safety:
UNSAFE. It is not safe to retrieve the default QoS value from a subscriber while another thread may be simultaneously calling DDSSubscriber::set_default_datareader_qos
Parameters
qos<<inout>> DDS_DataReaderQos to be filled-up.
Returns
One of the Standard Return Codes
See Also
DDS_DATAREADER_QOS_DEFAULT
DDSSubscriber::create_datareader
virtual DDS_ReturnCode_t DDSSubscriber::set_default_datareader_qos ( const DDS_DataReaderQos qos)
pure virtual

Sets the default DDS_DataReaderQos values for this subscriber.

This call causes the default values inherited from the owning DDSDomainParticipant to be overridden.

This default value will be used for newly created DDSDataReader if DDS_DATAREADER_QOS_DEFAULT is specified as the qos parameter when DDSSubscriber::create_datareader is called.

Precondition
The specified QoS policies must be consistent, or else the operation will have no effect and fail with DDS_RETCODE_INCONSISTENT_POLICY
MT Safety:
UNSAFE. It is not safe to set the default QoS value from a subscriber while another thread may be simultaneously calling DDSSubscriber::set_default_datareader_qos, DDSSubscriber::get_default_datareader_qos or calling DDSSubscriber::create_datareader with DDS_DATAREADER_QOS_DEFAULT as the qos parameter.
Parameters
qos<<in>> The default DDS_DataReaderQos to be set to. The special value DDS_DATAREADER_QOS_DEFAULT may be passed as qos to indicate that the default QoS should be reset back to the initial values the factory would used if DDSSubscriber::set_default_datareader_qos had never been called.
Returns
One of the Standard Return Codes, or or DDS_RETCODE_INCONSISTENT_POLICY
virtual DDS_ReturnCode_t DDSSubscriber::set_default_datareader_qos_with_profile ( const char *  library_name,
const char *  profile_name 
)
pure virtual

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

This default value will be used for newly created DDSDataReader if DDS_DATAREADER_QOS_DEFAULT is specified as the qos parameter when DDSSubscriber::create_datareader is called.

Precondition
The DDS_DataReaderQos contained in the specified XML QoS profile must be consistent, or else the operation will have no effect and fail with DDS_RETCODE_INCONSISTENT_POLICY
MT Safety:
UNSAFE. It is not safe to set the default QoS value from a DDSSubscriber while another thread may be simultaneously calling DDSSubscriber::set_default_datareader_qos, DDSSubscriber::get_default_datareader_qos or calling DDSSubscriber::create_datareader with DDS_DATAREADER_QOS_DEFAULT as the qos parameter.
Parameters
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSSubscriber::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSSubscriber::set_default_profile).

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

Returns
One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY
See Also
DDS_DATAREADER_QOS_DEFAULT
DDSSubscriber::create_datareader_with_profile
virtual DDS_ReturnCode_t DDSSubscriber::set_default_library ( const char *  library_name)
pure virtual

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

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

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

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

Parameters
library_name<<in>> Library name. If library_name is null any previous default is unset.
Returns
One of the Standard Return Codes
See Also
DDSSubscriber::get_default_library
virtual const char* DDSSubscriber::get_default_library ( )
pure virtual

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

Returns
The default library or null if the default library was not set.
See Also
DDSSubscriber::set_default_library
virtual DDS_ReturnCode_t DDSSubscriber::set_default_profile ( const char *  library_name,
const char *  profile_name 
)
pure virtual

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

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

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

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

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

Parameters
library_name<<in>> The library name containing the profile.
profile_name<<in>> The profile name. If profile_name is null any previous default is unset.
Returns
One of the Standard Return Codes
See Also
DDSSubscriber::get_default_profile
DDSSubscriber::get_default_profile_library
virtual const char* DDSSubscriber::get_default_profile ( )
pure virtual

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

Returns
The default profile or null if the default profile was not set.
See Also
DDSSubscriber::set_default_profile
virtual const char* DDSSubscriber::get_default_profile_library ( )
pure virtual

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

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

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

Returns
The default profile library or null if the default profile was not set.
See Also
DDSSubscriber::set_default_profile
virtual DDSDataReader* DDSSubscriber::create_datareader ( DDSTopicDescription topic,
const DDS_DataReaderQos qos,
DDSDataReaderListener listener,
DDS_StatusMask  mask 
)
pure virtual

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

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

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

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

MT Safety:
UNSAFE. If DDS_DATAREADER_QOS_DEFAULT is used for the qos parameter, it is not safe to create the datareader while another thread may be simultaneously calling DDSSubscriber::set_default_datareader_qos.
Precondition
If subscriber is enabled, the topic must be enabled. If it is not, this operation will fail and no DDSDataReader will be created.
The given DDSTopicDescription must have been created from the same participant as this subscriber. If it was created from a different participant, this method will return NULL.
If qos is DDS_DATAREADER_QOS_USE_TOPIC_QOS, topic cannot be DDSMultiTopic, or else this method will return NULL.
Parameters
topic<<in>> The DDSTopicDescription that the DDSDataReader will be associated with. Cannot be NULL.
qos<<in>> The qos of the DDSDataReader. The special value DDS_DATAREADER_QOS_DEFAULT can be used to indicate that the DDSDataReader should be created with the default DDS_DataReaderQos set in the DDSSubscriber. If DDSTopicDescription is of type DDSTopic or DDSContentFilteredTopic, the special value DDS_DATAREADER_QOS_USE_TOPIC_QOS can be used to indicate that the DDSDataReader should be created with the combination of the default DDS_DataReaderQos set on the DDSSubscriber and the DDS_TopicQos (in the case of a DDSContentFilteredTopic, the DDS_TopicQos of the related DDSTopic). if DDS_DATAREADER_QOS_USE_TOPIC_QOS is used, topic cannot be a DDSMultiTopic.
listener<<in>> The listener of the DDSDataReader.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
A DDSDataReader of a derived class specific to the data-type associated with the DDSTopic or NULL if an error occurred.
See Also
FooDataReader
Specifying QoS on entities for information on setting QoS before entity creation
DDS_DataReaderQos for rules on consistency among QoS
DDSSubscriber::create_datareader_with_profile
DDSSubscriber::get_default_datareader_qos
DDSTopic::set_qos
DDSSubscriber::copy_from_topic_qos
DDSDataReader::set_listener
Examples:
HelloWorld_subscriber.cxx.
virtual DDSDataReader* DDSSubscriber::create_datareader_with_profile ( DDSTopicDescription topic,
const char *  library_name,
const char *  profile_name,
DDSDataReaderListener listener,
DDS_StatusMask  mask 
)
pure virtual

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

The DDSDataReader will be attached and belong to the DDSSubscriber.

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

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

Precondition
If subscriber is enabled, the topic must be enabled. If it is not, this operation will fail and no DDSDataReader will be created.
The given DDSTopicDescription must have been created from the same participant as this subscriber. If it was created from a different participant, this method will return NULL.
Parameters
topic<<in>> The DDSTopicDescription that the DDSDataReader will be associated with. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSSubscriber::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSSubscriber::set_default_profile).
listener<<in>> The listener of the DDSDataReader.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
A DDSDataReader of a derived class specific to the data-type associated with the DDSTopic or NULL if an error occurred.
See Also
FooDataReader
Specifying QoS on entities for information on setting QoS before entity creation
DDS_DataReaderQos for rules on consistency among QoS
DDS_DATAREADER_QOS_DEFAULT
DDS_DATAREADER_QOS_USE_TOPIC_QOS
DDSSubscriber::create_datareader
DDSSubscriber::get_default_datareader_qos
DDSTopic::set_qos
DDSSubscriber::copy_from_topic_qos
DDSDataReader::set_listener
virtual DDS_ReturnCode_t DDSSubscriber::delete_datareader ( DDSDataReader a_datareader)
pure virtual

Deletes a DDSDataReader that belongs to the DDSSubscriber.

Precondition
If the DDSDataReader does not belong to the DDSSubscriber, or if ther are any existing DDSReadCondition or DDSQueryCondition objects that are attached to the DDSDataReader, or if there are outstanding loans on samples (as a result of a call to read(), take(), or one of the variants thereof), the operation fails with the error DDS_RETCODE_PRECONDITION_NOT_MET.
Postcondition
Listener installed on the DDSDataReader will not be called after this method completes successfully.
MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
Parameters
a_datareader<<in>> The DDSDataReader to be deleted.
Returns
One of the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET.
virtual DDS_ReturnCode_t DDSSubscriber::delete_contained_entities ( )
pure virtual

Deletes all the entities that were created by means of the "create" operation on the DDSSubscriber.

Deletes all contained DDSDataReader objects. This pattern is applied recursively. In this manner, the operation DDSSubscriber::delete_contained_entities on the DDSSubscriber will end up deleting all the entities recursively contained in the DDSSubscriber, that is also the DDSQueryCondition and DDSReadCondition objects belonging to the contained DDSDataReader.

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

Once DDSSubscriber::delete_contained_entities completes successfully, the application may delete the DDSSubscriber, knowing that it has no contained DDSDataReader objects.

MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
Returns
One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET
virtual DDSDataReader* DDSSubscriber::lookup_datareader ( const char *  topic_name)
pure virtual

Retrieves an existing DDSDataReader.

Use this operation on the built-in DDSSubscriber (Built-in Topics) to access the built-in DDSDataReader entities for the built-in topics.

The built-in DDSDataReader is created when this operation is called on a built-in topic for the first time. The built-in DDSDataReader is deleted automatically when the DDSDomainParticipant is deleted.

To ensure that builtin DDSDataReader entities receive all the discovery traffic, it is suggested that you lookup the builtin DDSDataReader before the DDSDomainParticipant is enabled. Looking up builtin DDSDataReader may implicitly register builtin transports due to creation of DDSDataReader (see Built-in Transport Plugins for details on when a builtin transport is registered). Therefore, if you are want to modify builtin transport properties, do so before using this operation.

Therefore the suggested sequence when looking up builtin DataReaders is:

Parameters
topic_name<<in>> Name of the DDSTopicDescription that the retrieved DDSDataReader is attached to. Cannot be NULL.
Returns
A DDSDataReader that belongs to the DDSSubscriber attached to the DDSTopicDescription with topic_name. If no such DDSDataReader exists, this operation returns NULL.

The returned DDSDataReader may be enabled or disabled.

If more than one DDSDataReader is attached to the DDSSubscriber, this operation may return any one of them.

MT Safety:
UNSAFE. It is not safe to lookup a DDSDataReader in one thread while another thread is simultaneously creating or destroying that DDSDataReader.
virtual DDS_ReturnCode_t DDSSubscriber::begin_access ( )
pure virtual

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

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

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

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

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

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

Returns
One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.
See Also
Access to data samples
DDSSubscriber::get_datareaders
PRESENTATION
virtual DDS_ReturnCode_t DDSSubscriber::end_access ( )
pure virtual

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

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

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

Returns
One of the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_NOT_ENABLED.
virtual DDS_ReturnCode_t DDSSubscriber::get_datareaders ( DDSDataReaderSeq readers,
DDS_SampleStateMask  sample_states,
DDS_ViewStateMask  view_states,
DDS_InstanceStateMask  instance_states 
)
pure virtual

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

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

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

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

Parameters
readers<<inout>> a DDSDataReaderSeq object where the set or list of readers will be returned.
sample_states<<in>> the returned DataReader must contain samples that have one of these sample_states.
view_states<<in>> the returned DataReader must contain samples that have one of these view_states.
instance_states<<in>> the returned DataReader must contain samples that have one of these instance_states.
Returns
One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.
See Also
Access to data samples
DDSSubscriber::begin_access
DDSSubscriber::end_access
PRESENTATION
virtual DDS_ReturnCode_t DDSSubscriber::get_all_datareaders ( DDSDataReaderSeq readers)
pure virtual

Retrieve all the DataReaders created from this Subscriber.

Parameters
readers<<inout>> Sequence where the DataReaders will be added
Returns
One of the Standard Return Codes
virtual DDS_ReturnCode_t DDSSubscriber::notify_datareaders ( )
pure virtual

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

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

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

Returns
One of the Standard Return Codes, or DDS_RETCODE_NOT_ENABLED.
virtual DDSDomainParticipant* DDSSubscriber::get_participant ( )
pure virtual

Returns the DDSDomainParticipant to which the DDSSubscriber belongs.

Returns
the DDSDomainParticipant to which the DDSSubscriber belongs.
virtual DDS_ReturnCode_t DDSSubscriber::copy_from_topic_qos ( DDS_DataReaderQos datareader_qos,
const DDS_TopicQos topic_qos 
)
pure virtual

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

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

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

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

Parameters
datareader_qos<<inout>> DDS_DataReaderQos to be filled-up.
topic_qos<<in>> DDS_TopicQos to be merged with DDS_DataReaderQos.
Returns
One of the Standard Return Codes
virtual DDS_ReturnCode_t DDSSubscriber::set_qos ( const DDS_SubscriberQos qos)
pure virtual

Sets the subscriber QoS.

This operation modifies the QoS of the DDSSubscriber.

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

Parameters
qos<<in>> DDS_SubscriberQos to be set to. Policies must be consistent. Immutable policies cannot be changed after DDSSubscriber is enabled. The special value DDS_SUBSCRIBER_QOS_DEFAULT can be used to indicate that the QoS of the DDSSubscriber should be changed to match the current default DDS_SubscriberQos set in the DDSDomainParticipant.
Returns
One of the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY, or DDS_RETCODE_INCONSISTENT_POLICY.
See Also
DDS_SubscriberQos for rules on consistency among QoS
set_qos (abstract)
Operations Allowed in Listener Callbacks
virtual DDS_ReturnCode_t DDSSubscriber::set_qos_with_profile ( const char *  library_name,
const char *  profile_name 
)
pure virtual

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

This operation modifies the QoS of the DDSSubscriber.

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

Parameters
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSSubscriber::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSSubscriber::set_default_profile).
Returns
One of the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY, or DDS_RETCODE_INCONSISTENT_POLICY.
See Also
DDS_SubscriberQos for rules on consistency among QoS
Operations Allowed in Listener Callbacks
virtual DDS_ReturnCode_t DDSSubscriber::get_qos ( DDS_SubscriberQos qos)
pure virtual

Gets the subscriber QoS.

This method may potentially allocate memory depending on the sequences contained in some QoS policies.

Parameters
qos<<in>> DDS_SubscriberQos to be filled in.
Returns
One of the Standard Return Codes
See Also
get_qos (abstract)
virtual DDS_ReturnCode_t DDSSubscriber::set_listener ( DDSSubscriberListener l,
DDS_StatusMask  mask = DDS_STATUS_MASK_ALL 
)
pure virtual

Sets the subscriber listener.

Parameters
l<<in>> DDSSubscriberListener to set to.
mask<<in>> DDS_StatusMask associated with the DDSSubscriberListener.
Returns
One of the Standard Return Codes
See Also
set_listener (abstract)
virtual DDSSubscriberListener* DDSSubscriber::get_listener ( )
pure virtual

Get the subscriber listener.

Returns
DDSSubscriberListener of the DDSSubscriber.
See Also
get_listener (abstract)
virtual DDSDataReader* DDSSubscriber::lookup_datareader_by_name ( const char *  datareader_name)
pure virtual

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

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

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

Parameters
datareader_name<<in>> Entity name of the DDSDataReader.
Returns
The first DDSDataReader found with the specified name or NULL if it is not found.
See Also
DDSDomainParticipant::lookup_datareader_by_name

RTI Connext Traditional C++ API Version 6.0.0 Copyright © Sun Mar 3 2019 Real-Time Innovations, Inc